Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

158 KB
Raw Blame
from __future__ import annotations

import asyncio
import email.utils
import inspect
import json
import logging
import math
import re
import secrets
import threading
import urllib.parse
import uuid
from dataclasses import dataclass, field, replace
from datetime import datetime, timedelta, timezone
from enum import Enum
from typing import Any, Awaitable, Callable, Literal, Mapping, Sequence, TypeVar

import aiohttp
import config.v2_config as model_hub_config
from config.v2_config import (
    KEYLESS_EXA_SERVICE_ID,
    KEYLESS_EXA_SOURCE_ID,
    normalize_model_hub_base_url,
)
from core.agent_core.ai._common import PROVIDER_SILENCE_TIMEOUT_S
from core.handlers.model_hub.adapter import (
    DiscoveredModel,
    EngineEnsureResult,
    EngineHealth,
    EngineStatus,
    ObservationDiscovery,
    ObservationOutcome,
    OAuthFlowState,
    OAuthSubmissionRejectedError,
    OriginNotAllowedError,
    RawCallOutcome,
    RawOutcomeKind,
    RetainedMaterialDisposition,
    RuntimePlatformUnsupportedError,
    SearchCredentialCheck,
    SearchResponse,
    MODEL_PROTOCOLS,
    SourceObservation,
    SourceBinding,
    make_source_observation,
)
from core.handlers.model_hub.errors import ModelDiscoveryError
from core.handlers.model_hub.oauth import oauth_failure_detail
from core.handlers.model_hub.identifiers import model_id_without_credential_address
from core.handlers.model_hub.quota import (
    CLAUDE_PLAN_FETCH_TIMEOUT_SECONDS,
    QUOTA_FETCH_TIMEOUT_SECONDS,
    SubscriptionQuotaError,
    parse_claude_plan,
    parse_subscription_quota,
)
from core.handlers.model_hub.async_owner import run_owned_in_thread
from core.os_errors import local_os_errno
from vibe.model_hub_runtime.client import (
    _OFFICIAL_BASE_URLS,
    EngineClient,
    EngineClientError,
    EngineInvokeHandle,
    completed_handle,
    engine_disowned_call,
    probe_models,
    upstream_api_url,
)
from vibe import __version__ as AVIBE_VERSION
from vibe.model_hub_runtime.api_key_vendors import (
    anthropic_api_key_header,
    pinned_api_key_protocol,
    search_service,
    validate_api_key_auth_scheme,
)
from vibe.model_hub_runtime.keyless_exa_mcp import KeylessExaMcpClient
from vibe.model_hub_runtime.installer import (
    INSTALL_ALREADY_RUNNING_REASON,
    INSTALL_PLATFORM_UNSUPPORTED_REASON,
    INSTALL_RECOVERY_ABANDONED_REASON,
    INSTALL_RECOVERY_SCHEDULE_FAILED_REASON,
    INSTALL_RECOVERY_TIMEOUT_REASON,
    InstallClaimTransition,
)
from vibe.model_hub_runtime.state import EngineStateError, EngineStateStore
from vibe.model_hub_runtime.supervisor import (
    EngineConfigLostError,
    EngineSupervisor,
    EngineUnavailableError,
    get_engine_supervisor,
)


_T = TypeVar("_T")

# The subscription vendors the engine can start an OAuth flow for, and the three
# names each one answers to on the way through it:
#
#   management endpoint  where the start request goes
#   callback provider    the name `POST /oauth-callback` accepts for the session
#                        the start registered, for the vendors that take one
#   auth provider        the `provider` the finished grant carries in
#                        `GET /auth-files`, which is how a flow finds its own
#
# The three can differ for one vendor — Claude starts at `/anthropic-auth-url`,
# answers a callback as `anthropic`, and lands as `claude` — so none of them is
# derivable from the Avibe vendor id, and each row states all three. What the
# flow *asks of the user* is not in here: it is read from the start response,
# which is the only thing that knows whether this vendor issued a device code or
# expects a redirect URL back.
_OAUTH_ENDPOINTS = {
    "anthropic": ("/anthropic-auth-url", "anthropic", "claude"),
    "openai": ("/codex-auth-url", "codex", "codex"),
    "codex": ("/codex-auth-url", "codex", "codex"),
    "gemini": ("/antigravity-auth-url", "antigravity", "antigravity"),
    "kimi": ("/kimi-auth-url", "kimi", "kimi"),
    "xai": ("/xai-auth-url", "xai", "xai"),
}


# The local surface the pinned engine serves a hub-held subscription on.
#
# A subscription's protocol is not a fact about the vendor's public API — it is a
# fact about how the engine that holds the credential exposes it to us, the same
# kind of shipped product knowledge as `vibe/data/api_key_vendors.json`. It is
# stated for the vendors whose grant no response probe can reach: the credential
# never leaves the engine, and the upstream behind it is the vendor's CLI plane
# rather than an endpoint Avibe may synthesize a request against.
#
# Read from the engine at the commit `cliproxyapi_manifest.json` pins
# (v7.3.16, `c404af96`); each row is one of its serving surfaces, not a guess:
#
#   gemini  `internal/translator/antigravity/openai/chat-completions/init.go:9`
#           registers `translator.Register(OpenAI, Antigravity, ...)`, so an
#           OpenAI-chat request is translated to the antigravity upstream at
#           `cloudcode-pa.googleapis.com/v1internal:generateContent`.
#   kimi    `internal/runtime/executor/kimi_executor.go:54` reports
#           `FormatOpenAI` from `RequestToFormat`, `:119` translates to
#           `openai`, and `:150` calls the upstream's `/v1/chat/completions`.
#   xai     `internal/runtime/executor/xai_executor_request.go:517` accepts
#           `FormatOpenAI` and folds its output controls into the Responses body
#           the executor sends to `/responses`
#           (`internal/runtime/executor/xai_executor_execute.go:45`).
#
# All three land on `openai_chat`. This table is not required to agree with
# `vibe/data/api_key_vendors.json`, and for `xai` it no longer does: that catalog
# pins the protocol Avibe speaks to a vendor's *public* API with a key it holds,
# while this one names the surface the engine serves a credential it holds
# itself. The engine reaches xAI's Responses API from either, so the api-key
# channel is pinned to the surface OpenAI is steering the ecosystem toward and
# this one keeps the surface the shipped grant path was verified on.
_HUB_SUBSCRIPTION_PROTOCOLS = {
    "gemini": "openai_chat",
    "kimi": "openai_chat",
    "xai": "openai_chat",
}
_SEARCH_BODY_MAX_BYTES = 8 * 1024 * 1024
_SEARCH_TIMEOUT_SECONDS = 30.0
_SEARCH_CHECK_TIMEOUT_SECONDS = 10.0
_SEARCH_CHECK_CONNECT_TIMEOUT_SECONDS = 5.0
_SEARCH_RESPONSE_HEADERS = frozenset({"content-type", "retry-after", "x-ratelimit-reset", "date", "content-length"})


async def _read_bounded_search_body(content: Any) -> tuple[bytes | None, bool]:
    """Read a response to EOF while stopping as soon as the cap is exceeded."""
    chunks: list[bytes] = []
    total = 0
    async for chunk in content.iter_chunked(64 * 1024):
        data = bytes(chunk)
        total += len(data)
        if total > _SEARCH_BODY_MAX_BYTES:
            return None, True
        chunks.append(data)
    return b"".join(chunks), False


def _search_check_matches(body: object, rule: Mapping[str, Any]) -> bool:
    if rule.get("status") is not None:
        # Status is checked by the caller; keep this predicate about body facts.
        pass
    path = rule.get("path")
    if path is None:
        return True
    current: object = body
    for part in str(path).split("."):
        if not isinstance(current, Mapping) or part not in current:
            return False
        current = current[part]
    return current == rule.get("equals")


def _search_limit_outcome(body: object, rule: Mapping[str, Any]) -> Literal["pass", "limit", "unknown"]:
    """Classify complete Tavily usage/limit pairs; the account section is optional."""
    pairs = rule.get("pairs")
    if not isinstance(pairs, list) or not isinstance(body, Mapping):
        return "unknown"
    if any(name in body and not isinstance(body[name], Mapping) for name in ("key", "account")):
        return "unknown"
    missing = object()
    values: dict[str, tuple[float, float | None] | None] = {
        "key": None,
        "plan": None,
        "paygo": None,
    }
    paths = {
        "key": ("key.usage", "key.limit"),
        "plan": ("account.plan_usage", "account.plan_limit"),
        "paygo": ("account.paygo_usage", "account.paygo_limit"),
    }
    for pair in pairs:
        if not isinstance(pair, Mapping):
            return "unknown"
        usage_path = pair.get("usage")
        limit_path = pair.get("limit")
        if not isinstance(usage_path, str) or not isinstance(limit_path, str):
            return "unknown"
        role = next(
            (
                name
                for name, expected in paths.items()
                if expected == (usage_path, limit_path)
            ),
            None,
        )
        if role is None:
            return "unknown"
        usage: object = body
        limit: object = body
        for part in usage_path.split("."):
            if not isinstance(usage, Mapping) or part not in usage:
                usage = missing
                break
            usage = usage[part]
        for part in limit_path.split("."):
            if not isinstance(limit, Mapping) or part not in limit:
                limit = missing
                break
            limit = limit[part]
        if usage is missing and limit is missing:
            continue
        if (
            usage is missing
            or isinstance(usage, bool)
            or not isinstance(usage, (int, float))
            or not math.isfinite(float(usage))
        ):
            return "unknown"
        if role == "key" and limit is None:
            values[role] = (float(usage), None)
            continue
        if (
            limit is missing
            or isinstance(limit, bool)
            or not isinstance(limit, (int, float))
            or not math.isfinite(float(limit))
        ):
            return "unknown"
        values[role] = (float(usage), float(limit))

    if not any(value is not None for value in values.values()):
        return "unknown"
    key = values["key"]
    plan = values["plan"]
    paygo = values["paygo"]
    if key is not None and key[1] is not None and key[0] >= key[1]:
        return "limit"
    if plan is None and paygo is None:
        # A valid key pair with headroom authenticates the key even when
        # account usage is absent; the first search confirms payment.
        return "pass"
    key_has_headroom = key is None or key[1] is None or key[0] < key[1]
    account_has_headroom = (
        (plan is not None and plan[0] < plan[1])
        or (paygo is not None and paygo[0] < paygo[1])
    )
    return "pass" if key_has_headroom and account_has_headroom else "limit"
_INSTALL_RECOVERY_WAIT_SECONDS = 30.0
_INSTALL_RECOVERY_INITIAL_DELAY_SECONDS = 0.25
_INSTALL_RECOVERY_MAX_DELAY_SECONDS = 4.0
# The engine answers a credential's model list from memory.
_ENGINE_MODEL_LISTING_TIMEOUT_SECONDS = 5.0


logger = logging.getLogger(__name__)


class _ProtocolProof(Enum):
    PROVEN = "proven"
    UNPROVEN = "unproven"


class _AuthenticationEvidence(Enum):
    ACCEPTED = "accepted"
    REJECTED = "rejected"
    UNKNOWN = "unknown"


class _ProtocolObservationShape(Enum):
    NONE = "none"
    GENERIC_REQUEST_ERROR = "generic_request_error"
    HTTP_404 = "http_404"
    NON_JSON = "non_json"
    UNSTRUCTURED = "unstructured"


@dataclass(frozen=True)
class _ProtocolEvidence:
    protocol: _ProtocolProof
    authentication: _AuthenticationEvidence
    shape: _ProtocolObservationShape = _ProtocolObservationShape.NONE
    status: int | None = field(default=None, compare=False)


# What a finished hub subscription grant establishes on its own.
#
# The engine accepted the credential — that is what completing the grant means —
# so authentication is `ACCEPTED`. It says nothing about which protocol, because
# no request was made: `_HUB_SUBSCRIPTION_PROTOCOLS` supplies that instead, so
# the proof stays `UNPROVEN` and there is no response shape to record.
_ENGINE_SERVED_SUBSCRIPTION_EVIDENCE = _ProtocolEvidence(
    protocol=_ProtocolProof.UNPROVEN,
    authentication=_AuthenticationEvidence.ACCEPTED,
    shape=_ProtocolObservationShape.NONE,
)


@dataclass(frozen=True)
class _ProtocolEvidenceRule:
    statuses: frozenset[int]
    protocol: _ProtocolProof
    authentication: _AuthenticationEvidence
    shape: _ProtocolObservationShape = _ProtocolObservationShape.NONE
    top_level_field: str | None = None
    top_level_values: frozenset[str] = frozenset()
    error_identifiers: frozenset[str] = frozenset()
    error_params: frozenset[str] | None = None

    def matches(self, status: int, payload: Mapping[str, Any]) -> bool:
        if status not in self.statuses:
            return False
        if self.top_level_field is not None:
            value = payload.get(self.top_level_field)
            if not isinstance(value, str) or value.strip().lower() not in self.top_level_values:
                return False
        error = payload.get("error")
        if self.error_identifiers or self.error_params is not None:
            if not isinstance(error, dict):
                return False
        if self.error_identifiers:
            identifiers = {
                value.strip().lower() for value in (error.get("type"), error.get("code")) if isinstance(value, str)
            }
            if self.error_identifiers.isdisjoint(identifiers):
                return False
        if self.error_params is not None and error.get("param") not in self.error_params:
            return False
        return True


@dataclass(frozen=True)
class _ProtocolObservationTaxonomy:
    """One protocol's request shape and response evidence table.

    The request path and body are part of the same authority as the response
    taxonomy. Every probe omits ``model`` so observation does not request model
    scheduling. Schema validation never proves authentication, regardless of
    whether the interface has a catalog owner or a user declaration.
    """

    request_path: str
    request_body: Mapping[str, Any]
    oauth_path: str | None
    evidence_rules: tuple[_ProtocolEvidenceRule, ...]


_SUCCESS_STATUSES = frozenset(range(200, 300))
_REQUEST_ERROR_STATUSES = frozenset({400, 404, 422})
_AUTHENTICATION_ERROR_STATUSES = frozenset({401, 403})
_RATE_LIMIT_STATUSES = frozenset({429})
_SERVER_ERROR_STATUSES = frozenset(range(500, 600))

_REQUEST_ERROR_IDENTIFIERS = frozenset(
    {
        "invalid_parameter",
        "invalid_request_error",
        "validation_error",
    }
)
_MODEL_ERROR_IDENTIFIERS = frozenset({"model_not_found", "not_found_error"})
_AUTHENTICATION_ERROR_IDENTIFIERS = frozenset({"authentication_error", "invalid_api_key", "permission_error"})
_REFRESH_INVALIDATION_IDENTIFIERS = frozenset(
    {
        "invalid_grant",
        "refresh_token_expired",
        "refresh_token_invalid",
        "refresh_token_invalidated",
        "refresh_token_revoked",
        "refresh_token_reused",
    }
)
_SERVER_ERROR_IDENTIFIERS = frozenset({"api_error", "internal_error", "overloaded", "overloaded_error", "server_error"})
_RATE_LIMIT_ERROR_IDENTIFIERS = frozenset({"rate_limit_error", "rate_limit_exceeded"})

_OPENAI_RESPONSES_PARAMS = frozenset(
    {
        "input",
        "instructions",
        "max_output_tokens",
        "previous_response_id",
        "reasoning",
        "text",
        "truncation",
    }
)
_OPENAI_CHAT_PARAMS = frozenset(
    {
        "messages",
        "max_completion_tokens",
        "max_tokens",
        "response_format",
        "stop",
        "temperature",
        "tool_choice",
        "top_p",
    }
)
_OPENAI_FAMILY_PROTOCOLS = frozenset({"openai_responses", "openai_chat"})
_OPENAI_FAMILY_PARAMS = _OPENAI_RESPONSES_PARAMS | _OPENAI_CHAT_PARAMS
_CREDENTIAL_ERROR_PARAMS = frozenset(
    {
        "api_key",
        "api-key",
        "access_token",
        "access-token",
        "authorization",
        "auth",
        "auth_token",
        "auth-token",
        "bearer_token",
        "bearer-token",
        "token",
        "x-api-key",
        "x_api_key",
        "x-auth-token",
        "x_auth_token",
        "x-token",
    }
)
_CREDENTIAL_ERROR_MESSAGE_TOKENS = frozenset(
    {
        "authentication",
        "auth_failed",
        "invalid_api_key",
        "api_key_not_valid",
        "missing_api_key",
        "no_api_key",
        "unauthorized",
    }
)
_PAIRWISE_EXCLUSION_SHAPES = frozenset(
    {
        _ProtocolObservationShape.HTTP_404,
        _ProtocolObservationShape.NON_JSON,
        _ProtocolObservationShape.UNSTRUCTURED,
    }
)
_IDENTIFIER_SEPARATOR_RE = re.compile(r"[^0-9A-Za-z]+")
_CAMEL_CASE_BOUNDARY_RE = re.compile(r"(?<=[0-9a-z])(?=[A-Z])")


def _openai_evidence_rules(
    success_objects: frozenset[str],
    request_params: frozenset[str],
) -> tuple[_ProtocolEvidenceRule, ...]:
    return (
        _ProtocolEvidenceRule(
            statuses=_SUCCESS_STATUSES,
            top_level_field="object",
            top_level_values=success_objects,
            protocol=_ProtocolProof.PROVEN,
            authentication=_AuthenticationEvidence.ACCEPTED,
        ),
        _ProtocolEvidenceRule(
            statuses=_REQUEST_ERROR_STATUSES,
            error_identifiers=_REQUEST_ERROR_IDENTIFIERS,
            error_params=request_params,
            protocol=_ProtocolProof.PROVEN,
            authentication=_AuthenticationEvidence.UNKNOWN,
        ),
        _ProtocolEvidenceRule(
            statuses=_REQUEST_ERROR_STATUSES,
            error_identifiers=_MODEL_ERROR_IDENTIFIERS,
            protocol=_ProtocolProof.UNPROVEN,
            authentication=_AuthenticationEvidence.UNKNOWN,
            shape=_ProtocolObservationShape.GENERIC_REQUEST_ERROR,
        ),
        _ProtocolEvidenceRule(
            statuses=_AUTHENTICATION_ERROR_STATUSES,
            error_params=request_params,
            protocol=_ProtocolProof.PROVEN,
            authentication=_AuthenticationEvidence.REJECTED,
        ),
        _ProtocolEvidenceRule(
            statuses=_AUTHENTICATION_ERROR_STATUSES,
            error_identifiers=_AUTHENTICATION_ERROR_IDENTIFIERS,
            protocol=_ProtocolProof.UNPROVEN,
            authentication=_AuthenticationEvidence.REJECTED,
        ),
        _ProtocolEvidenceRule(
            statuses=_SERVER_ERROR_STATUSES,
            error_identifiers=_SERVER_ERROR_IDENTIFIERS,
            protocol=_ProtocolProof.PROVEN,
            authentication=_AuthenticationEvidence.UNKNOWN,
        ),
        _ProtocolEvidenceRule(
            statuses=_RATE_LIMIT_STATUSES,
            error_identifiers=_RATE_LIMIT_ERROR_IDENTIFIERS,
            protocol=_ProtocolProof.PROVEN,
            authentication=_AuthenticationEvidence.UNKNOWN,
        ),
    )


# Omit the model so observation stops at request validation, before a relay
# schedules upstream capacity or applies model-specific availability limits.
_PROTOCOL_OBSERVATION_TAXONOMY = {
    "anthropic": _ProtocolObservationTaxonomy(
        request_path="/v1/messages",
        request_body={
            # Fail schema validation before a relay selects a model. A synthetic
            # model can otherwise surface as an availability failure even when
            # the credential and interface are valid.
            "max_tokens": 0,
            "messages": [],
        },
        oauth_path="/v1/messages?beta=true",
        evidence_rules=(
            _ProtocolEvidenceRule(
                statuses=_SUCCESS_STATUSES,
                top_level_field="type",
                top_level_values=frozenset({"message"}),
                protocol=_ProtocolProof.PROVEN,
                authentication=_AuthenticationEvidence.ACCEPTED,
            ),
            _ProtocolEvidenceRule(
                statuses=_REQUEST_ERROR_STATUSES,
                top_level_field="type",
                top_level_values=frozenset({"error"}),
                error_identifiers=_REQUEST_ERROR_IDENTIFIERS | _MODEL_ERROR_IDENTIFIERS,
                protocol=_ProtocolProof.PROVEN,
                authentication=_AuthenticationEvidence.UNKNOWN,
            ),
            _ProtocolEvidenceRule(
                statuses=_AUTHENTICATION_ERROR_STATUSES,
                top_level_field="type",
                top_level_values=frozenset({"error"}),
                error_identifiers=_AUTHENTICATION_ERROR_IDENTIFIERS,
                protocol=_ProtocolProof.PROVEN,
                authentication=_AuthenticationEvidence.REJECTED,
            ),
            _ProtocolEvidenceRule(
                statuses=_SERVER_ERROR_STATUSES,
                top_level_field="type",
                top_level_values=frozenset({"error"}),
                error_identifiers=_SERVER_ERROR_IDENTIFIERS,
                protocol=_ProtocolProof.PROVEN,
                authentication=_AuthenticationEvidence.UNKNOWN,
            ),
            _ProtocolEvidenceRule(
                statuses=_RATE_LIMIT_STATUSES,
                top_level_field="type",
                top_level_values=frozenset({"error"}),
                error_identifiers=_RATE_LIMIT_ERROR_IDENTIFIERS,
                protocol=_ProtocolProof.PROVEN,
                authentication=_AuthenticationEvidence.UNKNOWN,
            ),
        ),
    ),
    "openai_responses": _ProtocolObservationTaxonomy(
        request_path="/v1/responses",
        request_body={},
        oauth_path="/backend-api/codex/responses",
        evidence_rules=_openai_evidence_rules(
            frozenset({"response"}),
            _OPENAI_RESPONSES_PARAMS,
        ),
    ),
    "openai_chat": _ProtocolObservationTaxonomy(
        request_path="/v1/chat/completions",
        request_body={},
        oauth_path=None,
        evidence_rules=_openai_evidence_rules(
            frozenset({"chat.completion", "chat.completion.chunk"}),
            _OPENAI_CHAT_PARAMS,
        ),
    ),
}


def _error_identifiers(error: Mapping[str, Any]) -> frozenset[str]:
    return _payload_identifiers(error)


def _normalized_identifier(value: str) -> str:
    normalized = _CAMEL_CASE_BOUNDARY_RE.sub("_", value.strip())
    normalized = _IDENTIFIER_SEPARATOR_RE.sub("_", normalized).strip("_").lower()
    return normalized


def _payload_identifiers(payload: Mapping[str, Any]) -> frozenset[str]:
    return frozenset(
        normalized
        for value in (payload.get("type"), payload.get("code"))
        if isinstance(value, str)
        if (normalized := _normalized_identifier(value))
    )


def _error_param_name(error: Mapping[str, Any]) -> str | None:
    value = error.get("param")
    if not isinstance(value, str):
        return None
    normalized = value.strip().lower()
    return normalized or None


def _error_message_indicates_credential_rejection(message: object) -> bool:
    if not isinstance(message, str) or not message.strip():
        return False
    normalized = _normalized_identifier(message)
    return any(token in normalized for token in _CREDENTIAL_ERROR_MESSAGE_TOKENS)


def _request_error_rejects_credential(
    status: int,
    error: Mapping[str, Any] | None,
) -> bool:
    return (
        status in _REQUEST_ERROR_STATUSES
        and isinstance(error, dict)
        and (
            _error_param_name(error) in _CREDENTIAL_ERROR_PARAMS
            or not _AUTHENTICATION_ERROR_IDENTIFIERS.isdisjoint(_error_identifiers(error))
            or _error_message_indicates_credential_rejection(error.get("message"))
        )
    )


def _oauth_rejection_is_definitive(
    status: int,
    payload: Mapping[str, Any],
) -> bool:
    """Recognize refresh-invalidating words, but not access-token expiry.

    This helper is intentionally not sufficient on its own for takeover
    validation: the protocol probe is an upstream request, not a refresh
    endpoint. The pinned CPA inventory does not expose refresh provenance and
    cannot turn these words into an authoritative grant-rejection verdict.
    """

    if status not in {*_REQUEST_ERROR_STATUSES, *_AUTHENTICATION_ERROR_STATUSES}:
        return False
    identifiers = set(_payload_identifiers(payload))
    error = payload.get("error")
    if isinstance(error, dict):
        identifiers.update(_error_identifiers(error))
        message = _normalized_identifier(str(error.get("message") or ""))
        if any(token in message for token in _REFRESH_INVALIDATION_IDENTIFIERS):
            return True
    return not _REFRESH_INVALIDATION_IDENTIFIERS.isdisjoint(identifiers)


def _payload_is_structured(payload: Mapping[str, Any]) -> bool:
    return (
        isinstance(payload.get("error"), dict)
        or isinstance(payload.get("type"), str)
        or isinstance(payload.get("code"), str)
        or isinstance(payload.get("object"), str)
    )


def _anthropic_wrapperless_error_kind(
    status: int,
    payload: Mapping[str, Any],
) -> str | None:
    if "type" in payload:
        return None
    error = payload.get("error")
    if not isinstance(error, dict):
        return None
    if _request_error_rejects_credential(status, error):
        return "rejected"
    identifiers = _error_identifiers(error)
    if status in _REQUEST_ERROR_STATUSES and not (_REQUEST_ERROR_IDENTIFIERS | _MODEL_ERROR_IDENTIFIERS).isdisjoint(
        identifiers
    ):
        return "accepted"
    if status in _AUTHENTICATION_ERROR_STATUSES and not _AUTHENTICATION_ERROR_IDENTIFIERS.isdisjoint(identifiers):
        return "rejected"
    if status in _SERVER_ERROR_STATUSES and not _SERVER_ERROR_IDENTIFIERS.isdisjoint(identifiers):
        return "unknown"
    if status in _RATE_LIMIT_STATUSES and not _RATE_LIMIT_ERROR_IDENTIFIERS.isdisjoint(identifiers):
        return "unknown"
    return None


def _openai_wrapperless_error_kind(
    status: int,
    payload: Mapping[str, Any],
) -> str | None:
    if isinstance(payload.get("error"), dict):
        return None
    identifiers = _payload_identifiers(payload)
    if not identifiers:
        return None
    if status in _REQUEST_ERROR_STATUSES and not (_REQUEST_ERROR_IDENTIFIERS | _MODEL_ERROR_IDENTIFIERS).isdisjoint(
        identifiers
    ):
        return "accepted"
    if status in _AUTHENTICATION_ERROR_STATUSES and not _AUTHENTICATION_ERROR_IDENTIFIERS.isdisjoint(identifiers):
        return "rejected"
    if status in _SERVER_ERROR_STATUSES and not _SERVER_ERROR_IDENTIFIERS.isdisjoint(identifiers):
        return "unknown"
    if status in _RATE_LIMIT_STATUSES and not _RATE_LIMIT_ERROR_IDENTIFIERS.isdisjoint(identifiers):
        return "unknown"
    return None


def _default_unproven_shape(
    *,
    status: int,
    payload: Mapping[str, Any] | None = None,
    non_json: bool = False,
) -> _ProtocolObservationShape:
    if status == 404:
        return _ProtocolObservationShape.HTTP_404
    if status not in _REQUEST_ERROR_STATUSES:
        return _ProtocolObservationShape.NONE
    if non_json:
        return _ProtocolObservationShape.NON_JSON
    if payload is None or not _payload_is_structured(payload):
        return _ProtocolObservationShape.UNSTRUCTURED
    return _ProtocolObservationShape.NONE


def _parse_protocol_authenticated_evidence(
    protocol: str,
    status: int,
    body: str | bytes,
    *,
    vendor: str | None = None,
    request_root: str | None = None,
    oauth: bool = False,
) -> _ProtocolEvidence:
    """Classify protocol shape without treating schema validation as login.

    A missing-model error can precede authentication. Neither a declaration nor
    a differently rejected credential can upgrade it into authentication proof.
    """

    def evidence(
        protocol: _ProtocolProof,
        authentication: _AuthenticationEvidence,
        shape: _ProtocolObservationShape = _ProtocolObservationShape.NONE,
    ) -> _ProtocolEvidence:
        return _ProtocolEvidence(
            protocol=protocol,
            authentication=authentication,
            shape=shape,
            status=status,
        )

    try:
        payload = json.loads(body)
    except (TypeError, UnicodeDecodeError, ValueError):
        return evidence(
            protocol=_ProtocolProof.UNPROVEN,
            authentication=_AuthenticationEvidence.UNKNOWN,
            shape=_default_unproven_shape(status=status, non_json=True),
        )
    if not isinstance(payload, dict):
        return evidence(
            protocol=_ProtocolProof.UNPROVEN,
            authentication=_AuthenticationEvidence.UNKNOWN,
            shape=_default_unproven_shape(status=status),
        )

    if oauth and _oauth_rejection_is_definitive(status, payload):
        return evidence(
            protocol=_ProtocolProof.UNPROVEN,
            # The management probe is not CPA's refresh endpoint. Even an
            # ``invalid_grant``-shaped upstream response is inconclusive. The
            # pinned inventory also has no refresh-specific error provenance.
            authentication=_AuthenticationEvidence.UNKNOWN,
        )

    top_level_identifiers = _payload_identifiers(payload)
    if (
        not oauth
        and status in _AUTHENTICATION_ERROR_STATUSES
        and not _AUTHENTICATION_ERROR_IDENTIFIERS.isdisjoint(top_level_identifiers)
    ):
        return evidence(
            protocol=_ProtocolProof.UNPROVEN,
            authentication=_AuthenticationEvidence.REJECTED,
        )
    error = payload.get("error")
    if not oauth and _request_error_rejects_credential(status, error):
        return evidence(
            protocol=_ProtocolProof.UNPROVEN,
            authentication=_AuthenticationEvidence.REJECTED,
        )

    if protocol == "anthropic":
        wrapperless = _anthropic_wrapperless_error_kind(status, payload)
        if wrapperless == "accepted":
            return evidence(
                protocol=_ProtocolProof.UNPROVEN,
                authentication=_AuthenticationEvidence.UNKNOWN,
                shape=_ProtocolObservationShape.GENERIC_REQUEST_ERROR,
            )
        if wrapperless == "rejected" and not oauth:
            return evidence(
                protocol=_ProtocolProof.UNPROVEN,
                authentication=_AuthenticationEvidence.REJECTED,
            )
        if wrapperless == "unknown":
            return evidence(
                protocol=_ProtocolProof.UNPROVEN,
                authentication=_AuthenticationEvidence.UNKNOWN,
            )

    taxonomy = _PROTOCOL_OBSERVATION_TAXONOMY.get(protocol)
    for rule in taxonomy.evidence_rules if taxonomy is not None else ():
        if oauth and rule.authentication is _AuthenticationEvidence.REJECTED:
            continue
        if rule.matches(status, payload):
            return evidence(
                protocol=rule.protocol,
                authentication=rule.authentication,
                shape=rule.shape,
            )
    if protocol in _OPENAI_FAMILY_PROTOCOLS and status in _REQUEST_ERROR_STATUSES:
        wrapperless = _openai_wrapperless_error_kind(status, payload)
        if wrapperless == "accepted":
            return evidence(
                protocol=_ProtocolProof.UNPROVEN,
                authentication=_AuthenticationEvidence.UNKNOWN,
                shape=_ProtocolObservationShape.GENERIC_REQUEST_ERROR,
            )
        if isinstance(error, dict):
            identifiers = _error_identifiers(error)
            if (
                not _REQUEST_ERROR_IDENTIFIERS.isdisjoint(identifiers)
                and _AUTHENTICATION_ERROR_IDENTIFIERS.isdisjoint(identifiers)
                and _error_param_name(error) not in _OPENAI_FAMILY_PARAMS
            ):
                return evidence(
                    protocol=_ProtocolProof.UNPROVEN,
                    authentication=_AuthenticationEvidence.UNKNOWN,
                    shape=_ProtocolObservationShape.GENERIC_REQUEST_ERROR,
                )
    if _response_shape_proves_protocol(protocol, payload):
        return evidence(
            protocol=_ProtocolProof.PROVEN,
            authentication=_AuthenticationEvidence.UNKNOWN,
        )
    return evidence(
        protocol=_ProtocolProof.UNPROVEN,
        authentication=_AuthenticationEvidence.UNKNOWN,
        shape=_default_unproven_shape(status=status, payload=payload),
    )


async def _probe_protocol_response(
    *,
    vendor: str,
    protocol: str,
    base_url: str | None,
    secret: str,
    auth_scheme: str | None = None,
    timeout: float = 15.0,
) -> _ProtocolEvidence:
    """Require a response from the candidate protocol's distinct request path."""

    validate_api_key_auth_scheme(vendor, protocol, base_url, secret, auth_scheme)
    if protocol == "google":
        # Gemini requires the model in the generation URL. Observation never
        # invents a model or schedules inference: an explicit declaration can
        # instead authenticate through the existing credential-gated listing.
        return _ProtocolEvidence(_ProtocolProof.UNPROVEN, _AuthenticationEvidence.UNKNOWN)
    root = base_url or _OFFICIAL_BASE_URLS.get(vendor)
    if not root:
        raise EngineClientError("source requires a base URL for protocol observation")
    taxonomy = _PROTOCOL_OBSERVATION_TAXONOMY.get(protocol)
    if taxonomy is None:
        raise EngineClientError("unsupported source protocol")
    try:
        url = upstream_api_url(root, taxonomy.request_path)
        credential = anthropic_api_key_header(root, secret) if protocol == "anthropic" else {
            "Authorization": f"Bearer {secret}",
        }
    except (TypeError, ValueError):
        raise EngineClientError("source base URL is invalid")
    assert url is not None
    headers = {**credential, "Accept": "application/json"}
    if protocol == "anthropic":
        headers["anthropic-version"] = "2023-06-01"
    client_timeout = aiohttp.ClientTimeout(total=timeout)

    async def observe() -> _ProtocolEvidence:
        async with aiohttp.ClientSession(timeout=client_timeout) as session:
            async with session.post(
                url,
                headers=headers,
                json=dict(taxonomy.request_body),
                allow_redirects=False,
            ) as response:
                body = await response.content.read(64 * 1024)
                return _parse_protocol_authenticated_evidence(
                    protocol,
                    response.status,
                    body,
                    vendor=vendor,
                    request_root=root,
                )

    try:
        return await asyncio.wait_for(observe(), timeout=timeout)
    except asyncio.TimeoutError:
        raise EngineClientError("protocol observation timed out", error_type="timeout") from None
    except aiohttp.ClientError:
        raise EngineClientError(
            "protocol observation failed",
            error_type="network_error",
        ) from None


@dataclass(frozen=True)
class _AuthRecord:
    identity: str
    auth_index: str
    name: str
    provider: str
    fingerprint: str
    account_id: str | None = None
    status: str = ""
    status_message: str = ""
    unavailable: bool = False


def _response_shape_proves_protocol(
    protocol: str,
    body: Mapping[str, Any],
) -> bool:
    """Recognize protocol-specific shapes without inferring authentication."""

    if protocol == "anthropic":
        error = body.get("error")
        return body.get("type") == "message" or (
            body.get("type") == "error" and isinstance(error, dict) and isinstance(error.get("type"), str)
        )
    error = body.get("error")
    if protocol == "openai_responses":
        return body.get("object") == "response" or (
            isinstance(error, dict) and error.get("param") in _OPENAI_RESPONSES_PARAMS
        )
    if protocol == "openai_chat":
        return body.get("object") in {"chat.completion", "chat.completion.chunk"} or (
            isinstance(error, dict) and error.get("param") in _OPENAI_CHAT_PARAMS
        )
    return False


def _openai_family_elimination_proof(
    responses: Mapping[str, _ProtocolEvidence],
    *,
    considered_protocols: frozenset[str],
    ruled_out_protocols: frozenset[str],
) -> str | None:
    """Prove one OpenAI-family protocol from the pair of responses, not from the URL.

    A request-error row with matched identifiers but no family-distinctive
    ``param`` proves only that one endpoint parsed the synthetic request with
    authentication accepted. The sibling protocol becomes excluded only when its
    own endpoint answers the same source with an unproven shape, so the proof is
    carried by the response pair rather than by either request path alone. That
    pairwise proof is valid only when every other probed protocol was already
    ruled out for this source. A competing protocol can be ruled out by an
    explicit authentication rejection or by a definitive request-error-shaped
    exclusion. Transient upstream failures do not qualify.
    """

    if not {protocol for protocol in considered_protocols if protocol not in _OPENAI_FAMILY_PROTOCOLS}.issubset(
        ruled_out_protocols
    ):
        return None

    candidate = responses.get("openai_responses")
    sibling = responses.get("openai_chat")
    if (
        candidate is not None
        and sibling is not None
        and candidate.protocol is _ProtocolProof.UNPROVEN
        and candidate.authentication is _AuthenticationEvidence.ACCEPTED
        and candidate.shape is _ProtocolObservationShape.GENERIC_REQUEST_ERROR
        and sibling.protocol is _ProtocolProof.UNPROVEN
        and sibling.authentication is _AuthenticationEvidence.UNKNOWN
        and sibling.shape in _PAIRWISE_EXCLUSION_SHAPES
    ):
        return "openai_responses"
    if (
        candidate is not None
        and sibling is not None
        and sibling.protocol is _ProtocolProof.UNPROVEN
        and sibling.authentication is _AuthenticationEvidence.ACCEPTED
        and sibling.shape is _ProtocolObservationShape.GENERIC_REQUEST_ERROR
        and candidate.protocol is _ProtocolProof.UNPROVEN
        and candidate.authentication is _AuthenticationEvidence.UNKNOWN
        and candidate.shape in _PAIRWISE_EXCLUSION_SHAPES
    ):
        return "openai_chat"
    return None


def _pairwise_positive_exclusion(evidence: _ProtocolEvidence) -> bool:
    return (
        evidence.protocol is _ProtocolProof.UNPROVEN
        and evidence.authentication is _AuthenticationEvidence.UNKNOWN
        and evidence.shape in _PAIRWISE_EXCLUSION_SHAPES
    )


def hub_subscription_serving_protocol(vendor: str) -> str | None:
    """The protocol a hub-held subscription for this vendor is served on.

    ``None`` for a vendor whose grant is proven by response instead of pinned,
    which is why callers ask this before deciding to probe rather than after
    failing to.
    """

    return _HUB_SUBSCRIPTION_PROTOCOLS.get(vendor.strip().lower())


def _protocol_is_persistable_without_shape_proof(
    *,
    credential_kind: str,
    vendor: str,
    protocol: str,
    protocol_order: Sequence[str],
) -> bool:
    if credential_kind == "oauth":
        # A hub subscription's protocol is pinned rather than proven, so there is
        # no response shape to wait for. Nothing else about an OAuth credential
        # is persistable this way: an unpinned vendor returns False here and
        # stays on the probe.
        return hub_subscription_serving_protocol(vendor) == protocol
    if credential_kind != "api_key":
        return False
    pinned_protocol = pinned_api_key_protocol(vendor)
    if pinned_protocol == protocol:
        return True
    return vendor == "custom" and len(protocol_order) == 1 and protocol_order[0] == protocol


class _ModelsWitness(Enum):
    """What an owned interface's model listing established about a credential."""

    ACCEPTED = "accepted"
    REJECTED = "rejected"
    INCONCLUSIVE = "inconclusive"


@dataclass(frozen=True)
class _ModelsWitnessResult:
    credential: _ModelsWitness
    models: tuple[DiscoveredModel, ...] = ()


async def _authenticate_with_models_witness(
    *,
    vendor: str,
    protocol: str,
    base_url: str | None,
    secret: str,
    auth_scheme: str | None = None,
) -> _ModelsWitnessResult:
    """Read the owned interface's model listing as the authentication witness.

    The protocol probe deliberately carries no ``model`` so observation never
    enters a relay's scheduler, which is exactly why a conforming interface
    answers it with a request error and leaves authentication unknown. The
    listing this rung already fetches for inventory is the one call on that same
    interface that a correct credential answers and a wrong one refuses, so it
    carries the authentication the probe cannot: an authentication status
    rejects the credential, and no listing route, an unparseable body, or a
    transport failure proves nothing and leaves the observation exactly where
    the probe left it.

    A listing only accepts the credential once the same request without one is
    refused. Some interfaces publish their catalogue to anybody, and there a
    listing attests to whoever asked rather than to this key. Asking with no
    credential settles which kind this is: unlike an altered or fabricated key,
    an absent one cannot be wrong about a grammar nobody published or collide
    with another valid key, so the answer is unambiguous. An open catalogue
    therefore stays inconclusive and the source saves the way it does today.

    Acceptance is bounded accordingly: the interface admits this credential and
    refuses admission without one, which is not proof that it read the value.
    An interface that requires a credential without reading it answers those two
    requests identically, so it is admitted as well, and the third request that
    would separate the two carries an altered credential and attests to nothing
    in either direction. The first real call catches a credential nothing
    validated, exactly where it catches one revoked after its add.

    Only a catalog pin or a concrete declaration asks, because the answer names
    no protocol; that owner supplies it. The accepted result carries the
    listing, so one call both authenticates the source and populates it.
    """

    scheme_options = {"auth_scheme": auth_scheme} if auth_scheme is not None else {}
    try:
        models = await probe_models(
            vendor=vendor,
            protocol=protocol,
            base_url=base_url,
            secret=secret,
            **scheme_options,
        )
    except EngineClientError as exc:
        if exc.status_code in _AUTHENTICATION_ERROR_STATUSES:
            return _ModelsWitnessResult(credential=_ModelsWitness.REJECTED)
        return _ModelsWitnessResult(credential=_ModelsWitness.INCONCLUSIVE)
    try:
        await probe_models(
            vendor=vendor,
            protocol=protocol,
            base_url=base_url,
            secret=None,
            **scheme_options,
        )
    except EngineClientError as refusal:
        if refusal.status_code in _AUTHENTICATION_ERROR_STATUSES:
            return _ModelsWitnessResult(
                credential=_ModelsWitness.ACCEPTED,
                models=tuple(models),
            )
    return _ModelsWitnessResult(credential=_ModelsWitness.INCONCLUSIVE)


def _anthropic_wrapperless_elimination_proof(
    responses: Mapping[str, _ProtocolEvidence],
    *,
    considered_protocols: frozenset[str],
    ruled_out_protocols: frozenset[str],
) -> str | None:
    """Prove wrapperless Anthropic only from the complete response set.

    A wrapperless ``{"error": {"type": ...}}`` request error still proves only
    that the endpoint accepted the credential and parsed the synthetic request.
    It becomes Anthropic evidence only when both OpenAI-family sibling probes
    were actually part of this observation round and their own responses ruled
    them out. The proof is therefore carried by the response set, not by the
    ``/v1/messages`` path alone.
    """

    if not _OPENAI_FAMILY_PROTOCOLS.issubset(considered_protocols):
        return None
    if not _OPENAI_FAMILY_PROTOCOLS.issubset(ruled_out_protocols):
        return None
    candidate = responses.get("anthropic")
    if (
        candidate is not None
        and candidate.protocol is _ProtocolProof.UNPROVEN
        and candidate.authentication is _AuthenticationEvidence.ACCEPTED
        and candidate.shape is _ProtocolObservationShape.GENERIC_REQUEST_ERROR
    ):
        return "anthropic"
    return None


# The vendors whose finished OAuth grant is bound by *probing* it: the ones with
# a public upstream URL and header set the probe below can synthesize a request
# against, and read the protocol back out of the response.
#
# This is one of the two routes a grant binds by, not the whole admission. The
# other is `_HUB_SUBSCRIPTION_PROTOCOLS`, where the protocol is pinned from the
# engine's serving surface because there is no reachable upstream to ask. Every
# vendor `_OAUTH_ENDPOINTS` can sign in takes exactly one of the two — a flow
# that could start and then not bind would be a dead end — and
# `tests/test_model_hub_runtime.py` asserts that partition rather than listing
# the members, so a vendor added to the start table without a binding route
# fails a test instead of shipping.
#
# That test also pins the probe's actual behaviour against this set, so widening
# one without the other is a failure rather than a silent change.
_OAUTH_OBSERVABLE_VENDORS = frozenset({"anthropic", "openai", "codex"})


def _probe_oauth_protocol_response(
    *,
    client: EngineClient,
    auth: _AuthRecord,
    vendor: str,
    protocol: str,
) -> _ProtocolEvidence:
    """Probe one allowlisted OAuth upstream through the engine-held credential."""

    taxonomy = _PROTOCOL_OBSERVATION_TAXONOMY.get(protocol)
    if taxonomy is None:
        raise EngineClientError("unsupported source protocol")
    if vendor == "anthropic" and protocol == "anthropic":
        url = f"https://api.anthropic.com{taxonomy.oauth_path or taxonomy.request_path}"
        headers = {
            "Accept": "application/json",
            "Content-Type": "application/json",
            "Anthropic-Version": "2023-06-01",
            "Anthropic-Beta": "oauth-2025-04-20",
            "X-App": "cli",
        }
    elif vendor in {"openai", "codex"} and protocol == "openai_responses":
        url = f"https://chatgpt.com{taxonomy.oauth_path or taxonomy.request_path}"
        headers = {
            "Accept": "application/json",
            "Content-Type": "application/json",
            "Originator": "codex-tui",
        }
        if auth.account_id:
            headers["Chatgpt-Account-Id"] = auth.account_id
    else:
        raise EngineClientError(
            "OAuth credential does not support this protocol path",
            status_code=404,
        )
    headers["Authorization"] = "Bearer $TOKEN$"

    def request(probe_headers: dict[str, str]) -> _ProtocolEvidence:
        payload = client.management_request(
            "POST",
            "/api-call",
            payload={
                "auth_index": auth.auth_index,
                "method": "POST",
                "url": url,
                "header": probe_headers,
                "data": json.dumps(taxonomy.request_body, separators=(",", ":")),
            },
        )
        status = payload.get("status_code")
        if not isinstance(status, int) or isinstance(status, bool):
            raise EngineClientError(
                "protocol observation returned an invalid status",
                error_type="invalid_json",
            )
        body = payload.get("body")
        return _parse_protocol_authenticated_evidence(
            protocol,
            status,
            body if isinstance(body, str) else "",
            vendor=vendor,
            oauth=True,
        )

    return request(headers)


_OAUTH_CONTROL_PLANE_URLS = {
    "anthropic": "https://api.anthropic.com/api/oauth/profile",
    "openai": "https://chatgpt.com/backend-api/wham/usage",
    "codex": "https://chatgpt.com/backend-api/wham/usage",
}


def _parse_oauth_control_plane_witness(
    vendor: str,
    status: object,
    body: object,
) -> bool:
    """Accept only the provider's model-free account/control-plane shape."""

    if not isinstance(status, int) or isinstance(status, bool) or status not in _SUCCESS_STATUSES:
        return False
    if not isinstance(body, (str, bytes, bytearray)):
        return False
    try:
        payload = json.loads(body)
    except (TypeError, UnicodeDecodeError, ValueError):
        return False
    if not isinstance(payload, dict) or "error" in payload:
        return False

    if vendor == "anthropic":
        account = payload.get("account")
        uuid_value = account.get("uuid") if isinstance(account, dict) else None
        return isinstance(uuid_value, str) and bool(uuid_value.strip())
    if vendor in {"openai", "codex"}:
        plan_type = payload.get("plan_type")
        return isinstance(plan_type, str) and bool(plan_type.strip())
    return False


def _oauth_account_call_headers(auth: _AuthRecord, normalized_vendor: str) -> dict[str, str]:
    """Headers for a model-free account GET; CPA substitutes ``$TOKEN$``."""

    headers = {
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Authorization": "Bearer $TOKEN$",
    }
    if normalized_vendor == "anthropic":
        headers.update(
            {
                "User-Agent": "axios/1.15.2",
                "Cache-Control": "no-cache",
            }
        )
    else:
        headers["User-Agent"] = "codex-cli"
        if auth.account_id:
            headers["ChatGPT-Account-ID"] = auth.account_id
    return headers


# The vendors' own quota reports: the same endpoints their CLIs read for
# `/usage` and `/status`. Anthropic gates its report behind the OAuth beta.
_SUBSCRIPTION_QUOTA_URLS = {
    "anthropic": "https://api.anthropic.com/api/oauth/usage",
    "openai": "https://chatgpt.com/backend-api/wham/usage",
    "codex": "https://chatgpt.com/backend-api/wham/usage",
}


def _retry_after_seconds(headers: object) -> float | None:
    if not isinstance(headers, dict):
        return None
    for key, value in headers.items():
        if not isinstance(key, str) or key.lower() != "retry-after":
            continue
        raw = str(value[0] if isinstance(value, list) and value else value).strip()
        try:
            seconds = float(raw)
        except ValueError:
            # RFC 9110 also allows an HTTP-date.
            try:
                moment = email.utils.parsedate_to_datetime(raw)
            except (TypeError, ValueError, IndexError):
                return None
            if moment.tzinfo is None:
                moment = moment.replace(tzinfo=timezone.utc)
            seconds = (moment - datetime.now(timezone.utc)).total_seconds()
        return seconds if math.isfinite(seconds) and seconds > 0 else None
    return None


def _fetch_subscription_quota(
    *,
    client: EngineClient,
    auth: _AuthRecord,
    vendor: str,
) -> dict[str, Any]:
    """Read one grant's quota report and keep only the parsed windows."""

    url = _SUBSCRIPTION_QUOTA_URLS[vendor]
    headers = _oauth_account_call_headers(auth, vendor)
    if vendor == "anthropic":
        headers["anthropic-beta"] = "oauth-2025-04-20"
    payload = client.management_request(
        "POST",
        "/api-call",
        payload={
            "auth_index": auth.auth_index,
            "method": "GET",
            "url": url,
            "header": headers,
        },
        timeout=QUOTA_FETCH_TIMEOUT_SECONDS,
    )
    status = payload.get("status_code")
    if status in {401, 403}:
        raise SubscriptionQuotaError("auth_expired")
    if status == 429:
        raise SubscriptionQuotaError(
            "rate_limited",
            retry_after_seconds=_retry_after_seconds(payload.get("header")),
        )
    if not isinstance(status, int) or isinstance(status, bool) or status not in _SUCCESS_STATUSES:
        raise SubscriptionQuotaError("unavailable")
    parsed = parse_subscription_quota(vendor, payload.get("body"))
    if vendor == "anthropic" and parsed.get("plan") is None:
        parsed["plan"] = _fetch_claude_plan(client=client, auth=auth)
    return parsed


def _fetch_claude_plan(*, client: EngineClient, auth: _AuthRecord) -> str | None:
    """Claude's usage report names no plan; read it from the profile, best effort."""

    try:
        payload = client.management_request(
            "POST",
            "/api-call",
            payload={
                "auth_index": auth.auth_index,
                "method": "GET",
                "url": _OAUTH_CONTROL_PLANE_URLS["anthropic"],
                "header": _oauth_account_call_headers(auth, "anthropic"),
            },
            timeout=CLAUDE_PLAN_FETCH_TIMEOUT_SECONDS,
        )
    except (EngineClientError, OSError):
        return None
    status = payload.get("status_code")
    if not isinstance(status, int) or isinstance(status, bool) or status not in _SUCCESS_STATUSES:
        return None
    return parse_claude_plan(payload.get("body"))


def _probe_oauth_control_plane_witness(
    *,
    client: EngineClient,
    auth: _AuthRecord,
    vendor: str,
) -> None:
    """Use CPA's current auth record for a bodyless control-plane GET."""

    normalized_vendor = vendor.strip().lower()
    url = _OAUTH_CONTROL_PLANE_URLS.get(normalized_vendor)
    if url is None:
        raise EngineClientError("unsupported OAuth control-plane witness")

    payload = client.management_request(
        "POST",
        "/api-call",
        payload={
            "auth_index": auth.auth_index,
            "method": "GET",
            "url": url,
            "header": _oauth_account_call_headers(auth, normalized_vendor),
        },
    )
    if not _parse_oauth_control_plane_witness(
        normalized_vendor,
        payload.get("status_code"),
        payload.get("body"),
    ):
        raise EngineClientError(
            "OAuth control-plane witness was inconclusive",
            error_type="invalid_response",
        )


@dataclass
class _OAuthFlow:
    flow_id: str
    source_id: str
    engine_state: str
    vendor: str
    callback_provider: str
    auth_provider: str
    expects: str
    auth_url: str | None
    device_code: str | None
    expires_at_iso: str
    before_auth_fingerprints: dict[str, str]
    state: str = "awaiting_action"
    error_key: str | None = None
    credential_ref: str | None = None
    retained_material_disposition: RetainedMaterialDisposition = RetainedMaterialDisposition.NONE
    retained_credential_ref: str | None = None
    error_detail: str | None = None
    grant_write_possible: bool = False
    retained_material_decided: bool = False
    operation_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)

    def snapshot(self) -> OAuthFlowState:
        return OAuthFlowState(
            flow_id=self.flow_id,
            source_id=self.source_id,
            vendor=self.vendor,
            state=self.state,
            auth_url=self.auth_url,
            device_code=self.device_code,
            expects=self.expects,
            instructions_key=f"models.oauth.{self.vendor}.{self.expects}",
            error_key=self.error_key,
            expires_at_iso=self.expires_at_iso,
            credential_ref=self.credential_ref,
            channel="hub",
            retained_material_disposition=self.retained_material_disposition,
            retained_credential_ref=self.retained_credential_ref,
            error_detail=self.error_detail,
        )


class CLIProxyEngineAdapter:
    """Managed CLIProxyAPI implementation of the frozen EngineAdapter contract."""

    def __init__(
        self,
        *,
        supervisor: EngineSupervisor | None = None,
        state_store: EngineStateStore | None = None,
    ) -> None:
        self.supervisor = supervisor or get_engine_supervisor()
        self.state_store = state_store or self.supervisor.state_store
        self._routing_lock = asyncio.Lock()
        self._active_transports = 0
        self._transports_idle = asyncio.Event()
        self._transports_idle.set()
        self._unsent_requests = 0
        self._requests_sent = asyncio.Event()
        self._requests_sent.set()
        self._installation_lock = asyncio.Lock()
        self._install_task: asyncio.Task[None] | None = None
        self._install_admission: asyncio.Future[EngineStatus] | None = None
        self._install_owner_active = False
        self._start_after_install_task: asyncio.Task[None] | None = None
        self._installation_stopping = False
        self._oauth_flows: dict[str, _OAuthFlow] = {}
        self._active_oauth_providers: set[str] = set()
        self._oauth_lock = threading.RLock()
        self._keyless_exa_client = KeylessExaMcpClient()

    async def install(self) -> EngineStatus:
        await self.recover_installation()
        async with self._installation_lock:
            task = self._install_task
            admission = self._install_admission
            if task is not None and not task.done():
                if admission is None:
                    return await self.status()
            else:
                status = await self.status()
                if status.health is not EngineHealth.NOT_INSTALLED:
                    return status
                if self._installation_stopping:
                    raise EngineUnavailableError(
                        "models.engine.install_failed",
                        reason="engine_stopping",
                    )
                admission = asyncio.get_running_loop().create_future()
                self._install_admission = admission
                self._start_install_task_locked(
                    generation=uuid.uuid4().hex,
                    expected_target=None,
                    not_installed=status,
                    admission=admission,
                    claim_owned=False,
                )
        assert admission is not None
        return await asyncio.shield(admission)

    async def recover_installation(self) -> EngineStatus:
        async with self._installation_lock:
            install_task = self._install_task
            if install_task is not None and not install_task.done():
                return await self.status()
            install_state = await asyncio.to_thread(self.supervisor.installer.install_state)
            if not install_state or install_state.get("state") != "installing":
                return await self.status()
            generation = uuid.uuid4().hex
            claimed = await asyncio.to_thread(
                self.supervisor.installer.transition_install_claim,
                InstallClaimTransition.RESUME,
                generation=generation,
                previous_generation=install_state.get("generation"),
                target=install_state["target"],
            )
            if not claimed:
                return await self.status()
            try:
                self._start_install_task_locked(
                    generation=generation,
                    expected_target=install_state["target"],
                    not_installed=None,
                    admission=None,
                    claim_owned=True,
                )
            except Exception:  # noqa: BLE001
                logger.exception("Failed to schedule Model Hub runtime install recovery")
                await self._abandon_install_claim(
                    generation=generation,
                    target=install_state["target"],
                    reason=INSTALL_RECOVERY_SCHEDULE_FAILED_REASON,
                )
            return await self.status()

    def _start_install_task_locked(
        self,
        *,
        generation: str,
        expected_target: Mapping[str, str] | None,
        not_installed: EngineStatus | None,
        admission: asyncio.Future[EngineStatus] | None,
        claim_owned: bool,
    ) -> None:
        task = asyncio.create_task(
            self._run_installation(
                generation=generation,
                expected_target=expected_target,
                not_installed=not_installed,
                admission=admission,
                claim_owned=claim_owned,
            ),
            name="model-hub-runtime-install",
        )
        self._install_task = task
        self._install_owner_active = True
        task.add_done_callback(self._installation_done)

    def _installation_done(self, task: asyncio.Task[None]) -> None:
        if self._install_task is task:
            self._install_task = None
            self._install_admission = None
            self._install_owner_active = False
        try:
            task.result()
        except asyncio.CancelledError:
            return
        except Exception:  # noqa: BLE001
            logger.exception("Model Hub runtime install task failed")

    def _start_after_install_done(self, task: asyncio.Task[None]) -> None:
        if self._start_after_install_task is task:
            self._start_after_install_task = None
        try:
            task.result()
        except asyncio.CancelledError:
            return
        except Exception:  # noqa: BLE001
            logger.exception("Model Hub runtime start after installation failed")

    async def _start_after_install(self, install_task: asyncio.Task[None]) -> None:
        await asyncio.shield(install_task)
        async with self._installation_lock:
            if self._installation_stopping:
                return
            status = await self.status()
            if status.health in {
                EngineHealth.INSTALLING,
                EngineHealth.NOT_INSTALLED,
            }:
                return
            await self._engine_call(self.supervisor.ensure_running)

    async def _run_installation(
        self,
        *,
        generation: str,
        expected_target: Mapping[str, str] | None,
        not_installed: EngineStatus | None,
        admission: asyncio.Future[EngineStatus] | None,
        claim_owned: bool,
    ) -> None:
        loop = asyncio.get_running_loop()
        recovery_deadline: float | None = None
        recovery_delay = _INSTALL_RECOVERY_INITIAL_DELAY_SECONDS
        claimed_target: dict[str, str] | None = dict(expected_target) if expected_target is not None else None

        def persist_claim(target: dict[str, str]) -> None:
            nonlocal claim_owned, claimed_target
            claimed_target = dict(target)
            if expected_target is not None:
                return
            claim_owned = self.supervisor.installer.transition_install_claim(
                InstallClaimTransition.CREATE,
                generation=generation,
                target=target,
            )
            if not claim_owned:
                raise RuntimeError("Model Hub runtime install claim moved during admission")
            assert not_installed is not None
            assert admission is not None
            installing = replace(
                not_installed,
                health=EngineHealth.INSTALLING,
                installed_version=None,
                verified=False,
                listen_port=None,
                error_key=None,
            )
            loop.call_soon_threadsafe(self._resolve_install_admission, admission, installing)

        try:
            while True:
                try:
                    await self.ensure_installed(
                        expected_target=expected_target,
                        on_resolved=persist_claim,
                    )
                    break
                except EngineUnavailableError as exc:
                    if expected_target is None or exc.reason != INSTALL_ALREADY_RUNNING_REASON:
                        raise
                    if self._installation_stopping:
                        await self._abandon_install_claim(
                            generation=generation,
                            target=claimed_target,
                        )
                        return
                    now = loop.time()
                    if recovery_deadline is None:
                        recovery_deadline = now + _INSTALL_RECOVERY_WAIT_SECONDS
                        logger.warning(
                            "Model Hub runtime recovery waiting up to %.1fs for the shared install lock",
                            _INSTALL_RECOVERY_WAIT_SECONDS,
                        )
                    remaining = recovery_deadline - now
                    if remaining <= 0:
                        logger.error("Model Hub runtime recovery gave up waiting for the shared install lock")
                        raise EngineUnavailableError(
                            "models.engine.install_failed",
                            reason=INSTALL_RECOVERY_TIMEOUT_REASON,
                        )
                    await asyncio.sleep(min(recovery_delay, remaining))
                    recovery_delay = min(
                        recovery_delay * 2,
                        _INSTALL_RECOVERY_MAX_DELAY_SECONDS,
                    )
            installed = await asyncio.to_thread(
                self.supervisor.installer.resolve_engine_path,
            )
            if installed is None:
                raise EngineUnavailableError("models.engine.install_failed")
            settled = await asyncio.to_thread(
                self.supervisor.installer.transition_install_claim,
                InstallClaimTransition.SETTLE_SUCCESS,
                generation=generation,
                target=claimed_target,
            )
            self._install_owner_active = False
            if settled:
                await asyncio.to_thread(self.supervisor.note_installation_settled)
        except asyncio.CancelledError:
            raise
        except Exception as exc:  # noqa: BLE001
            self._install_owner_active = False
            reason = self._install_failure_reason(exc)
            if claim_owned:
                try:
                    await asyncio.to_thread(
                        self.supervisor.installer.transition_install_claim,
                        InstallClaimTransition.SETTLE_FAILURE,
                        generation=generation,
                        target=claimed_target,
                        reason=reason,
                    )
                except Exception:  # noqa: BLE001
                    logger.exception("Failed to persist Model Hub runtime install failure")
            elif admission is not None and reason != INSTALL_PLATFORM_UNSUPPORTED_REASON:
                try:
                    await asyncio.to_thread(
                        self.supervisor.installer.transition_install_claim,
                        InstallClaimTransition.ADMISSION_FAILURE,
                        generation=generation,
                        reason=reason,
                    )
                except Exception:  # noqa: BLE001
                    logger.exception("Failed to persist Model Hub runtime admission failure")
            if admission is not None:
                self._reject_install_admission(admission, exc)

    async def _abandon_install_claim(
        self,
        *,
        generation: str,
        target: Mapping[str, str] | None,
        reason: str = INSTALL_RECOVERY_ABANDONED_REASON,
    ) -> None:
        self._install_owner_active = False
        try:
            await asyncio.to_thread(
                self.supervisor.installer.transition_install_claim,
                InstallClaimTransition.ABANDON,
                generation=generation,
                target=target,
                reason=reason,
            )
        except Exception:  # noqa: BLE001
            logger.exception("Failed to abandon Model Hub runtime install claim")

    @staticmethod
    def _resolve_install_admission(
        admission: asyncio.Future[EngineStatus],
        status: EngineStatus,
    ) -> None:
        if not admission.done():
            admission.set_result(status)

    @staticmethod
    def _reject_install_admission(
        admission: asyncio.Future[EngineStatus],
        error: Exception,
    ) -> None:
        if not admission.done():
            admission.set_exception(error)

    @staticmethod
    def _install_failure_reason(error: Exception) -> str:
        if isinstance(error, RuntimePlatformUnsupportedError):
            return INSTALL_PLATFORM_UNSUPPORTED_REASON
        if isinstance(error, EngineUnavailableError) and error.reason:
            return error.reason
        return "model_hub_engine_install_failed"

    @staticmethod
    def _install_failure(reason: str, *, os_errno: int | None = None) -> Exception:
        if reason == INSTALL_PLATFORM_UNSUPPORTED_REASON:
            return RuntimePlatformUnsupportedError()
        return EngineUnavailableError("models.engine.install_failed", reason=reason, os_errno=os_errno)

    async def ensure_installed(
        self,
        *,
        force: bool = False,
        offline: bool = False,
        expected_target: Mapping[str, str] | None = None,
        on_resolved: Callable[[dict[str, str]], None] | None = None,
    ) -> EngineEnsureResult:
        async with self._routing_lock:
            installer = self.supervisor.installer.offline_copy() if offline else self.supervisor.installer
            if expected_target is None and on_resolved is None:
                if force:
                    install = await asyncio.to_thread(
                        installer.ensure,
                        force=True,
                    )
                else:
                    install = await asyncio.to_thread(installer.ensure)
            else:
                ensure_kwargs: dict[str, Any] = {
                    "expected_target": expected_target,
                    "on_resolved": on_resolved,
                }
                if force:
                    ensure_kwargs["force"] = True
                install = await asyncio.to_thread(
                    installer.ensure,
                    **ensure_kwargs,
                )
            if not install.get("ok"):
                reason = str(install.get("reason") or "engine_install_failed")
                raise self._install_failure(reason, os_errno=install.get("os_errno"))
            if install.get("changed"):
                await self._transports_idle.wait()
                await run_owned_in_thread(self.supervisor.restart_if_running)
            return EngineEnsureResult(
                status=await self.status(),
                changed=bool(install.get("changed")),
            )

    async def start(self) -> EngineStatus:
        async with self._installation_lock:
            status = await self.status()
            if status.health is EngineHealth.INSTALLING:
                install_task = self._install_task
                if install_task is not None and not install_task.done():
                    start_task = self._start_after_install_task
                    if start_task is None or start_task.done():
                        start_task = asyncio.create_task(
                            self._start_after_install(install_task),
                            name="model-hub-runtime-start-after-install",
                        )
                        self._start_after_install_task = start_task
                        start_task.add_done_callback(self._start_after_install_done)
                return status
            await self._engine_call(self.supervisor.ensure_running)
            return await self.status()

    async def stop_runtime(self) -> EngineStatus:
        async with self._installation_lock:
            status = await self.status()
            if status.health is EngineHealth.INSTALLING:
                return status
            start_after_install_task = self._start_after_install_task
            if start_after_install_task is not None and not start_after_install_task.done():
                start_after_install_task.cancel()
            await asyncio.to_thread(self.supervisor.disable)
            return await self.status()

    async def stop(self) -> None:
        async with self._installation_lock:
            self._installation_stopping = True
            install_task = self._install_task
            start_after_install_task = self._start_after_install_task
        if install_task is not None:
            try:
                await asyncio.shield(install_task)
            except asyncio.CancelledError:
                if not install_task.cancelled():
                    raise
            except Exception:  # noqa: BLE001
                pass
        if start_after_install_task is not None:
            try:
                await asyncio.shield(start_after_install_task)
            except asyncio.CancelledError:
                if not start_after_install_task.cancelled():
                    raise
            except Exception:  # noqa: BLE001
                pass
        await self._keyless_exa_client.close()
        await asyncio.to_thread(self.supervisor.stop)

    async def status(self) -> EngineStatus:
        raw = await asyncio.to_thread(self.supervisor.status)
        status = raw["status"]
        listening = status.get("listening") or {}
        projected = EngineStatus(
            health=EngineHealth(status["health"]),
            installed_version=status.get("installed_version"),
            verified=bool(status.get("verified")),
            listen_host="127.0.0.1",
            listen_port=listening.get("port"),
            last_check_iso=status.get("last_check"),
            host_platform=raw.get("host_platform"),
            error_key=status.get("error_key"),
        )
        if self._install_owner_active:
            return replace(
                projected,
                health=EngineHealth.INSTALLING,
                installed_version=None,
                verified=False,
                listen_port=None,
                error_key=None,
            )
        return projected

    async def gateway_token(self) -> str:
        connection = await self._engine_call(self.supervisor.ensure_running)
        return connection.gateway_token

    async def sync_sources(self, bindings: Sequence[SourceBinding]) -> None:
        async with self._routing_lock:
            # The routing lock orders the projection against new admissions.
            # An admitted request keeps the projection it was admitted under
            # until the engine has read it; established streams keep their
            # connection, since CPA hot-reloads the config, so a save neither
            # waits for them nor restarts. Cancellation must retain the lock
            # until the finite transaction has applied or restored the prior
            # projection.
            await self._requests_sent.wait()
            try:
                await run_owned_in_thread(self._sync_sources_transaction, tuple(bindings))
            except EngineConfigLostError:
                # The transaction kept the projection the engine was launched
                # with, so the restart renders that and the save then applies
                # as it would have. A second loss fails the save.
                await self._restart_lost_engine()
                await run_owned_in_thread(self._sync_sources_transaction, tuple(bindings))

    def _sync_sources_transaction(self, bindings: Sequence[SourceBinding]) -> None:
        try:
            previous = self.state_store.list_sources()
        except EngineStateError:
            previous = []
        self.state_store.sync_sources(bindings)
        try:
            self.supervisor.reload_config_if_running(previous)
        except EngineConfigLostError:
            # Nothing the engine runs is Avibe's to restore.
            self.state_store.replace_sources(previous)
            raise
        except Exception:
            applied = self.state_store.list_sources()
            self.state_store.replace_sources(previous)
            try:
                self.supervisor.reload_config_if_running(applied)
            except Exception as restore_error:
                raise EngineStateError(
                    "source sync failed and the previous engine state could not be restored"
                ) from restore_error
            raise

    def _hold_unsent_request(self) -> Callable[[], None]:
        self._unsent_requests += 1
        self._requests_sent.clear()
        released = False

        def release() -> None:
            nonlocal released
            if released:
                return
            released = True
            self._unsent_requests -= 1
            if self._unsent_requests == 0:
                self._requests_sent.set()

        return release

    def _acquire_transport(self) -> Callable[[], None]:
        self._active_transports += 1
        self._transports_idle.clear()
        released = False

        def release() -> None:
            nonlocal released
            if released:
                return
            released = True
            self._active_transports -= 1
            if self._active_transports == 0:
                self._transports_idle.set()

        return release

    async def _restart_lost_engine(self) -> None:
        """Restore an engine that lost its configuration; the caller holds the routing lock.

        Holding it admits no new work. The engine restarts from the config
        Avibe renders once the streams it still serves have ended, so none of
        them is cut.
        """
        await self._transports_idle.wait()
        await run_owned_in_thread(self.supervisor.restart_lost_engine)

    async def _locked_engine_call(self, call: Callable[[], _T]) -> _T:
        """Run a supervisor call that may start the engine, under the routing lock the caller holds."""
        try:
            return await asyncio.to_thread(call)
        except EngineConfigLostError:
            await self._restart_lost_engine()
            return await asyncio.to_thread(call)

    async def _engine_call(self, call: Callable[[], _T]) -> _T:
        """Run a supervisor call that may start the engine, restoring one that lost its configuration."""
        try:
            return await asyncio.to_thread(call)
        except EngineConfigLostError:
            async with self._routing_lock:
                await self._restart_lost_engine()
            return await asyncio.to_thread(call)

    async def provision_credential(
        self,
        vendor: str,
        protocol: str,
        secret: str,
        base_url: str | None,
        *,
        auth_scheme: str | None = None,
        on_reserved: Callable[[str], None] | None = None,
    ) -> str:
        return await run_owned_in_thread(
            self.state_store.store_api_key,
            secret,
            vendor=vendor,
            protocol=protocol,
            base_url=base_url,
            **({"auth_scheme": auth_scheme} if auth_scheme is not None else {}),
            on_reserved=on_reserved,
        )

    @staticmethod
    def _search_catalog_parts(catalog: Mapping[str, Any]) -> tuple[str | None, Mapping[str, Any] | None]:
        vendor = catalog.get("vendor")
        service = catalog.get("search")
        if isinstance(service, Mapping):
            return vendor if isinstance(vendor, str) else None, service
        return vendor if isinstance(vendor, str) else None, catalog

    async def _search_http(
        self,
        *,
        catalog: Mapping[str, Any],
        credential_ref: str | None,
        method: str,
        endpoint: str,
        payload: Mapping[str, Any] | None = None,
        extra_headers: Mapping[str, str] | None = None,
        timeout_total: float = _SEARCH_TIMEOUT_SECONDS,
        connect_timeout: float | None = None,
        on_sent: Callable[[], Awaitable[None] | None] | None = None,
    ) -> SearchResponse:
        """Call only the immutable catalog endpoint for one search operation."""
        vendor, service = self._search_catalog_parts(catalog)
        if service is None or not isinstance(service.get("endpoint"), str):
            return SearchResponse(None, {}, None, "invalid_endpoint")
        configured_endpoint = endpoint
        parsed = urllib.parse.urlsplit(configured_endpoint)
        catalog_endpoint = urllib.parse.urlsplit(str(service.get("endpoint") or ""))
        allowed_paths = {catalog_endpoint.path}
        check = service.get("free_check")
        if isinstance(check, Mapping):
            check_endpoint = urllib.parse.urlsplit(str(check.get("endpoint") or ""))
            if check_endpoint.path:
                allowed_paths.add(check_endpoint.path)
        if (
            parsed.scheme != "https"
            or not parsed.hostname
            or parsed.hostname.lower() != (catalog_endpoint.hostname or "").lower()
            or parsed.port != catalog_endpoint.port
            or parsed.path not in allowed_paths
            or parsed.query
            or parsed.fragment
        ):
            return SearchResponse(None, {}, None, "invalid_endpoint")
        try:
            if credential_ref is None:
                key = None
                metadata = {}
            else:
                key = await asyncio.to_thread(self.state_store.read_api_key, credential_ref)
                metadata = await asyncio.to_thread(self.state_store.credential_metadata, credential_ref)
        except Exception:
            return SearchResponse(None, {}, None, "connection")
        if vendor is None or (credential_ref is not None and metadata.get("vendor") != vendor):
            return SearchResponse(None, {}, None, "invalid_endpoint")
        auth = str(service.get("auth") or "bearer")
        headers = {"Accept": "application/json", "Content-Type": "application/json"}
        if auth == "x-api-key" and key is not None:
            headers["x-api-key"] = key
        elif auth != "none" and key is not None:
            headers["Authorization"] = f"Bearer {key}"
        elif auth != "none":
            return SearchResponse(None, {}, None, "invalid_endpoint")
        if isinstance(service.get("headers"), Mapping):
            headers.update({str(name): str(value) for name, value in service["headers"].items()})
        if extra_headers:
            headers.update(extra_headers)
        timeout = aiohttp.ClientTimeout(total=timeout_total, connect=connect_timeout)
        callback_called = False
        response_status: int | None = None
        response_headers: dict[str, str] = {}
        response_received_at: datetime | None = None

        class SearchRequest(aiohttp.ClientRequest):
            async def send(self, conn):
                nonlocal callback_called
                # At send(), aiohttp owns the Connection and closes it if
                # admission fails. Raising from connection-create trace hooks
                # can instead orphan the not-yet-owned transport.
                if not callback_called and on_sent is not None:
                    admission = on_sent()
                    if inspect.isawaitable(admission):
                        await admission
                    callback_called = True
                return await super().send(conn)
        try:
            async with aiohttp.ClientSession(
                timeout=timeout,
                trust_env=False,
                request_class=SearchRequest,
            ) as session:
                async with session.request(
                    method,
                    configured_endpoint,
                    headers=headers,
                    json=dict(payload) if payload is not None else None,
                    allow_redirects=False,
                ) as response:
                    response_status = response.status
                    response_received_at = datetime.now(timezone.utc)
                    response_headers = {
                        name: value
                        for name, value in response.headers.items()
                        if name.lower() in _SEARCH_RESPONSE_HEADERS
                    }
                    body, body_too_large = await _read_bounded_search_body(response.content)
                    if body_too_large:
                        return SearchResponse(
                            response_status,
                            response_headers,
                            None,
                            "body_too_large",
                            on_sent_fired=callback_called,
                            response_received_at=response_received_at,
                        )
                    assert body is not None
                    if 300 <= response_status < 400:
                        return SearchResponse(
                            response_status,
                            response_headers,
                            body,
                            "redirect",
                            on_sent_fired=callback_called,
                            response_received_at=response_received_at,
                        )
                    return SearchResponse(
                        response_status,
                        response_headers,
                        body,
                        on_sent_fired=callback_called,
                        response_received_at=response_received_at,
                    )
        except asyncio.CancelledError:
            return SearchResponse(
                response_status,
                response_headers,
                None,
                "cancelled",
                on_sent_fired=callback_called,
                response_received_at=response_received_at,
            )
        except asyncio.TimeoutError:
            return SearchResponse(
                response_status,
                response_headers,
                None,
                "timeout",
                on_sent_fired=callback_called,
                response_received_at=response_received_at,
            )
        except (aiohttp.ClientError, OSError, ValueError):
            return SearchResponse(
                response_status,
                response_headers,
                None,
                "connection",
                on_sent_fired=callback_called,
                response_received_at=response_received_at,
            )

    async def check_search_credential(
        self,
        credential_ref: str,
        catalog: Mapping[str, Any],
    ) -> SearchCredentialCheck:
        vendor, service = self._search_catalog_parts(catalog)
        if vendor is None or service is None:
            return SearchCredentialCheck("unknown")
        check = service.get("free_check")
        if not isinstance(check, Mapping):
            return SearchCredentialCheck("unknown")
        response = await self._search_http(
            catalog=catalog,
            credential_ref=credential_ref,
            method=str(check.get("method") or "GET"),
            endpoint=str(check.get("endpoint") or ""),
            timeout_total=_SEARCH_CHECK_TIMEOUT_SECONDS,
            connect_timeout=_SEARCH_CHECK_CONNECT_TIMEOUT_SECONDS,
        )
        if response.error == "cancelled":
            raise asyncio.CancelledError
        if response.http_status in set(check.get("invalid_statuses") or ()):
            return SearchCredentialCheck("invalid")
        if response.error or response.http_status is None:
            return SearchCredentialCheck("unknown")
        if response.http_status != 200 or response.body is None:
            return SearchCredentialCheck("unknown")
        def decode() -> SearchCredentialCheck:
            # The free check shares search's 8 MiB body bound, not the event loop.
            try:
                body = json.loads(response.body.decode("utf-8"))
            except (UnicodeDecodeError, json.JSONDecodeError, RecursionError):
                return SearchCredentialCheck("unknown")
            limit_rule = check.get("limit")
            if isinstance(limit_rule, Mapping):
                limit_outcome = _search_limit_outcome(body, limit_rule)
                if limit_outcome == "limit":
                    return SearchCredentialCheck("limit")
                if limit_outcome == "unknown":
                    return SearchCredentialCheck("unknown")
            passed = check.get("pass")
            balance = check.get("balance")
            if isinstance(passed, Mapping) and _search_check_matches(body, passed):
                return SearchCredentialCheck("pass")
            if isinstance(balance, Mapping) and _search_check_matches(body, balance):
                return SearchCredentialCheck("balance")
            if balance is None and isinstance(passed, Mapping) and passed.get("status") == 200:
                return SearchCredentialCheck("pass")
            return SearchCredentialCheck("unknown")

        return await asyncio.to_thread(decode)

    async def search(
        self,
        source_id: str,
        vendor: str,
        service_id: str,
        credential_ref: str | None,
        request: Mapping[str, Any],
        *,
        on_sent: Callable[[], Awaitable[None] | None] | None = None,
    ) -> SearchResponse:
        if service_id == KEYLESS_EXA_SERVICE_ID:
            if (
                not model_hub_config.KEYLESS_EXA_ACTIVE
                or source_id != KEYLESS_EXA_SOURCE_ID
                or vendor != "exa-mcp"
            ):
                return SearchResponse(None, {}, None, "invalid_endpoint")
            service = search_service(vendor, "search")
            if service is None or service.get("service_id") != service_id:
                return SearchResponse(None, {}, None, "invalid_endpoint")
            return await self._keyless_exa_client.search(request, on_sent=on_sent)
        service = search_service(vendor, "search" if vendor in {"tavily", "exa"} else "openai_chat")
        if service is None or service.get("service_id") != service_id:
            return SearchResponse(None, {}, None, "invalid_endpoint")
        catalog = {"vendor": vendor, **service}
        return await self._search_http(
            catalog=catalog,
            credential_ref=credential_ref,
            method="POST",
            endpoint=str(service.get("endpoint") or ""),
            payload=request,
            on_sent=on_sent,
        )

    async def revoke_search_credential(self, credential_ref: str) -> None:
        await asyncio.to_thread(self.state_store.revoke_search_credential, credential_ref)

    async def fetch(
        self,
        source_id: str,
        vendor: str,
        service_id: str,
        credential_ref: str | None,
        request: Mapping[str, Any],
        *,
        on_sent: Callable[[], Awaitable[None] | None] | None = None,
    ) -> SearchResponse:
        from vibe.model_hub_runtime.fetch_catalog import fetch_service_catalog

        if service_id == KEYLESS_EXA_SERVICE_ID:
            if (
                not model_hub_config.KEYLESS_EXA_ACTIVE
                or source_id != KEYLESS_EXA_SOURCE_ID
                or vendor != "exa-mcp"
                or credential_ref is not None
            ):
                return SearchResponse(None, {}, None, "invalid_endpoint")
            service = next(
                (entry for entry in fetch_service_catalog() if entry.get("service_id") == service_id),
                None,
            )
            if service is None:
                return SearchResponse(None, {}, None, "invalid_endpoint")
            return await self._keyless_exa_client.fetch(request, on_sent=on_sent)

        # Keyed services use the same custody and bounded HTTP transport as search,
        # but their immutable fetch catalog owns a different endpoint and body shape.
        service = next(
            (
                entry for entry in fetch_service_catalog()
                if entry.get("service_id") == service_id and entry.get("vendor") == vendor
                and entry.get("kind") == "service"
                and (entry.get("source_id") is None)
            ),
            None,
        )
        if service is None or vendor not in {"tavily", "exa", "deepseek"} or credential_ref is None:
            # The built-in Reader is the only credentialless HTTP fetch service.
            if vendor != "jina-reader" or credential_ref is not None:
                return SearchResponse(None, {}, None, "invalid_endpoint")
            service = next(
                (
                    entry for entry in fetch_service_catalog()
                    if entry.get("service_id") == service_id and entry.get("vendor") == vendor
                    and entry.get("source_id") == source_id and entry.get("kind") == "service"
                ),
                None,
            )
            if service is None:
                return SearchResponse(None, {}, None, "invalid_endpoint")
        payload = dict(request)
        request_spec = service.get("request") if isinstance(service.get("request"), Mapping) else {}
        headers = request_spec.get("headers") if isinstance(request_spec.get("headers"), Mapping) else {}
        if isinstance(service.get("headers"), Mapping):
            headers = {**headers, **service["headers"]}
        if vendor == "jina-reader":
            headers = {**headers, "User-Agent": f"Avibe/{AVIBE_VERSION}"}
        return await self._search_http(
            catalog={"vendor": vendor, **service},
            credential_ref=credential_ref,
            method="POST",
            endpoint=str(service.get("endpoint") or ""),
            payload=payload,
            extra_headers=headers or None,
            on_sent=on_sent,
        )

    async def provision_oauth_credential(
        self,
        source_id: str,
        vendor: str,
        material: Mapping[str, object],
        *,
        on_reserved: Callable[[str], None] | None = None,
    ) -> str:
        normalized_vendor = vendor.strip().lower()
        auth_type = {"anthropic": "claude", "openai": "codex"}.get(normalized_vendor)
        if auth_type is None:
            raise EngineStateError("native OAuth vendor is unsupported")
        if not isinstance(material, Mapping):
            raise EngineStateError("native OAuth material is invalid")
        payload = dict(material)
        payload["type"] = auth_type
        auth_name = f"avibe-migration-{uuid.uuid4().hex}.json"
        return await run_owned_in_thread(
            self.state_store.stage_oauth_credential,
            source_id,
            normalized_vendor,
            auth_name,
            payload,
            on_reserved=on_reserved,
        )

    async def activate_oauth_credential(self, credential_ref: str) -> None:
        """Publish a staged grant without replacing a live auth file."""

        async with self._routing_lock:
            await self._transports_idle.wait()

            def publish_grant(running: EngineClient | None):
                return (*self.state_store.activate_oauth_auth_file(credential_ref), running)

            # Published under the lifecycle exclusion: an engine a previous service
            # left running is reaped first, so none can load or rotate the new grant
            # outside this service's reconcile below.
            auth_name, payload, _prefix, _already_active, client = await run_owned_in_thread(
                self.supervisor.with_engine_excluded,
                publish_grant,
            )
            if client is None:
                # The next ordered lifecycle step starts CPA. The atomically
                # published watched file is the source of truth; no management
                # upload is needed while the engine is down.
                return

            expected_provider = str(payload.get("type") or "").strip().lower()
            try:
                inventory = await run_owned_in_thread(_auth_inventory, client)
            except EngineClientError as exc:
                raise EngineStateError("OAuth activation could not inspect the engine") from exc
            matching = [auth for auth in inventory.values() if auth.name == auth_name or auth.identity == auth_name]
            if len(matching) > 1:
                raise EngineStateError("OAuth activation auth record is ambiguous")
            if matching:
                if matching[0].provider != expected_provider:
                    raise EngineStateError("OAuth activation auth record conflicts")
                await run_owned_in_thread(
                    self.state_store.mark_oauth_engine_published,
                    credential_ref,
                )
                return

            # The local file is already visible. A GET followed by POST is
            # unsafe: CPA's watcher can register/rotate the file between those
            # calls, after which POST would re-upload stale R0 bytes. Use the
            # supervisor's existing watched-file reconcile path instead.
            restart_if_running = getattr(self.supervisor, "restart_if_running", None)
            if not callable(restart_if_running):
                raise EngineStateError("OAuth activation could not reconcile engine")
            try:
                await run_owned_in_thread(restart_if_running)
            except Exception as exc:
                raise EngineStateError("OAuth activation could not reconcile engine") from exc

            client = await asyncio.to_thread(self.supervisor.client_if_running)
            if client is None:
                raise EngineStateError("OAuth activation could not reconcile engine")
            try:
                inventory = await run_owned_in_thread(_auth_inventory, client)
            except EngineClientError as exc:
                raise EngineStateError("OAuth activation could not inspect the engine") from exc
            matching = [auth for auth in inventory.values() if auth.name == auth_name or auth.identity == auth_name]
            if len(matching) > 1:
                raise EngineStateError("OAuth activation auth record is ambiguous")
            if not matching:
                raise EngineStateError("OAuth activation could not reconcile engine")
            if matching[0].provider != expected_provider:
                raise EngineStateError("OAuth activation auth record conflicts")
            await run_owned_in_thread(
                self.state_store.mark_oauth_engine_published,
                credential_ref,
            )

            return

    async def validate_oauth_credential(self, credential_ref: str) -> None:
        """Require an upstream authentication witness without inference."""

        async with self._routing_lock:
            await self._transports_idle.wait()
            metadata = await asyncio.to_thread(
                self.state_store.credential_metadata,
                credential_ref,
            )
            if metadata.get("kind") != "oauth":
                raise EngineStateError("OAuth credential is unavailable")
            if metadata.get("activation_state") == "staged":
                raise EngineStateError("OAuth credential is not active")
            normalized_vendor = str(metadata.get("vendor") or "").strip().lower()
            expected_provider = {
                "anthropic": "claude",
                "openai": "codex",
            }.get(normalized_vendor)
            if expected_provider is None:
                raise EngineStateError("OAuth credential validation is unsupported")
            try:
                client = await run_owned_in_thread(self.supervisor.client)
            except EngineConfigLostError:
                # Already drained: the routing lock is held and transports are idle.
                await self._restart_lost_engine()
                client = await run_owned_in_thread(self.supervisor.client)
            try:
                inventory = await run_owned_in_thread(_auth_inventory, client)
            except EngineClientError as exc:
                raise EngineStateError("OAuth credential validation could not inspect the engine") from exc
            auth_name = str(metadata.get("auth_name") or "")
            matches = [
                auth
                for auth in inventory.values()
                if (auth.name == auth_name or auth.identity == auth_name)
                and auth.provider == expected_provider
                and auth.auth_index
            ]
            if len(matches) != 1:
                raise EngineStateError("OAuth credential validation is inconclusive")
            # CPA v7.3.16 loses refresh failure details ("token expired") and
            # also puts request failures in status_message. None of those
            # inventory strings proves that a refresh grant was rejected.
            try:
                await run_owned_in_thread(
                    _probe_oauth_control_plane_witness,
                    client=client,
                    auth=matches[0],
                    vendor=normalized_vendor,
                )
            except (EngineClientError, OSError) as exc:
                raise EngineStateError("OAuth credential validation failed") from exc

    async def matches_api_key_credential(
        self,
        credential_ref: str,
        vendor: str,
        protocol: str,
        secret: str,
        base_url: str | None,
        *,
        auth_scheme: str | None = None,
    ) -> bool:
        return await asyncio.to_thread(
            self.state_store.matches_api_key_credential,
            credential_ref,
            vendor,
            protocol,
            secret,
            base_url,
            **({"auth_scheme": auth_scheme} if auth_scheme is not None else {}),
        )

    async def credential_auth_scheme(self, credential_ref: str) -> str | None:
        return await asyncio.to_thread(self.state_store.credential_auth_scheme, credential_ref)

    async def credential_address(self, credential_ref: str) -> str | None:
        return await asyncio.to_thread(self._credential_address, credential_ref)

    def _credential_address(self, credential_ref: str) -> str | None:
        """Settle the address the same way ``bind_source`` settles it.

        Only an OAuth credential records an address of its own, and one written
        by an older release may not have even that. Every other bound Source is
        addressed by the prefix its record holds, which ``bind_source`` reaches
        for next. Reading just the credential would therefore report no address
        for a Source the engine addresses perfectly well, and the repair would
        decline exactly the ids that need it.
        """

        metadata = self.state_store.credential_metadata_if_present(credential_ref)
        prefix = (metadata or {}).get("prefix")
        if isinstance(prefix, str) and prefix:
            return prefix
        record = next(
            (source for source in self.state_store.list_sources() if source.credential_ref == credential_ref),
            None,
        )
        return record.prefix if record is not None and record.prefix else None

    async def retarget_api_key_credential(
        self,
        credential_ref: str,
        vendor: str,
        protocol: str,
        base_url: str | None,
    ) -> str:
        metadata = await asyncio.to_thread(
            self.state_store.credential_metadata,
            credential_ref,
        )
        normalized_vendor = vendor.strip().lower()
        if (
            metadata.get("kind") != "api_key"
            or metadata.get("vendor") != normalized_vendor
            or metadata.get("protocol") != protocol
        ):
            raise EngineStateError("credential does not match retarget request")
        secret = await asyncio.to_thread(
            self.state_store.read_api_key,
            credential_ref,
        )
        return await asyncio.to_thread(
            self.state_store.store_api_key,
            secret,
            vendor=normalized_vendor,
            protocol=protocol,
            base_url=base_url,
            **({"auth_scheme": metadata["auth_scheme"]} if metadata.get("auth_scheme") is not None else {}),
        )

    async def credential_supports_refresh(self, credential_ref: str) -> bool:
        metadata = await asyncio.to_thread(
            self.state_store.credential_metadata,
            credential_ref,
        )
        return metadata.get("kind") == "oauth"

    async def provision_transient_credential(
        self,
        vendor: str,
        secret: str,
        base_url: str | None,
        *,
        auth_scheme: str | None = None,
        on_reserved: Callable[[str], None] | None = None,
    ) -> str:
        """Store an unbound observation key until the observation settles.

        The observation seam determines protocol from upstream responses, so the
        legacy temporary record uses a neutral engine-store protocol marker.
        Explicit Bearer is restricted to Anthropic interfaces. Neither marker
        supplies authentication evidence; observation still needs upstream proof.
        """

        validate_api_key_auth_scheme(vendor, None, base_url, secret, auth_scheme)
        return await run_owned_in_thread(
            self.state_store.store_api_key,
            secret,
            vendor=vendor,
            protocol="anthropic" if auth_scheme == "bearer" else "openai_chat",
            base_url=base_url,
            **({"auth_scheme": auth_scheme} if auth_scheme is not None else {}),
            on_reserved=on_reserved,
        )

    async def revoke_api_key_credential(self, credential_ref: str) -> None:
        await asyncio.to_thread(self.state_store.assert_credential_unbound, credential_ref)
        is_search = await asyncio.to_thread(
            self.state_store.api_key_credential_is_search,
            credential_ref,
        )
        if not is_search:
            await asyncio.to_thread(self.supervisor.invalidate_configs)
        await asyncio.to_thread(self.state_store.revoke_api_key_credential, credential_ref)

    async def revoke_credential(self, credential_ref: str) -> None:
        await asyncio.to_thread(
            self.state_store.assert_credential_unbound,
            credential_ref,
        )
        metadata = await asyncio.to_thread(
            self.state_store.credential_metadata_if_present,
            credential_ref,
        )
        if metadata is not None and metadata.get("protocol") == "search":
            await self.revoke_search_credential(credential_ref)
            return
        auth_name = metadata.get("auth_name") if metadata is not None and metadata.get("kind") == "oauth" else None
        if auth_name:
            if metadata.get("activation_state") != "staged":

                def remove_grant(client: EngineClient | None) -> None:
                    if client is not None:
                        try:
                            client.management_request(
                                "DELETE",
                                "/auth-files",
                                query={"name": str(auth_name)},
                                timeout=1.0,
                            )
                        except EngineClientError as exc:
                            raise EngineStateError("unable to remove OAuth auth file") from exc
                    self.state_store.delete_oauth_auth_file(str(auth_name))

                # One supervisor operation: an engine left running by a previous
                # service is reaped first, and none can start and load the grant
                # before its file is gone.
                await asyncio.to_thread(self.supervisor.with_engine_excluded, remove_grant)
                await asyncio.to_thread(
                    self.state_store.audit_auth_permissions,
                    enforce=True,
                )
        await asyncio.to_thread(self.supervisor.invalidate_configs)
        await asyncio.to_thread(self.state_store.revoke_credential, credential_ref)

    async def cleanup_orphaned_oauth_material(self, credential_ref: str) -> bool:
        try:
            await asyncio.to_thread(
                self.state_store.assert_credential_unbound,
                credential_ref,
            )
            metadata = await asyncio.to_thread(
                self.state_store.credential_metadata_if_present,
                credential_ref,
            )
        except EngineStateError:
            return False
        # Revocation is ordered after both auth-file deletions. Therefore an
        # absent ref proves cleanup already converged, including never-created
        # refs whose postcondition held vacuously.
        if metadata is None:
            try:
                await asyncio.to_thread(
                    self.state_store.revoke_credential,
                    credential_ref,
                )
            except EngineStateError:
                return False
            return True
        if metadata.get("kind") != "oauth":
            return False
        if metadata.get("activation_state") == "staged":
            try:
                await asyncio.to_thread(
                    self.state_store.revoke_credential,
                    credential_ref,
                )
            except EngineStateError:
                return False
            return True
        auth_name = metadata.get("auth_name")
        if not isinstance(auth_name, str) or not auth_name:
            return False
        return await self._cleanup_oauth_material(auth_name, credential_ref)

    async def discover_models(
        self,
        vendor: str,
        protocol: str,
        base_url: str | None,
        credential_ref: str,
        *,
        start_engine: bool = True,
    ) -> Sequence[DiscoveredModel]:
        metadata = await asyncio.to_thread(
            self.state_store.credential_metadata,
            credential_ref,
        )
        normalized_vendor = vendor.strip().lower()
        if metadata["kind"] == "oauth":
            if metadata.get("vendor") != normalized_vendor or base_url is not None:
                raise EngineStateError("credential does not match discovery target")
            if start_engine:
                client = await self._engine_call(self.supervisor.client)
            else:
                client = await run_owned_in_thread(self.supervisor.client_if_running)
                if client is None:
                    raise ModelDiscoveryError("engine is not running")
            # Owned and bounded: a cancelled listing (Hub shutdown) returns only
            # once its worker has stopped using the engine, within the
            # controller's runtime-work shutdown grace.
            payload = await run_owned_in_thread(
                client.management_request,
                "GET",
                "/auth-files/models",
                query={"name": str(metadata["auth_name"])},
                timeout=_ENGINE_MODEL_LISTING_TIMEOUT_SECONDS,
            )
            prefix = metadata.get("prefix")
            return _discovered_models(
                payload,
                str(prefix) if isinstance(prefix, str) and prefix else None,
            )
        normalized_base_url = await asyncio.to_thread(
            self.state_store.validate_api_key_target,
            credential_ref,
            vendor=normalized_vendor,
            protocol=protocol,
            base_url=base_url,
        )
        secret = await asyncio.to_thread(self.state_store.read_api_key, credential_ref)
        try:
            return await probe_models(
                vendor=normalized_vendor,
                protocol=protocol,
                base_url=normalized_base_url,
                secret=secret,
                **({"auth_scheme": metadata["auth_scheme"]} if metadata.get("auth_scheme") is not None else {}),
            )
        except EngineClientError as exc:
            raise ModelDiscoveryError("model discovery failed") from exc

    async def observe_source(
        self,
        vendor: str,
        base_url: str | None,
        credential_ref: str,
        protocol_order: Sequence[str],
    ) -> SourceObservation:
        """Observe sequentially and stop at the first persistable proof.

        ``protocol_order`` orders attempts only, with one exception: a hub
        subscription whose serving protocol the engine declares is answered by
        that pin whenever the order contains it, because no other candidate
        could be served. A protocol-specific response
        with accepted authentication proves the current attempt and terminates
        observation. A shipped vendor catalog pin or a concrete `custom`
        declaration also terminates observation after a shaped success, and,
        because that interface's owner is already named, may take its
        authentication from the model listing when the model-less probe leaves
        it unknown. Schema errors that no listing answers remain unverified;
        explicit unverified saving belongs to
        Source creation, not this observation. A shaped rejection is
        recorded while later candidates continue on Auto detect. Vendor, URL,
        and order never create a conclusion on their own; `custom` Auto still requires response-backed
        proof, and exhausting that path without one remains ambiguous.
        """

        metadata = await asyncio.to_thread(
            self.state_store.credential_metadata,
            credential_ref,
        )
        normalized_vendor = vendor.strip().lower()
        try:
            normalized_base_url = normalize_model_hub_base_url(base_url)
        except (TypeError, ValueError):
            raise EngineStateError("invalid source base URL") from None
        if metadata.get("vendor") != normalized_vendor:
            raise EngineStateError("credential does not match observation target")
        credential_kind = metadata.get("kind")
        auth_scheme = metadata.get("auth_scheme")
        scheme_options = {"auth_scheme": auth_scheme} if auth_scheme is not None else {}
        secret: str | None = None
        oauth_auth: _AuthRecord | None = None
        if credential_kind == "api_key":
            if metadata.get("base_url") != normalized_base_url:
                raise EngineStateError("credential does not match observation target")
            secret = await asyncio.to_thread(self.state_store.read_api_key, credential_ref)
            if auth_scheme is not None:
                for protocol in protocol_order:
                    validate_api_key_auth_scheme(
                        normalized_vendor,
                        protocol,
                        base_url,
                        secret,
                        auth_scheme,
                    )
        elif credential_kind == "oauth":
            if normalized_base_url is not None:
                raise EngineStateError("credential does not match observation target")
            client = await self._engine_call(self.supervisor.client)
            inventory = await asyncio.to_thread(_auth_inventory, client)
            auth_name = str(metadata.get("auth_name") or "")
            matches = [auth for auth in inventory.values() if auth.name == auth_name or auth.identity == auth_name]
            if len(matches) != 1 or not matches[0].auth_index:
                raise EngineStateError("OAuth credential binding is unavailable")
            oauth_auth = matches[0]
        else:
            raise EngineStateError("credential does not match observation target")

        if credential_kind == "oauth":
            served_protocol = hub_subscription_serving_protocol(normalized_vendor)
            if served_protocol is not None and served_protocol in protocol_order:
                # A pinned subscription's protocol does not depend on the order it
                # is asked in: the engine serves this auth kind on one surface,
                # and every other candidate would only be attempted to be refused.
                # A caller that asks for an order excluding the pin is left on the
                # ordinary path, where it reaches that refusal for itself.
                protocol_order = (served_protocol,)

        failures: list[EngineClientError] = []
        received_rejection = False
        received_proven_unknown = False
        received_unproven_response = False
        received_accepted_unproven_response = False
        response_evidence_by_protocol: dict[str, _ProtocolEvidence] = {}
        ruled_out_protocols: set[str] = set()
        for protocol in protocol_order:
            if protocol not in MODEL_PROTOCOLS:
                raise EngineStateError("unsupported source protocol")
            owner_scoped_protocol = _protocol_is_persistable_without_shape_proof(
                credential_kind=str(credential_kind),
                vendor=normalized_vendor,
                protocol=protocol,
                protocol_order=protocol_order,
            )
            try:
                if credential_kind == "api_key":
                    evidence = await _probe_protocol_response(
                        vendor=normalized_vendor,
                        protocol=protocol,
                        base_url=base_url,
                        secret=secret or "",
                        **scheme_options,
                    )
                elif credential_kind == "oauth" and owner_scoped_protocol:
                    # A pinned subscription has no upstream to probe: the engine
                    # holds the credential and serves it on the surface
                    # `_HUB_SUBSCRIPTION_PROTOCOLS` names. The completed grant is
                    # the evidence, so this stands in for a response that was
                    # accepted without narrowing the protocol by shape — which is
                    # what the pin is there to narrow instead.
                    evidence = _ENGINE_SERVED_SUBSCRIPTION_EVIDENCE
                else:
                    assert oauth_auth is not None
                    evidence = await asyncio.to_thread(
                        _probe_oauth_protocol_response,
                        client=client,
                        auth=oauth_auth,
                        vendor=normalized_vendor,
                        protocol=protocol,
                    )
            except EngineClientError as exc:
                failures.append(exc)
                continue
            if evidence.authentication is _AuthenticationEvidence.REJECTED:
                received_rejection = True
                ruled_out_protocols.add(protocol)
                continue
            if (
                credential_kind == "api_key"
                and owner_scoped_protocol
                and evidence.authentication is _AuthenticationEvidence.UNKNOWN
            ):
                # This interface already has an owner, so the only thing left to
                # establish is whether it accepts the credential -- and the
                # model-less probe just declined to say. Its model listing
                # answers that, and is the inventory this rung would fetch next
                # anyway, so a listing that turns out to be credential-gated
                # both verifies the source and fills it in one pass.
                witness = await _authenticate_with_models_witness(
                    vendor=normalized_vendor,
                    protocol=protocol,
                    base_url=base_url,
                    secret=secret or "",
                    **scheme_options,
                )
                if witness.credential is _ModelsWitness.REJECTED:
                    received_rejection = True
                    ruled_out_protocols.add(protocol)
                    continue
                if witness.credential is _ModelsWitness.ACCEPTED:
                    return make_source_observation(
                        outcome=ObservationOutcome.OBSERVED,
                        reachable=True,
                        authenticated=True,
                        protocol=protocol,
                        discovery=ObservationDiscovery.SUCCEEDED,
                        models=witness.models,
                    )
            proved_protocol: str | None = None
            if evidence.protocol is _ProtocolProof.PROVEN:
                if evidence.authentication is _AuthenticationEvidence.UNKNOWN:
                    received_proven_unknown = True
                    continue
                proved_protocol = protocol
            else:
                received_unproven_response = True
                if evidence.authentication is _AuthenticationEvidence.ACCEPTED:
                    received_accepted_unproven_response = True
                    if owner_scoped_protocol:
                        proved_protocol = protocol
                if _pairwise_positive_exclusion(evidence):
                    ruled_out_protocols.add(protocol)
                response_evidence_by_protocol[protocol] = evidence
                if proved_protocol is None:
                    continue
            try:
                if credential_kind == "api_key":
                    models = await probe_models(
                        vendor=normalized_vendor,
                        protocol=proved_protocol,
                        base_url=base_url,
                        secret=secret or "",
                        **scheme_options,
                    )
                else:
                    models = await self.discover_models(
                        normalized_vendor,
                        proved_protocol,
                        None,
                        credential_ref,
                    )
            except (EngineClientError, ModelDiscoveryError):
                discovery = ObservationDiscovery.FAILED
                models = ()
            else:
                discovery = ObservationDiscovery.SUCCEEDED
            return make_source_observation(
                outcome=ObservationOutcome.OBSERVED,
                reachable=True,
                authenticated=True,
                protocol=proved_protocol,
                discovery=discovery,
                models=tuple(models),
            )

        considered_protocols = frozenset(protocol_order)
        proved_protocol = _openai_family_elimination_proof(
            response_evidence_by_protocol,
            considered_protocols=considered_protocols,
            ruled_out_protocols=frozenset(ruled_out_protocols),
        ) or _anthropic_wrapperless_elimination_proof(
            response_evidence_by_protocol,
            considered_protocols=considered_protocols,
            ruled_out_protocols=frozenset(ruled_out_protocols),
        )
        if proved_protocol is not None:
            try:
                if credential_kind == "api_key":
                    models = await probe_models(
                        vendor=normalized_vendor,
                        protocol=proved_protocol,
                        base_url=base_url,
                        secret=secret or "",
                        **scheme_options,
                    )
                else:
                    models = await self.discover_models(
                        normalized_vendor,
                        proved_protocol,
                        None,
                        credential_ref,
                    )
            except (EngineClientError, ModelDiscoveryError):
                discovery = ObservationDiscovery.FAILED
                models = ()
            else:
                discovery = ObservationDiscovery.SUCCEEDED
            return make_source_observation(
                outcome=ObservationOutcome.OBSERVED,
                reachable=True,
                authenticated=True,
                protocol=proved_protocol,
                discovery=discovery,
                models=tuple(models),
            )

        if received_accepted_unproven_response:
            # A shaped request error already proved the credential was accepted
            # even when the response family never narrowed to one persisted
            # protocol.
            return make_source_observation(
                outcome=ObservationOutcome.AMBIGUOUS,
                reachable=True,
                authenticated=True,
                protocol=None,
                discovery=ObservationDiscovery.NOT_ATTEMPTED,
                models=(),
            )
        if received_proven_unknown:
            return make_source_observation(
                outcome=ObservationOutcome.ADAPTER_ERROR,
                reachable=True,
                authenticated=None,
                protocol=None,
                discovery=ObservationDiscovery.NOT_ATTEMPTED,
                models=(),
            )
        if received_unproven_response and not considered_protocols.issubset(ruled_out_protocols):
            return make_source_observation(
                outcome=ObservationOutcome.AMBIGUOUS,
                reachable=True,
                authenticated=None,
                protocol=None,
                discovery=ObservationDiscovery.NOT_ATTEMPTED,
                models=(),
            )
        if received_rejection:
            return make_source_observation(
                outcome=ObservationOutcome.AUTHENTICATION_FAILED,
                reachable=True,
                authenticated=False,
                protocol=None,
                discovery=ObservationDiscovery.NOT_ATTEMPTED,
                models=(),
            )
        if any(error.error_type == "timeout" for error in failures):
            return make_source_observation(
                outcome=ObservationOutcome.TIMEOUT,
                reachable=None,
                authenticated=None,
                protocol=None,
                discovery=ObservationDiscovery.NOT_ATTEMPTED,
                models=(),
            )
        if any(error.error_type in {"network_error", "ConnectionError", "URLError"} for error in failures):
            return make_source_observation(
                outcome=ObservationOutcome.UNREACHABLE,
                reachable=False,
                authenticated=None,
                protocol=None,
                discovery=ObservationDiscovery.NOT_ATTEMPTED,
                models=(),
            )
        return make_source_observation(
            outcome=ObservationOutcome.ADAPTER_ERROR,
            reachable=None,
            authenticated=None,
            protocol=None,
            discovery=ObservationDiscovery.NOT_ATTEMPTED,
            models=(),
        )

    async def start_oauth(self, source_id: str, vendor: str) -> OAuthFlowState:
        await asyncio.to_thread(self.state_store.validate_source_id, source_id)
        normalized_vendor = vendor.strip().lower()
        endpoint = _OAUTH_ENDPOINTS.get(normalized_vendor)
        if endpoint is None:
            raise EngineStateError("OAuth vendor lacks a Model Hub subscription flow")
        engine_endpoint, callback_provider, auth_provider = endpoint
        with self._oauth_lock:
            self._expire_oauth_flows_locked()
            if auth_provider in self._active_oauth_providers:
                raise EngineStateError("an OAuth flow for this provider is already active")
            self._active_oauth_providers.add(auth_provider)
        try:
            client = await self._engine_call(self.supervisor.client)
            before = await asyncio.to_thread(_auth_inventory, client)
            payload = await asyncio.to_thread(
                client.management_request,
                "GET",
                engine_endpoint,
                # Every start Avibe makes is Web-UI-originated, which is all this
                # flag states. The engine decides what follows from it: a vendor
                # whose grant comes back through a redirect starts a forwarder
                # for it, and one that issues a device code has nothing to
                # forward and ignores the flag.
                query={"is_webui": "true"},
            )
            engine_state = str(payload.get("state") or "").strip()
            if not engine_state:
                raise EngineStateError("engine OAuth response omitted state")
            device_code = str(payload.get("user_code") or "").strip() or None
            flow_kind = str(payload.get("flow") or "").strip().lower()
            expects = "none" if device_code or flow_kind == "device" else "paste_callback_url"
            expires_in = max(1, int(payload.get("expires_in") or 300))
            flow = _OAuthFlow(
                flow_id=f"oaf_{secrets.token_hex(12)}",
                source_id=source_id,
                engine_state=engine_state,
                vendor=normalized_vendor,
                callback_provider=callback_provider,
                auth_provider=auth_provider,
                expects=expects,
                auth_url=str(payload.get("url") or payload.get("verification_uri") or "").strip() or None,
                device_code=device_code,
                expires_at_iso=(datetime.now(timezone.utc) + timedelta(seconds=expires_in)).isoformat(),
                before_auth_fingerprints={identity: record.fingerprint for identity, record in before.items()},
                grant_write_possible=expects == "none",
            )
        except Exception:
            with self._oauth_lock:
                self._active_oauth_providers.discard(auth_provider)
            raise
        with self._oauth_lock:
            self._oauth_flows[flow.flow_id] = flow
        return flow.snapshot()

    def subscription_account_label(self, source_id: str, vendor: str, credential_ref: str) -> str | None:
        endpoint = _OAUTH_ENDPOINTS.get(vendor)
        if endpoint is None:
            return None
        return self.state_store.oauth_account_label(
            credential_ref, source_id=source_id, vendor=vendor, auth_provider=endpoint[2],
        )

    async def subscription_quota(self, source_id: str, vendor: str, credential_ref: str) -> dict[str, Any]:
        """Read the bound grant's rate-limit windows without starting the engine."""

        normalized_vendor = vendor.strip().lower()
        endpoint = _OAUTH_ENDPOINTS.get(normalized_vendor)
        if endpoint is None or normalized_vendor not in _SUBSCRIPTION_QUOTA_URLS:
            raise SubscriptionQuotaError("unsupported")
        try:
            metadata = await asyncio.to_thread(self.state_store.credential_metadata, credential_ref)
        except (EngineStateError, OSError, ValueError):
            raise SubscriptionQuotaError("unavailable") from None
        if (
            metadata.get("kind") != "oauth"
            or metadata.get("source_id") not in {None, source_id}
            or str(metadata.get("vendor") or "").strip().lower() != normalized_vendor
            or metadata.get("activation_state") not in {None, "active"}
        ):
            raise SubscriptionQuotaError("unavailable")
        # A presentation read never starts, repairs, or restarts the engine.
        client = await asyncio.to_thread(self.supervisor.client_if_running)
        if client is None:
            raise SubscriptionQuotaError("unavailable")
        try:
            inventory = await run_owned_in_thread(_auth_inventory, client)
        except (EngineClientError, OSError):
            raise SubscriptionQuotaError("unavailable") from None
        auth_name = str(metadata.get("auth_name") or "")
        matches = [
            auth
            for auth in inventory.values()
            if (auth.name == auth_name or auth.identity == auth_name)
            and auth.provider == endpoint[2]
            and auth.auth_index
        ]
        if len(matches) != 1:
            raise SubscriptionQuotaError("unavailable")
        try:
            return await run_owned_in_thread(
                _fetch_subscription_quota,
                client=client,
                auth=matches[0],
                vendor=normalized_vendor,
            )
        except (EngineClientError, OSError):
            raise SubscriptionQuotaError("unavailable") from None

    async def oauth_status(self, flow_id: str) -> OAuthFlowState:
        flow = self._get_flow(flow_id)
        async with flow.operation_lock:
            self._expire_oauth_flow(flow)
            if flow.state in {"success", "failed", "cancelled"}:
                return flow.snapshot()
            try:
                client = await self._engine_call(self.supervisor.client)
                payload = await asyncio.to_thread(
                    client.management_request,
                    "GET",
                    "/get-auth-status",
                    query={"state": flow.engine_state},
                )
                status = str(payload.get("status") or "").strip().lower()
                if status == "ok":
                    await self._complete_oauth(flow, client)
                elif status == "error":
                    reason = str(payload.get("error") or "")
                    self._fail_flow(flow, _oauth_engine_failure_key(reason), detail=reason)
                elif flow.state != "verifying":
                    flow.state = "awaiting_action"
            except (EngineClientError, EngineUnavailableError) as error:
                self._fail_flow(flow, "models.oauth.engine_unavailable", detail=str(error))
            return flow.snapshot()

    async def submit_oauth(self, flow_id: str, value: str) -> OAuthFlowState:
        flow = self._get_flow(flow_id)
        async with flow.operation_lock:
            self._expire_oauth_flow(flow)
            if flow.state in {"success", "failed", "cancelled"}:
                raise EngineStateError("OAuth flow is no longer active")
            if flow.expects == "none":
                raise EngineStateError("this OAuth flow does not accept a submission")
            submitted = value.strip()
            if not submitted:
                raise EngineStateError("OAuth submission is empty")
            address = _oauth_callback_address(submitted)
            if address is not None:
                answers = {
                    key: answer.strip()
                    for key, answer in urllib.parse.parse_qsl(urllib.parse.urlsplit(address).query)
                }
                # The rejections that provably write nothing and leave the
                # session waiting, decided here where the value is known rather
                # than from an engine status several refusals share. An address
                # without an answer is refused by the engine before it reads its
                # session. An answer to another sign-in link would reach the
                # provider, which refuses its code for this flow's verifier —
                # and that refusal ends the session the user could have pasted
                # the right address into.
                rejection: Literal["no_answer", "other_attempt"] | None = None
                if not any(answers.get(key) for key in ("code", "error", "error_description")):
                    rejection = "no_answer"
                elif answers.get("state") and answers["state"] != flow.engine_state:
                    rejection = "other_attempt"
                if rejection is not None:
                    logger.info(
                        "OAuth submission rejected before the engine: flow=%s provider=%s reason=%s",
                        flow.flow_id,
                        flow.callback_provider,
                        rejection,
                    )
                    raise OAuthSubmissionRejectedError(flow_id, rejection)
            # Any failure after submission begins cannot prove whether the
            # engine wrote grant material.
            flow.grant_write_possible = True
            payload: dict[str, str] = {
                "provider": flow.callback_provider,
                "state": flow.engine_state,
            }
            if address is not None:
                payload["redirect_url"] = address
            else:
                payload["code"] = submitted
            try:
                client = await self._engine_call(self.supervisor.client)
                await asyncio.to_thread(
                    client.management_request,
                    "POST",
                    "/oauth-callback",
                    payload=payload,
                )
            except (EngineClientError, EngineUnavailableError) as error:
                self._fail_flow(flow, "models.oauth.submission_failed", detail=str(error))
                return flow.snapshot()
            flow.state = "verifying"
            return flow.snapshot()

    async def cancel_oauth(self, flow_id: str) -> None:
        flow = self._get_flow(flow_id)
        async with flow.operation_lock:
            self._expire_oauth_flow(flow)
            if flow.state in {"success", "failed", "cancelled"}:
                return
            try:
                client = await self._engine_call(self.supervisor.client)
                await asyncio.to_thread(
                    client.management_request,
                    "DELETE",
                    "/oauth-session",
                    query={"state": flow.engine_state},
                )
            except (EngineClientError, EngineUnavailableError):
                pass
            self._mark_retention_unknown_if_needed(flow)
            flow.state = "cancelled"
            self._release_provider(flow)

    async def invoke(
        self,
        source_id: str,
        model_id: str,
        request: Mapping[str, Any],
        stream: bool,
        origin: str,
        *,
        on_admitted: Callable[[], None] | None = None,
    ) -> EngineInvokeHandle:
        async with self._routing_lock:
            source = await asyncio.to_thread(self.state_store.get_source, source_id)
            if source is None:
                raise EngineStateError("source is not registered")
            if source.allowed_origins and origin not in source.allowed_origins:
                raise OriginNotAllowedError(f"origin {origin!r} is not allowed to use source {source_id!r}")
            try:
                client = await self._locked_engine_call(self.supervisor.client)
            except EngineUnavailableError as exc:
                return completed_handle(
                    RawCallOutcome(
                        kind=RawOutcomeKind.NETWORK_ERROR,
                        http_status=None,
                        error_code="engine_down",
                        redacted_message=None,
                        stream_started=False,
                        model_id=model_id,
                        source_id=source_id,
                        os_errno=local_os_errno(exc),
                    )
                )
            release = self._acquire_transport()
            request_sent = self._hold_unsent_request()
            try:
                if on_admitted is not None:
                    on_admitted()
            except BaseException:
                request_sent()
                release()
                raise
        try:
            request_protocol = {
                "claude": "anthropic",
                "codex": "openai_responses",
            }.get(origin, getattr(request, "protocol", None) or source.protocol)
            handle = await client.invoke(
                source,
                model_id,
                request,
                stream=stream,
                request_protocol=request_protocol,
                request_headers=getattr(request, "headers", None),
                on_transport_done=release,
                on_request_sent=request_sent,
                # Vibey gives measured streams its larger caller-owned pre-response
                # patience; the engine resumes the measured inter-byte bound once
                # the first response byte arrives.
                silence_bound_s=PROVIDER_SILENCE_TIMEOUT_S if origin == "vibey" else None,
            )
            if handle.outcome_available and engine_disowned_call(await handle.outcome()):
                # The engine's last health check vouches for it no longer: the
                # next admission checks it, finds the lost configuration, and
                # restores it once the open streams end (#2753, #2755).
                await asyncio.to_thread(self.supervisor.recheck_engine)
            return handle
        except BaseException:
            release()
            raise
        finally:
            request_sent()

    async def _complete_oauth(self, flow: _OAuthFlow, client: EngineClient) -> None:
        flow.grant_write_possible = True
        inventory = await asyncio.to_thread(_auth_inventory, client)
        provider_records = [record for record in inventory.values() if record.provider == flow.auth_provider]
        try:
            foreign = await asyncio.to_thread(self._foreign_bound_identities, provider_records, flow.source_id)
        except EngineStateError:
            self._set_retained_material(flow, RetainedMaterialDisposition.UNKNOWN)
            self._fail_flow(flow, "models.oauth.binding_failed")
            return
        changed = [
            record
            for record in provider_records
            if flow.before_auth_fingerprints.get(record.identity) != record.fingerprint
        ]
        # A record that did not exist before this flow is the login it produced.
        # Accounts other Sources already hold keep changing in the background
        # (refresh, status), so they only count when nothing new appeared: then
        # the login rewrote an existing file, which is either this Source's own
        # account (re-auth) or an account another Source already owns.
        fresh = [record for record in changed if record.identity not in flow.before_auth_fingerprints]
        candidates = fresh or [record for record in changed if record.identity not in foreign]
        if not fresh and candidates and len(candidates) != len(changed):
            # Existing records of this and another Source both changed: the
            # login may have rewritten either, so neither can be named.
            candidates = changed
        if not candidates and not changed and len(provider_records) == 1:
            candidates = provider_records
        if not candidates and changed:
            candidates = changed
        if len(candidates) != 1:
            if not candidates:
                flow.state = "verifying"
                return
            self._set_retained_material(flow, RetainedMaterialDisposition.UNKNOWN)
            self._fail_flow(flow, "models.oauth.ambiguous_engine_binding")
            return
        auth = candidates[0]
        if flow.auth_provider == "claude":
            try:
                # CPA only migrates Claude names while saving a new login.
                # Restore the existing ref before ownership or cleanup decisions.
                await asyncio.to_thread(self.state_store.reconcile_claude_login, auth.name)
                foreign = await asyncio.to_thread(
                    self._foreign_bound_identities, provider_records, flow.source_id,
                )
            except (EngineStateError, OSError):
                self._set_retained_material(flow, RetainedMaterialDisposition.UNKNOWN)
                self._fail_flow(flow, "models.oauth.binding_failed")
                return
        foreign_accounts = {
            record.account_id for record in provider_records if record.identity in foreign and record.account_id
        }
        if auth.identity in foreign or (auth.account_id and auth.account_id in foreign_accounts):
            # The same account is already a Source. A new file for it is this
            # flow's own material and is removed; an existing one belongs to the
            # other Source and is never touched.
            if auth.identity in foreign:
                self._set_retained_material(flow, RetainedMaterialDisposition.FOREIGN_SOURCE_REF)
            elif auth.identity not in flow.before_auth_fingerprints and await self._delete_auth_files(auth.name):
                self._set_retained_material(flow, RetainedMaterialDisposition.NONE)
            else:
                self._set_retained_material(flow, RetainedMaterialDisposition.UNKNOWN)
            self._fail_flow(flow, "models.oauth.account_already_added")
            return
        try:
            existing_credential_ref = await asyncio.to_thread(
                self.state_store.oauth_credential_ref,
                auth.name,
            )
        except EngineStateError:
            # The grant changed but duplicate persisted metadata means no single
            # ref can be named safely.
            self._set_retained_material(flow, RetainedMaterialDisposition.UNKNOWN)
            self._fail_flow(flow, "models.oauth.binding_failed")
            return

        existing_source_id: str | None = None
        if existing_credential_ref is not None:
            try:
                existing_credential = await asyncio.to_thread(
                    self.state_store.credential_metadata,
                    existing_credential_ref,
                )
            except EngineStateError:
                self._set_retained_material(flow, RetainedMaterialDisposition.UNKNOWN)
                self._fail_flow(flow, "models.oauth.binding_failed")
                return
            value = existing_credential.get("source_id")
            existing_source_id = str(value) if value else None

        try:
            credential_ref = await asyncio.to_thread(
                self.state_store.bind_oauth_credential,
                flow.source_id,
                flow.vendor,
                auth.name,
            )
        except EngineStateError:
            if existing_credential_ref is None or existing_source_id is None:
                self._set_retained_material(flow, RetainedMaterialDisposition.UNKNOWN)
            elif existing_source_id == flow.source_id:
                self._set_retained_material(
                    flow,
                    RetainedMaterialDisposition.FLOW_SOURCE_REF,
                    existing_credential_ref,
                )
            else:
                # The existing ref belongs to another source. Withhold it so a
                # consumer cannot revoke or journal foreign material.
                self._set_retained_material(
                    flow,
                    RetainedMaterialDisposition.FOREIGN_SOURCE_REF,
                )
            self._fail_flow(flow, "models.oauth.binding_failed")
            return

        try:
            credential = await asyncio.to_thread(
                self.state_store.credential_metadata,
                credential_ref,
            )
        except EngineStateError:
            self._set_retained_material(
                flow,
                RetainedMaterialDisposition.FLOW_SOURCE_REF,
                credential_ref,
            )
            self._fail_flow(flow, "models.oauth.binding_failed")
            return
        try:
            await asyncio.to_thread(
                client.management_request,
                "PATCH",
                "/auth-files/fields",
                payload={"name": auth.name, "prefix": credential["prefix"]},
            )
            await asyncio.to_thread(self.state_store.audit_auth_permissions, enforce=True)
        except (EngineClientError, EngineStateError):
            if existing_credential_ref is not None:
                self._set_retained_material(
                    flow,
                    RetainedMaterialDisposition.FLOW_SOURCE_REF,
                    credential_ref,
                )
            else:
                # Never destroy the only cleanup handle while grant material
                # may remain behind it. Both auth-file deletions must be
                # confirmed before revocation can discard the minted ref.
                if auth.identity not in flow.before_auth_fingerprints and await self._cleanup_oauth_material(
                    auth.name,
                    credential_ref,
                ):
                    self._set_retained_material(
                        flow,
                        RetainedMaterialDisposition.NONE,
                    )
                else:
                    self._set_retained_material(
                        flow,
                        RetainedMaterialDisposition.ORPHAN_REF,
                        credential_ref,
                    )
            self._fail_flow(flow, "models.oauth.binding_failed")
            return
        flow.credential_ref = credential_ref
        self._set_retained_material(
            flow,
            RetainedMaterialDisposition.FLOW_SOURCE_REF,
            credential_ref,
        )
        flow.state = "success"
        self._release_provider(flow)

    def _foreign_bound_identities(self, records: Sequence[_AuthRecord], source_id: str) -> set[str]:
        """Identities of auth records another Source's credential is bound to."""
        foreign: set[str] = set()
        for record in records:
            credential_ref = self.state_store.oauth_credential_ref(record.name)
            if credential_ref is None:
                continue
            owner = self.state_store.credential_metadata(credential_ref).get("source_id")
            if owner and owner != source_id:
                foreign.add(record.identity)
        return foreign

    async def _delete_auth_files(self, auth_name: str) -> bool:
        def remove(client: EngineClient | None) -> bool:
            try:
                if client is not None:
                    client.management_request("DELETE", "/auth-files", query={"name": auth_name})
                self.state_store.delete_oauth_auth_file(auth_name)
            except (EngineClientError, EngineStateError):
                return False
            return True

        # Atomic with the engine lifecycle, like ``_cleanup_oauth_material``.
        try:
            return await asyncio.to_thread(self.supervisor.with_engine_excluded, remove)
        except EngineUnavailableError:
            return False

    async def _cleanup_oauth_material(self, auth_name: str, credential_ref: str) -> bool:
        def remove_grant(client: EngineClient | None) -> bool:
            engine_delete_succeeded = True
            if client is not None:
                try:
                    client.management_request("DELETE", "/auth-files", query={"name": auth_name})
                except EngineClientError:
                    engine_delete_succeeded = False
            try:
                self.state_store.delete_oauth_auth_file(auth_name)
            except EngineStateError:
                return False
            return engine_delete_succeeded

        # Atomic with the engine lifecycle: see ``revoke_credential``.
        try:
            removed = await asyncio.to_thread(self.supervisor.with_engine_excluded, remove_grant)
        except EngineUnavailableError:
            return False
        if not removed:
            return False
        try:
            await asyncio.to_thread(
                self.state_store.revoke_credential,
                credential_ref,
            )
        except EngineStateError:
            return False
        return True

    def _get_flow(self, flow_id: str) -> _OAuthFlow:
        with self._oauth_lock:
            self._expire_oauth_flows_locked()
            flow = self._oauth_flows.get(flow_id)
        if flow is None:
            raise EngineStateError("OAuth flow is unknown")
        return flow

    def _fail_flow(self, flow: _OAuthFlow, error_key: str, *, detail: str | None = None) -> None:
        self._mark_retention_unknown_if_needed(flow)
        flow.state = "failed"
        flow.error_key = error_key
        flow.error_detail = oauth_failure_detail(detail)
        if flow.error_detail is not None:
            logger.warning(
                "OAuth flow failed: flow=%s provider=%s error_key=%s detail=%s",
                flow.flow_id,
                flow.callback_provider,
                error_key,
                flow.error_detail,
            )
        self._release_provider(flow)

    @staticmethod
    def _set_retained_material(
        flow: _OAuthFlow,
        disposition: RetainedMaterialDisposition,
        credential_ref: str | None = None,
    ) -> None:
        carries_ref = disposition in {
            RetainedMaterialDisposition.FLOW_SOURCE_REF,
            RetainedMaterialDisposition.ORPHAN_REF,
        }
        if carries_ref != (credential_ref is not None):
            raise AssertionError("retained material disposition/ref pairing is invalid")
        flow.retained_material_disposition = disposition
        flow.retained_credential_ref = credential_ref
        flow.retained_material_decided = True

    @classmethod
    def _mark_retention_unknown_if_needed(cls, flow: _OAuthFlow) -> None:
        if flow.grant_write_possible and not flow.retained_material_decided:
            cls._set_retained_material(flow, RetainedMaterialDisposition.UNKNOWN)

    def _release_provider(self, flow: _OAuthFlow) -> None:
        with self._oauth_lock:
            self._active_oauth_providers.discard(flow.auth_provider)

    def _expire_oauth_flow(self, flow: _OAuthFlow) -> None:
        with self._oauth_lock:
            self._expire_oauth_flow_locked(flow, datetime.now(timezone.utc))

    def _expire_oauth_flows_locked(self) -> None:
        now = datetime.now(timezone.utc)
        for flow in self._oauth_flows.values():
            if flow.operation_lock.locked():
                continue
            self._expire_oauth_flow_locked(flow, now)

    def _expire_oauth_flow_locked(self, flow: _OAuthFlow, now: datetime) -> None:
        if flow.state in {"success", "failed", "cancelled"}:
            return
        try:
            expires_at = datetime.fromisoformat(flow.expires_at_iso)
        except ValueError:
            expires_at = now
        if expires_at.tzinfo is None:
            expires_at = expires_at.replace(tzinfo=timezone.utc)
        if expires_at <= now:
            self._mark_retention_unknown_if_needed(flow)
            flow.state = "failed"
            flow.error_key = "models.oauth.expired"
            self._active_oauth_providers.discard(flow.auth_provider)


# A browser that cannot load the loopback callback page often copies its address
# without the scheme (``localhost:1455/auth/callback?code=…``). That value is an
# address, not a code: sent as a code, the provider refuses it and the refusal
# ends the session. A host followed by a port, path or query marks an address; a
# provider code carries none of them (Google's ``4/0A…`` has no host before its
# slash, and Anthropic's ``code#state`` has no path or query).
_SCHEMELESS_CALLBACK_ADDRESS = re.compile(
    r"^(?:"
    # A loopback or IP host is an address on its own, with or without a port.
    r"(?:localhost|\[[0-9a-f:.]+\]|\d{1,3}(?:\.\d{1,3}){3})(?::\d{1,5})?(?:[/?]|$)"
    # A named host needs a port, path or query: ``a.b.c`` alone may be a code.
    r"|(?:[a-z0-9-]+\.)+[a-z]{2,}(?::\d{1,5}(?:[/?]|$)|[/?])"
    r")",
    re.IGNORECASE,
)


def _oauth_callback_address(submitted: str) -> str | None:
    """Return a pasted OAuth value as a callback address, or None for a bare code."""

    if submitted.lower().startswith(("http://", "https://")):
        return submitted
    if "?" in submitted or _SCHEMELESS_CALLBACK_ADDRESS.match(submitted):
        return "http://" + submitted.lstrip("/")
    return None


# The pinned engine's OAuth session errors, verbatim and lower-cased, mapped to
# what the user can do about each. A closed table: anything the engine says that
# is not here, including a future rewording, keeps the generic key rather than
# borrowing a cause it did not state.
_OAUTH_ENGINE_SESSION_ERRORS = {
    "timeout waiting for oauth callback": "models.oauth.expired",
    "oauth flow timed out": "models.oauth.expired",
    "state code error": "models.oauth.callback_mismatch",
    "authentication failed: state mismatch": "models.oauth.callback_mismatch",
    "bad request": "models.oauth.provider_denied",
    "authentication failed": "models.oauth.provider_denied",
    "failed to exchange token": "models.oauth.exchange_failed",
}
# The one session error that carries its cause after the phrase.
_OAUTH_ENGINE_EXCHANGE_FAILURE = "failed to exchange authorization code for tokens"


def _oauth_engine_failure_key(reason: str) -> str:
    """Map the engine's session error to what the user can do about it."""

    text = " ".join(reason.split()).lower()
    if text == _OAUTH_ENGINE_EXCHANGE_FAILURE or text.startswith(_OAUTH_ENGINE_EXCHANGE_FAILURE + ":"):
        # Only the provider's answers about the grant itself blame the pasted
        # code; a proxy (407), a throttle (429) or any other refusal does not.
        if re.search(r"\bstatus 40[01]\b", text) or "invalid_grant" in text:
            return "models.oauth.code_rejected"
        return "models.oauth.exchange_failed"
    return _OAUTH_ENGINE_SESSION_ERRORS.get(text, "models.oauth.upstream_failed")


def _auth_inventory(client: EngineClient) -> dict[str, _AuthRecord]:
    payload = client.management_request("GET", "/auth-files")
    files = payload.get("files")
    if not isinstance(files, list):
        raise EngineClientError("engine auth inventory is invalid", error_type="invalid_json")
    inventory: dict[str, _AuthRecord] = {}
    for item in files:
        if not isinstance(item, dict):
            continue
        auth_index = str(item.get("auth_index") or "").strip()
        identity = str(item.get("id") or auth_index or item.get("name") or "").strip()
        name = str(item.get("name") or item.get("id") or "").strip()
        provider = str(item.get("provider") or item.get("type") or "").strip().lower()
        id_token = item.get("id_token")
        account_id = (
            str(id_token.get("chatgpt_account_id") or "").strip() or None if isinstance(id_token, dict) else None
        )
        if identity and name and provider:
            fingerprint = json.dumps(
                {
                    key: item.get(key)
                    for key in (
                        "modtime",
                        "updated_at",
                        "last_refresh",
                        "status",
                        "status_message",
                        "size",
                        "disabled",
                        "unavailable",
                    )
                },
                sort_keys=True,
                separators=(",", ":"),
            )
            inventory[identity] = _AuthRecord(
                identity=identity,
                auth_index=auth_index,
                name=name,
                provider=provider,
                fingerprint=fingerprint,
                account_id=account_id,
                status=str(item.get("status") or "").strip().lower(),
                status_message=str(item.get("status_message") or "").strip(),
                unavailable=bool(item.get("unavailable")),
            )
    return inventory


def _discovered_models(
    payload: Mapping[str, Any],
    prefix: str | None = None,
) -> tuple[DiscoveredModel, ...]:
    models = payload.get("models")
    if not isinstance(models, list):
        return ()
    coalesced: dict[str, tuple[str, ...] | None] = {}
    # Which spellings the engine used for each name, so a row it listed twice
    # under one name stays distinguishable from two rows that became one here.
    spellings: dict[str, set[str]] = {}
    for item in models:
        value = item.get("id") or item.get("alias") or item.get("name") if isinstance(item, dict) else item
        if not isinstance(value, str) or not value:
            continue
        answered = value
        # This is the one place an address enters the product: the engine answers
        # with the name it addresses this credential by. It is removed here, at
        # that boundary, rather than by every later reader of the inventory — and
        # only the address of the credential being discovered, so a model whose
        # own name is spelled like one is left as upstream named it.
        value = model_id_without_credential_address(value, prefix)
        if not value:
            continue
        supported_parameters = None
        if isinstance(item, dict) and isinstance(item.get("supported_parameters"), list):
            parameters = item["supported_parameters"]
            if all(isinstance(parameter, str) and parameter for parameter in parameters):
                supported_parameters = tuple(dict.fromkeys(parameters))
        if value not in coalesced:
            coalesced[value] = supported_parameters
            spellings[value] = {answered}
            continue
        if answered in spellings[value]:
            # The engine listed one name twice and said different things about
            # it. That is the engine contradicting itself and the first answer
            # has always been the one kept.
            continue
        # Two names the engine kept apart, landing on one only because the
        # address came off. The inventory holds one row per name, so the rows
        # are coalesced rather than the later one dropped: this merge is ours,
        # and nothing the engine said may be lost to the order it said it in.
        spellings[value].add(answered)
        held = coalesced[value]
        if supported_parameters is None:
            continue
        if held is None:
            coalesced[value] = supported_parameters
            continue
        coalesced[value] = tuple(dict.fromkeys(held + supported_parameters))
    return tuple(
        DiscoveredModel(id=model_id, supported_parameters=parameters) for model_id, parameters in coalesced.items()
    )


_adapter: CLIProxyEngineAdapter | None = None


def get_model_hub_engine_adapter() -> CLIProxyEngineAdapter:
    global _adapter
    if _adapter is None:
        _adapter = CLIProxyEngineAdapter()
    return _adapter


def set_model_hub_engine_adapter_for_tests(adapter: CLIProxyEngineAdapter | None) -> None:
    global _adapter
    _adapter = adapter