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.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
"""Model Hub EngineAdapter interface. FINAL CONTRACT v23 (2026-10-30).
This file is the canonical adapter boundary and must remain byte-identical to
``core/handlers/model_hub/adapter.py``. The adapter owns one-Source operations:
credential custody, protocol observation, model discovery, OAuth, invocation,
and cleanup. Model protocol operations use ``MODEL_PROTOCOLS`` (the four invocable
wire protocols); ``SOURCE_PROTOCOLS`` adds the tool-only ``search`` value only for
stored/created Source shapes. It never chooses or reorders Route hops, classifies
cross-Source
fallthrough, or exposes credential material. Contract changes route through the
orchestrator and land with every affected consumer on the same tested head.
"""
from __future__ import annotations
import asyncio
from dataclasses import dataclass, field
from datetime import datetime
from enum import Enum
import re
from typing import Any, AsyncIterator, Awaitable, Callable, Final, Literal, Mapping, Protocol, Sequence
from .stream_wire import ProtocolSSEState, ProtocolUsageReport, ServedTier
ENGINE_TRANSPORT_TIMEOUT_SECONDS: Final = 60.0
# Model invocation/observation is a narrower domain than stored Sources.
MODEL_PROTOCOLS = ("anthropic", "openai_responses", "openai_chat", "google")
# Source persistence/admission adds the tool-only search protocol.
SOURCE_PROTOCOLS = MODEL_PROTOCOLS + ("search",)
SEARCH_RESPONSE_MAX_BYTES: Final = 8 * 1024 * 1024
SEARCH_TRANSPORT_TIMEOUT_SECONDS: Final = 30.0
# Response correlation is a diagnostic fact, not a header-forwarding surface. These
# are the only upstream response header names allowed to cross the engine boundary.
RESPONSE_CORRELATION_HEADER_NAMES: Final = frozenset({"request-id", "x-request-id"})
# Claude's future subscription-cap classifier consumes this closed set. Keep the
# names lowercase here; the engine/client boundary matches them case-insensitively.
CLAUDE_UNIFIED_RATE_LIMIT_HEADER_NAMES: Final = frozenset({
"anthropic-ratelimit-unified-status",
"anthropic-ratelimit-unified-5h-status",
"anthropic-ratelimit-unified-7d-status",
"anthropic-ratelimit-unified-7d_oi-status",
"anthropic-ratelimit-unified-overage-status",
"anthropic-ratelimit-unified-overage-disabled-reason",
"anthropic-ratelimit-unified-representative-claim",
"anthropic-ratelimit-unified-5h-utilization",
"anthropic-ratelimit-unified-7d-utilization",
"anthropic-ratelimit-unified-5h-reset",
"anthropic-ratelimit-unified-7d-reset",
"anthropic-ratelimit-unified-7d_oi-reset",
"anthropic-ratelimit-unified-reset",
"anthropic-ratelimit-unified-overage-reset",
})
RESPONSE_CORRELATION_ID_MAX_LENGTH: Final = 256
RESPONSE_CORRELATION_ID_MAX_ITEMS: Final = len(RESPONSE_CORRELATION_HEADER_NAMES)
_CORRELATION_ID_CREDENTIAL_PATTERN = re.compile(
r"(?i)(?:bearer|basic)\s+|"
r"(?:authorization|api[_ -]?key|access[_ -]?token|token|secret|password|"
r"credential|cookie|session|signature)\s*[:=]|"
r"(?:sk|rk|pk|sess|token|secret|cred|key)[-_][a-z0-9_-]{8,}|"
r"(?:AIza[a-z0-9_-]{20,}|github_pat_[a-z0-9_]{20,}|gh[pousr]_[a-z0-9_]{20,})|"
r"ey[a-z0-9_-]+\.[a-z0-9_-]+\.[a-z0-9_-]+$"
)
def sanitize_response_correlation_ids(values: object) -> tuple[tuple[str, str], ...]:
"""Keep only bounded, credential-free values from the two trusted headers."""
pairs = values.items() if isinstance(values, Mapping) else values
try:
iterator = iter(pairs) # type: ignore[arg-type]
except TypeError:
return ()
retained: list[tuple[str, str]] = []
seen: set[str] = set()
for pair in iterator:
if not isinstance(pair, (tuple, list)) or len(pair) != 2:
continue
raw_name, raw_value = pair
if not isinstance(raw_name, str) or not isinstance(raw_value, str):
continue
name = raw_name.lower()
if name not in RESPONSE_CORRELATION_HEADER_NAMES or name in seen:
continue
if (
not raw_value
or len(raw_value) > RESPONSE_CORRELATION_ID_MAX_LENGTH
or any(not 0x21 <= ord(char) <= 0x7E for char in raw_value)
or _CORRELATION_ID_CREDENTIAL_PATTERN.search(raw_value)
):
continue
seen.add(name)
retained.append((name, raw_value))
if len(retained) >= RESPONSE_CORRELATION_ID_MAX_ITEMS:
break
order = {name: index for index, name in enumerate(sorted(RESPONSE_CORRELATION_HEADER_NAMES))}
return tuple(sorted(retained, key=lambda item: order[item[0]]))
OBSERVATION_OUTCOMES = (
"observed",
"ambiguous",
"unreachable",
"authentication_failed",
"adapter_error",
"timeout",
)
OBSERVATION_DISCOVERY_OUTCOMES = ("succeeded", "failed", "not_attempted")
class EngineHealth(str, Enum):
OK = "ok"
DEGRADED = "degraded"
DOWN = "down"
NOT_STARTED = "not_started"
NOT_INSTALLED = "not_installed"
INSTALLING = "installing"
@dataclass(frozen=True)
class EngineStatus:
health: EngineHealth
installed_version: str | None
verified: bool
listen_host: str # always "127.0.0.1"
listen_port: int | None
last_check_iso: str | None
host_platform: str | None = None
error_key: str | None = None
@dataclass(frozen=True)
class EngineEnsureResult:
status: EngineStatus
changed: bool
class RuntimePlatformUnsupportedError(RuntimeError):
"""The pinned managed runtime has no asset for the server host."""
class OAuthCredentialRejectedError(RuntimeError):
"""Authoritative rejection of a refresh grant, requiring new authorization.
An expired access token, generic 401, or profile-only permission failure
does not establish this outcome. Exceptions must carry no secret material.
"""
@dataclass(frozen=True)
class SearchResponse:
"""Bounded response from one catalog search endpoint.
The body is opaque to this boundary. It contains no credential material;
the adapter reads the key from custody only while making the request.
"""
http_status: int | None
headers: Mapping[str, str]
body: bytes | None
error: Literal["", "timeout", "connection", "redirect", "body_too_large", "invalid_endpoint", "cancelled"] = ""
on_sent_fired: bool = False
response_received_at: datetime | None = None
@dataclass(frozen=True)
class SearchCredentialCheck:
outcome: Literal["pass", "balance", "limit", "invalid", "unknown"]
@dataclass(frozen=True)
class SourceBinding:
"""Engine-side registration of one hub-channel source (projection of config)."""
source_id: str
vendor: str
protocol: str # "anthropic" | "openai_responses" | "openai_chat" | "google" | "search"
base_url: str | None # None => vendor official default
credential_ref: str # opaque handle; never secret material
allowed_origins: tuple[str, ...] # agent names allowed to draw on this
# source. Empty tuple = unrestricted (api_key default). Subscription
# sources MUST be non-empty (README invariant 3); L2 populates, L1
# enforces as backstop.
model_ids: tuple[str, ...] # truthful inventory evidence (discovered + manual).
# May be empty; API-key invocation need not be listed. Bare ids, no prefix.
model_reasoning_efforts: tuple[tuple[str, tuple[str, ...]], ...] = ()
# Per-model levels declared by the Source. CLIProxyAPI needs these on its
# model registration or it removes an otherwise valid reasoning effort.
route_model_ids: tuple[str, ...] = ()
# Sorted API-key transport targets derived from effective routes, never
# inventory or capability evidence. Independent of live health and mode.
text_only_model_ids: tuple[str, ...] = ()
# Models among model_ids and route_model_ids that this Source's upstream
# declares text-only in its own models.dev entry. CLIProxyAPI replaces
# tool-result images for such an openai-compatibility model instead of
# forwarding them; every other model keeps them.
class OriginNotAllowedError(Exception):
"""Raised by the adapter when ``invoke(origin=...)`` violates the source's
``allowed_origins``. A programming/policy error — never converted into a
``RawCallOutcome`` and never triggers fallback."""
class OAuthSubmissionRejectedError(Exception):
"""Raised by ``submit_oauth`` when the provider refuses the pasted value
before touching the flow. Nothing was written and the flow still awaits a
submission, so the user can paste again on the same flow.
``reason`` names what to paste instead: ``no_answer`` is an address that
carries no provider answer; ``other_attempt`` answers a different sign-in
link than this flow's, whose code this flow can never exchange."""
def __init__(
self,
flow_id: str,
reason: Literal["no_answer", "other_attempt"] = "no_answer",
) -> None:
super().__init__(flow_id)
self.reason = reason
class InvokeCancelledError(asyncio.CancelledError):
"""Owner cancellation carrying wire facts observed before transport cleanup."""
def __init__(self, observed: ProtocolSSEState) -> None:
super().__init__()
self.observed = observed
class RawOutcomeKind(str, Enum):
SUCCESS = "success"
HTTP_ERROR = "http_error"
NETWORK_ERROR = "network_error"
TIMEOUT = "timeout"
PROTOCOL_ERROR = "protocol_error" # malformed/unparseable upstream response
@dataclass(frozen=True)
class UpstreamRejection:
"""Closed facts of an HTTP 400 the upstream returned before any output.
The only input of the capability-evidence rules (``model-hub-capability-model.md``
§3.2). L1 fills it from the error envelope: raw machine tokens, and the one
token each recognized message names. It never carries prose, and the
failover decision never reads it.
"""
status: int
code: str | None = None # raw machine code, e.g. "invalid_value"
error_type: str | None = None # raw error type, e.g. "invalid_request_error"
param: str | None = None # raw parameter path, e.g. "reasoning.effort"
invalid_value: str | None = None # "Invalid value: '<value>'"
unsupported_tool_type: str | None = None # "Unsupported tool type: <type>"
invalid_encrypted_content_block: str | None = None # "Invalid encrypted_content in <kind> block"
@dataclass(frozen=True)
class RawCallOutcome:
"""Uninterpreted per-call result. Classification is L2's job, not L1's."""
kind: RawOutcomeKind
http_status: int | None
error_code: str | None # upstream machine code if parseable, else None
# L1's own account of how the call ended, never upstream text; classification
# does not read it. L1 guarantees no credential material.
redacted_message: str | None
stream_started: bool
model_id: str
source_id: str
error_type: str | None = None # raw upstream error type, if present
error_candidates: tuple[str, ...] = () # unsorted raw type/code candidates
# Tokens the upstream reported for this call, when the response carried a
# readable report. A call that settles before it can hand its body onward
# would otherwise take its token report with it, and a vendor that reported
# tokens billed for them whether or not the call ended well.
usage: ProtocolUsageReport | None = None
# Only failed HTTP responses supply retry advice: ASCII, at most 128
# characters, unparsed. The Retry-After header, else a usage cap's own reset
# from the error envelope in that header's syntax. L2 owns validation and
# the resulting retry policy.
retry_after: str | None = None
# Validated Retry-After-Ms advice. It stays separate from ``retry_after`` so
# a millisecond count can never reach code that interprets numeric advice as
# whole seconds.
retry_after_ms: int | None = field(default=None, repr=False)
# Aware UTC receipt time of those headers, before reading the error body.
response_received_at: datetime | None = None
# Exact, bounded Claude unified rate-limit facts for the future #2530
# classifier. These never reach an outward response or persisted event.
claude_rate_limit_headers: tuple[tuple[str, str], ...] = field(default=(), repr=False)
# Recognized model output or protocol success, independently of permissive
# forwarding. An unrecognized HTTP 200 alone cannot prove Source recovery.
recovery_verified: bool = False
# Upstream's own human-readable error text, credential-redacted and bounded
# by L1. Display-only: classification never reads it, it is never persisted
# into events or provenance, and it stays out of repr so logs cannot echo it.
upstream_detail: str | None = field(default=None, repr=False)
# Recognized local OS failure only, never an upstream code or error prose.
# Display-only; does not participate in classification or Source health.
os_errno: int | None = None
# A 400 before output, as closed tokens for the capability-evidence rules.
rejection: UpstreamRejection | None = None
# The search tools whose own completed item a served response carried, for
# the positive evidence written at settlement (``vibey-hosted-tools.md`` §3.2).
hosted_tools: frozenset[str] = frozenset()
# The processing tier a served response reports (``docs/plans/fast-mode.md``),
# for confirming that a fast request ran fast; None when it names none.
served_tier: ServedTier | None = None
# The response header name is retained in lowercase so relay ``x-request-id``
# and provider ``request-id`` values cannot be conflated. The client and
# provenance writer re-validate this tuple before persistence.
response_correlation_ids: tuple[tuple[str, str], ...] = ()
class ObservationOutcome(str, Enum):
OBSERVED = OBSERVATION_OUTCOMES[0]
AMBIGUOUS = OBSERVATION_OUTCOMES[1]
UNREACHABLE = OBSERVATION_OUTCOMES[2]
AUTHENTICATION_FAILED = OBSERVATION_OUTCOMES[3]
ADAPTER_ERROR = OBSERVATION_OUTCOMES[4]
TIMEOUT = OBSERVATION_OUTCOMES[5]
class ObservationDiscovery(str, Enum):
SUCCEEDED = OBSERVATION_DISCOVERY_OUTCOMES[0]
FAILED = OBSERVATION_DISCOVERY_OUTCOMES[1]
NOT_ATTEMPTED = OBSERVATION_DISCOVERY_OUTCOMES[2]
@dataclass(frozen=True)
class DiscoveredModel:
"""One model inventory row and the only upstream metadata v1 retains."""
id: str
supported_parameters: tuple[str, ...] | None = None
@dataclass(frozen=True)
class SourceObservation:
"""Response-backed result of an unsaved Source observation."""
outcome: ObservationOutcome
reachable: bool | None
authenticated: bool | None
protocol: str | None
discovery: ObservationDiscovery
models: tuple[DiscoveredModel, ...]
@property
def model_ids(self) -> tuple[str, ...]:
return tuple(model.id for model in self.models)
@dataclass(frozen=True)
class ObservationTerminalRule:
"""Complete legal product for one response-backed observation outcome."""
reachable: frozenset[bool | None]
authenticated: frozenset[bool | None]
protocols: frozenset[str | None]
discoveries: frozenset[ObservationDiscovery]
models_must_be_empty: bool
OBSERVATION_TERMINAL_RULES: Mapping[
ObservationOutcome,
ObservationTerminalRule,
] = {
ObservationOutcome.OBSERVED: ObservationTerminalRule(
reachable=frozenset({True}),
authenticated=frozenset({True}),
protocols=frozenset(MODEL_PROTOCOLS),
discoveries=frozenset(
{
ObservationDiscovery.SUCCEEDED,
ObservationDiscovery.FAILED,
}
),
models_must_be_empty=False,
),
ObservationOutcome.AMBIGUOUS: ObservationTerminalRule(
reachable=frozenset({True}),
authenticated=frozenset({True, None}),
protocols=frozenset({None}),
discoveries=frozenset({ObservationDiscovery.NOT_ATTEMPTED}),
models_must_be_empty=True,
),
ObservationOutcome.UNREACHABLE: ObservationTerminalRule(
reachable=frozenset({False}),
authenticated=frozenset({None}),
protocols=frozenset({None}),
discoveries=frozenset({ObservationDiscovery.NOT_ATTEMPTED}),
models_must_be_empty=True,
),
ObservationOutcome.AUTHENTICATION_FAILED: ObservationTerminalRule(
reachable=frozenset({True}),
authenticated=frozenset({False}),
protocols=frozenset({None}),
discoveries=frozenset({ObservationDiscovery.NOT_ATTEMPTED}),
models_must_be_empty=True,
),
ObservationOutcome.ADAPTER_ERROR: ObservationTerminalRule(
reachable=frozenset({True, None}),
authenticated=frozenset({None}),
protocols=frozenset({None}),
discoveries=frozenset({ObservationDiscovery.NOT_ATTEMPTED}),
models_must_be_empty=True,
),
ObservationOutcome.TIMEOUT: ObservationTerminalRule(
reachable=frozenset({None}),
authenticated=frozenset({None}),
protocols=frozenset({None}),
discoveries=frozenset({ObservationDiscovery.NOT_ATTEMPTED}),
models_must_be_empty=True,
),
}
def validate_source_observation(observation: object) -> SourceObservation:
"""Validate an adapter result against the sole terminal-product authority."""
if not isinstance(observation, SourceObservation):
raise TypeError("invalid SourceObservation")
if not isinstance(observation.outcome, ObservationOutcome):
raise ValueError("invalid SourceObservation outcome")
if not isinstance(observation.discovery, ObservationDiscovery):
raise ValueError("invalid SourceObservation discovery")
if observation.reachable is not None and not isinstance(observation.reachable, bool):
raise ValueError("invalid SourceObservation reachability")
if observation.authenticated is not None and not isinstance(
observation.authenticated,
bool,
):
raise ValueError("invalid SourceObservation authentication")
if not isinstance(observation.models, tuple) or any(
not isinstance(model, DiscoveredModel)
or not isinstance(model.id, str)
or not model.id
or (
model.supported_parameters is not None
and (
not isinstance(model.supported_parameters, tuple)
or any(
not isinstance(parameter, str) or not parameter
for parameter in model.supported_parameters
)
or len(set(model.supported_parameters))
!= len(model.supported_parameters)
)
)
for model in observation.models
):
raise ValueError("invalid SourceObservation inventory")
if len(set(observation.model_ids)) != len(observation.model_ids):
raise ValueError("invalid SourceObservation inventory")
rule = OBSERVATION_TERMINAL_RULES[observation.outcome]
if (
observation.reachable not in rule.reachable
or observation.authenticated not in rule.authenticated
or observation.protocol not in rule.protocols
or observation.discovery not in rule.discoveries
or (rule.models_must_be_empty and observation.model_ids)
or (observation.discovery is ObservationDiscovery.FAILED and observation.model_ids)
):
raise ValueError("invalid SourceObservation terminal product")
return observation
def make_source_observation(
*,
outcome: ObservationOutcome,
reachable: bool | None,
authenticated: bool | None,
protocol: str | None,
discovery: ObservationDiscovery,
models: Sequence[DiscoveredModel],
) -> SourceObservation:
"""Construct an adapter result through the terminal-product authority."""
return validate_source_observation(
SourceObservation(
outcome=outcome,
reachable=reachable,
authenticated=authenticated,
protocol=protocol,
discovery=discovery,
models=tuple(models),
)
)
class RetainedMaterialDisposition(str, Enum):
NONE = "none"
FLOW_SOURCE_REF = "flow_source_ref"
ORPHAN_REF = "orphan_ref"
FOREIGN_SOURCE_REF = "foreign_source_ref"
UNKNOWN = "unknown"
@dataclass(frozen=True)
class OAuthFlowState:
"""Channel-aware subscription OAuth flow state.
Deterministic binding: the flow is created FOR a pre-existing pending
``source_id``. On the Hub branch, ``credential_ref`` is non-null exactly
on success and names the engine auth record L2 binds to that source. On the
native CLI branch it is null at every state, including success, because the
sanctioned CLI owns its login material. This split mirrors shipped truth in
``core/handlers/model_hub/native_oauth.py:252-289`` and
``tests/test_model_hub_api.py:1147-1149``.
``retained_material_disposition`` is total across every state. For Hub
terminal states it reports where grant material written by THIS flow
remains: ``none`` means cleanup was confirmed or nothing was written;
``flow_source_ref`` names the flow source's ref; ``orphan_ref`` retains a
minted cleanup handle; ``foreign_source_ref`` means the single existing ref
belongs to another source; and ``unknown`` is the corrupt/ambiguous-state
floor, never a default. ``retained_credential_ref`` is non-null exactly for
``flow_source_ref`` and ``orphan_ref``. Foreign and unknown placements
deliberately withhold a ref so consumers cannot act on another source or
guess among candidates. Hub success pins ``flow_source_ref`` and equality
of both refs. Native pins ``none`` and a null retained ref by construction.
Mirrors ``oauth-flow.schema.json`` presentation semantics
(runtime-declared; UI renders from ``expects``).
"""
flow_id: str
source_id: str
vendor: str
state: str # "starting" | "awaiting_action" | "verifying" | "success" | "failed" | "cancelled"
auth_url: str | None
device_code: str | None
expects: str # "none" | "paste_code" | "paste_callback_url"
instructions_key: str | None
error_key: str | None
expires_at_iso: str | None
credential_ref: str | None
# Channel-aware producers set all three fields explicitly. Defaults keep the
# dataclass construction total for presentation-only adapter implementations.
channel: Literal["hub", "native_cli"] = "hub"
retained_material_disposition: RetainedMaterialDisposition = RetainedMaterialDisposition.NONE
retained_credential_ref: str | None = None
# What the provider, engine, or native CLI said when the flow failed,
# verbatim on one bounded line, for display beside ``error_key``. Null in
# every other state and whenever there is nothing to add to the key.
error_detail: str | None = None
# Native authorization/config commit succeeded, but this attempt's runtime
# application failed. This does not undo Source materialization or assert
# the runtime's current health.
application_failed: bool = False
class InvokeHandle(Protocol):
"""One in-flight upstream call.
``stream`` is None when a streaming failure settles before its first model
output (the outcome is then immediately awaitable). When ``stream`` is not
None, the settlement owner closes it before reading the outcome. A
never-started stream may have no outcome after closing;
``outcome_available`` is the non-blocking guard.
For streaming calls, ``stream_started`` becomes true only when the
protocol taxonomy observes the first model output; transport metadata and
error frames remain pre-output. ``close_stream()`` is idempotent.
``observed`` carries what the adapter itself read of this body, and it is
the handle's only member that answers before the body is consumed. A
streaming adapter has already read the head of the stream to decide there
was one — Anthropic reports the input tokens it billed in that head — and it
keeps reading as the body is yielded, so its tracker is never behind a
consumer's. Without it the facts of a call would exist only in bytes the
consumer has already pulled, and everything that can end a turn before the
first pull would see a call that never happened. It is None only when the
adapter tokenized no stream for this call.
"""
@property
def stream(self) -> AsyncIterator[bytes] | None: ...
@property
def observed(self) -> ProtocolSSEState | None: ...
@property
def outcome_available(self) -> bool: ...
async def close_stream(self) -> None: ...
async def outcome(self) -> RawCallOutcome: ...
class EngineAdapter(Protocol):
# --- lifecycle -------------------------------------------------------
async def install(self) -> EngineStatus: ...
async def recover_installation(self) -> EngineStatus: ...
async def ensure_installed(
self,
*,
force: bool = False,
offline: bool = False,
) -> EngineEnsureResult: ...
async def start(self) -> EngineStatus: ...
async def stop_runtime(self) -> EngineStatus: ...
async def stop(self) -> None: ...
async def status(self) -> EngineStatus: ...
# --- gateway ---------------------------------------------------------
async def gateway_token(self) -> str:
"""Local gateway token for Hub-channel backend injection.
This is the only credential the managed engine injects. Native-channel
turns bypass this gateway and use the sanctioned CLI's own login.
"""
...
# --- credential provisioning (engine-owned store) ---------------------
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:
"""Store an API-key secret in the Model Hub credential store. Search
Sources use this same opaque-ref custody, but are never rendered into
engine configuration or sent through the engine.
``secret`` is transient: the adapter must never log it; L2 must never
persist it (config stores refs only). When supplied, ``on_reserved`` is
called synchronously with the opaque ref after an atomic no-secret
reservation and before any secret bytes are written. A callback failure
forbids the write. Hub OAuth credentials never pass through here —
they are created engine-side by the OAuth flow and surfaced via
``OAuthFlowState.credential_ref``. ``auth_scheme`` optionally preserves
an explicit static transport; omission retains legacy semantics."""
...
async def check_search_credential(
self,
credential_ref: str,
catalog: Mapping[str, Any],
) -> SearchCredentialCheck:
"""Run one catalog free check without exposing its key or response."""
...
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:
"""Make exactly one catalog-host search request from Model Hub custody.
``credential_ref`` is an opaque custody handle for credentialed Sources;
it is ``None`` for the built-in keyless MCP Source. In both cases the
adapter owns the transport and never exposes secret material.
``on_sent`` fires once after the connection (including TLS) is ready and
immediately before aiohttp writes this request. A callback failure stops
the request before any request bytes are sent. An async callback is
awaited for final controller admission without holding a mutation lock
during DNS/TCP/TLS; existing synchronous callbacks remain supported.
"""
...
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:
"""Make exactly one catalog web-fetch request from Model Hub custody."""
...
async def revoke_search_credential(self, credential_ref: str) -> None:
"""Remove a search-only credential from Model Hub custody."""
...
async def provision_oauth_credential(
self,
source_id: str,
vendor: str,
material: Mapping[str, object],
*,
on_reserved: Callable[[str], None] | None = None,
) -> str:
"""Stage a native OAuth grant outside CPA's watched auth directory.
``material`` is transient and must never cross the L2 config boundary.
Return a durable opaque ref, with the provider, source, and prefix
already bound. When supplied, ``on_reserved`` is called synchronously
with the opaque ref after an atomic no-secret reservation and before
any grant bytes are written. A callback failure forbids the write.
Neither provisioning nor a restart may expose the staged grant to CPA.
Only ``activate_oauth_credential`` transfers refresh ownership, after
the caller has durably withdrawn native ownership.
"""
...
async def activate_oauth_credential(self, credential_ref: str) -> None:
"""Publish a staged grant without ever overwriting a rotated live grant.
Idempotent and cancellation-safe. The caller must persist an activation
intent first and must not restore old native tokens after this call may
have started. Preserve the only recovery handle on any failure.
"""
...
async def validate_oauth_credential(self, credential_ref: str) -> None:
"""Require credential-specific upstream acceptance, not auth inventory.
Used for imported grants, whose origin is not a completed engine OAuth
flow. Does not generate inference. Raise a sanitized error on denied or
inconclusive authentication; never equate an auth-file upload or the
engine's serving-protocol pin with upstream acceptance.
"""
...
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:
"""Compare transient native material inside custody; return no secrets."""
...
async def credential_auth_scheme(self, credential_ref: str) -> str | None:
"""Resolve immutable static transport without requiring the old secret.
A safe missing/content-corrupt private document may recover from its
ref. Readable wrong-kind/unknown/conflicting metadata, unsafe paths and
I/O errors reject. The replacement still needs normal key validation.
"""
...
async def credential_address(self, credential_ref: str) -> str | None:
"""Report the address outbound calls reach this credential through.
The engine addresses a credential through the model field and no other,
so a call spells ``<address>/<model>``. Custody mints that address and
is the only place it is recorded, which makes this the one answer that
can *prove* an id an older release stored carries one — as opposed to
guessing from its shape and renaming a vendor's own model.
Whichever address the engine would actually compose, however custody
happens to hold it: one credential records its own, another is
addressed by the record its Source is bound through. An implementation
that answers from only one of those reports no address for a Source the
engine addresses perfectly well.
None when nothing records an address for this credential, including
when it is gone. A caller that cannot prove ownership must leave the
id alone.
"""
...
def subscription_account_label(self, source_id: str, vendor: str, credential_ref: str) -> str | None:
"""Read optional public account metadata from this source's bound grant.
This local presentation read never starts the engine, refreshes a grant,
or exports credential material. Missing/unsafe metadata returns None.
"""
...
async def subscription_quota(self, source_id: str, vendor: str, credential_ref: str) -> dict[str, Any]:
"""Read this subscription's rate-limit windows from the vendor's usage report.
The engine makes the model-free account call with the bound grant; only
the parsed ``{plan, windows}`` crosses this boundary, never the grant or
the raw body. ``plan`` is the plan this read named, one without a built-in
fee included, or None when it could not name one; only None keeps the
last known plan. Raise ``SubscriptionQuotaError`` with a sanitized reason
(``auth_expired``, ``rate_limited``, ``unsupported``, ``unavailable`` or
``malformed``) on every failure. A report only: never feeds resolution.
"""
...
async def retarget_api_key_credential(
self,
credential_ref: str,
vendor: str,
protocol: str,
base_url: str | None,
) -> str:
"""Copy an API-key credential to a fresh ref with a new target.
The old ref remains valid until L2 commits the Source mutation and
explicitly revokes it. The secret never crosses this adapter boundary,
so Base URL replacement can be staged and rolled back transactionally.
"""
...
async def credential_supports_refresh(self, credential_ref: str) -> bool:
"""Return the credential's actual engine-side refresh capability.
This is a property of the stored credential, not an inference from
vendor, Source kind, or an HTTP status.
"""
...
async def revoke_credential(self, credential_ref: str) -> None:
"""Release a stored credential, preserving OAuth auth-file ordering."""
...
async def revoke_api_key_credential(self, credential_ref: str) -> None:
"""Retire an unbound ref under durable API-key-only caller intent.
Remove only the exact safe private ref namespace, even if the old
document is missing/content-corrupt. Reject readable identity conflicts
and unsafe paths. Never delete watched OAuth auth files or call OAuth
management APIs. Return only after durable cleanup; failure is retryable.
"""
...
async def revoke_search_credential(self, credential_ref: str) -> None:
"""Retire an unbound tool-only key under durable search-only intent.
Preserve API-key namespace and identity checks, but never access the
model engine or its configs, even when the document is already absent
or corrupt. The caller journals this operation before unlinking so
replay does not infer a lost protocol from credential metadata.
"""
...
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:
"""Provision an unbound credential for an unsaved observation.
The optional callback has the same write-ahead semantics as the
permanent and OAuth provisioners. Callers that own transient cleanup
may journal the ref before the observation secret reaches disk.
"""
...
async def cleanup_orphaned_oauth_material(self, credential_ref: str) -> bool:
"""Retry cleanup for an ``orphan_ref`` without exposing a filename.
Return true only after the running-engine auth-file delete (when an
engine is running), the local auth-file delete, and ref revocation are
all confirmed, or when ``credential_ref`` no longer resolves. Absence
is convergence, not a lenient fallback: this operation's ordering
invariant revokes the ref only after both auth-file deletions are
confirmed, so an absent ref proves that no material remains behind it.
A never-created ref satisfies the same postcondition vacuously. Return
false on any partial failure and retain the ref for a later retry. The
handle must never be destroyed while material may remain behind it.
"""
...
# --- source registry (L2 calls on every config change) ---------------
async def sync_sources(self, bindings: Sequence[SourceBinding]) -> None: ...
async def discover_models(
self,
vendor: str,
protocol: str,
base_url: str | None,
credential_ref: str,
*,
start_engine: bool = True,
) -> Sequence[DiscoveredModel]:
"""Refresh supplyable models for a saved Source using its stored protocol.
With ``start_engine=False`` an engine-held credential is listed only
from an engine that is already running; it is never started for this.
"""
...
async def observe_source(
self,
vendor: str,
base_url: str | None,
credential_ref: str,
protocol_order: Sequence[str],
) -> SourceObservation:
"""Observe connectivity, authentication, protocol, and inventory.
``protocol_order`` either enumerates Auto-detect probes or names one
owner-constrained protocol. A returned protocol may be established by
a protocol-shaped upstream response, by a shipped API-key vendor pin,
or by a concrete `custom` declaration. Schema-validation errors,
altered-credential controls and public inventory cannot establish
authentication. A shaped success can; a bare status cannot. Auto still
requires response-backed proof; order alone never proves a protocol.
Explicit unverified API-key saving and completed Hub OAuth admission
belong to Source creation, not this non-persisting evidence result.
They retain a fixed protocol owner with verification pending and do
not turn an unknown/rejected observation into authentication proof.
"""
...
# --- subscription OAuth (channel-specific ownership) ------------------
async def start_oauth(self, source_id: str, vendor: str) -> OAuthFlowState: ...
async def oauth_status(self, flow_id: str) -> OAuthFlowState: ...
async def submit_oauth(self, flow_id: str, value: str) -> OAuthFlowState:
"""``value`` per ``expects``: pasted code or callback URL.
A value the provider refuses without writing anything raises
``OAuthSubmissionRejectedError`` and leaves the flow awaiting action.
"""
...
async def cancel_oauth(self, flow_id: str) -> None: ...
# --- invocation primitive (exactly one source; no engine fallback) ---
async def invoke(
self,
source_id: str,
model_id: str,
request: Mapping[str, Any],
stream: bool,
origin: str,
*,
on_admitted: Callable[[], None] | None = None,
) -> InvokeHandle:
"""``origin`` = requesting agent name ("claude"|"codex"|"opencode"|...).
Raises ``OriginNotAllowedError`` when the binding's ``allowed_origins``
excludes it (backstop; L2 must have filtered already). ``model_id`` is
the chosen canonical route target. API-key targets need not be listed;
subscriptions retain their existing exact inventory admission.
The adapter must keep exact source isolation without inventing inventory.
After validating source/origin, acquire the transport lease and call
``on_admitted`` exactly once before any network wait. Callback failure
releases the lease without invoking upstream. Transport completion,
close, or cancellation releases the lease independently of settlement.
Cancellation before handle return raises ``InvokeCancelledError`` when
wire facts were observed, so L2 can meter them without inventing failure.
"""
...