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
"""C-2 provider adapter interface (``agent-core-contracts/provider.md``).
One adapter per wire protocol. An adapter speaks HTTP to the endpoint it is
given, converts canonical messages with the cross-provider rules, and yields
``ProviderEvent``s ending in exactly one ``Done`` or ``ProviderError``.
"""
from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any, AsyncIterator, Literal, Mapping, Optional, Protocol, Union
from core.agent_core.cancel import CancelToken
from core.agent_core.messages import AssistantMessage, HostedImage, Message, ProtocolName
from core.agent_core.tools.base import ToolSpec
ErrorKind = Literal[
"overflow",
"rate_limit",
"overloaded",
"network",
"stalled",
"server",
# The provider's stream ended after output without a terminal (Model Hub's ``modelHub.errors.stream_interrupted``).
"interrupted",
"auth",
"invalid_request",
"aborted",
"unknown",
]
RETRYABLE_ERROR_KINDS: frozenset[str] = frozenset(
{"rate_limit", "overloaded", "network", "stalled", "server", "interrupted"}
)
#: A response that dropped after streaming thinking alone is retried once for these (owner decision, 2026-10-11):
#: a transient failure, or one nothing classified. Never for a rate limit, an overflow, auth, or a rejected request.
THINKING_DROP_RETRY_KINDS: frozenset[str] = frozenset(
{"overloaded", "network", "stalled", "server", "interrupted", "unknown"}
)
@dataclass(frozen=True)
class HostedToolRoute:
"""How a hop sends one enabled search tool, from its C-6 facts (``HopResolution.hosted_tools``,
``vibey-hosted-tools.md`` §3.4, §4.1).
The agent declares the tool natively exactly when Model Hub assumes the hop runs it (``native: assumed``), with
the wire ``declaration`` and the Responses ``include`` values; otherwise (``proxy``) as the same-named function,
which the gateway's executor chain runs. ``replay`` is whether a hosted payload may go back verbatim to this hop.
``refused``: the hop's own Source would run the tool but refused it (a current refusal, C-6 ``refused``), so a call
here is a fallback from that Source.
"""
mode: Literal["native", "proxy"]
replay: bool
declaration: Optional[Mapping[str, Any]] = None
include: tuple[str, ...] = ()
refused: bool = False
#: Internal reason this request selected a recovery proxy, never refusal/capability evidence.
route_switch: Optional[str] = None
def __post_init__(self) -> None:
if self.mode not in ("native", "proxy"):
raise ValueError(f"unknown hosted tool mode: {self.mode!r}")
if not isinstance(self.replay, bool) or not isinstance(self.refused, bool):
raise ValueError("hosted replay and refused must be booleans")
if self.route_switch is not None and self.route_switch != "native_interrupted":
raise ValueError(f"unknown hosted route switch: {self.route_switch}")
if self.route_switch is not None and self.mode != "proxy":
raise ValueError("a route switch must use a proxy hosted tool")
if self.refused and self.mode != "proxy":
raise ValueError("a tool its Source refused runs as its function")
if self.mode == "proxy":
if self.declaration is not None or self.include:
raise ValueError("a proxy hosted tool has no native declaration or include")
return
declaration = self.declaration
if not isinstance(declaration, Mapping) or not isinstance(declaration.get("type"), str) or not declaration["type"]:
raise ValueError("a native hosted tool needs a declaration with a type")
if not isinstance(self.include, tuple) or not all(isinstance(item, str) and item for item in self.include):
raise ValueError("hosted include must be a tuple of strings")
@dataclass(frozen=True)
class ImageModel:
"""One image model ``image_generate`` may call (C-6 ``HopResolution.hosted_tools.image_generate``, §7.2): its
Source, its id, one short description line, and the optional arguments it takes."""
source_id: str
model_id: str
description: str
params: tuple[str, ...]
size_forms: tuple[str, ...]
@dataclass(frozen=True)
class ImageModels:
"""The turn's image models, default first, as the ``image_generate`` enum lists them."""
models: tuple[ImageModel, ...]
def __post_init__(self) -> None:
if not self.models or not all(isinstance(model, ImageModel) for model in self.models):
raise ValueError("image models are a non-empty tuple of ImageModel")
@dataclass(frozen=True)
class ModelEndpoint:
protocol: ProtocolName
base_url: str
model_id: str
token: str = field(repr=False)
request_headers: Mapping[str, str] = field(default_factory=dict)
provider: str = ""
#: Route-local cache lifetime override. The Model Hub validates provider
#: semantics before it reaches the adapter; unknown/relay routes use it only
#: for C-9 clearing, while official OpenAI Responses routes may also wire it.
cache_ttl: Optional[Literal["5m", "30m", "1h", "12h"]] = None
#: True only when Model Hub confirmed that the provider-specific TTL can be
#: sent on the wire (currently official OpenAI Responses GPT-5.6+).
cache_ttl_wire: bool = False
#: The hop's Source (``HopResolution.source_id``): the pin of a request that carries native hosted content.
source_id: Optional[str] = None
#: That Source's credential-free identity (``HopResolution.source_identity``): the account a response's opaque
#: payloads are bound to (``cross-provider.md``).
source_identity: Optional[str] = None
#: A portable request (§3.5, ``portable_endpoint``): never pinned, and no native hosted content. Its Source and
#: identity stay, so a response its own Source serves is still attributed to them.
portable: bool = False
#: The opaque payloads, by (Source identity, kind), that go nowhere: their provider refused one in this Session
#: (§3.5). A message that identity served is sent without them, as a different origin's would be.
opaque_refused: frozenset[tuple[str | None, str]] = frozenset()
#: Each enabled search tool's route on this hop, in Model Hub's order; empty when none is enabled.
hosted_tools: Mapping[str, HostedToolRoute] = field(default_factory=dict)
#: The models ``image_generate`` may call; None when the tool is off or no model is available.
image_models: Optional[ImageModels] = None
@dataclass(frozen=True)
class ModelCapabilities:
"""From C-6 hop resolution. ``None`` means Model Hub does not know; callers treat it conservatively."""
context_window: Optional[int] = None
input_limit: Optional[int] = None
max_output_tokens: Optional[int] = None
supports_tools: Optional[bool] = None
supports_images: Optional[bool] = None
supports_reasoning: Optional[bool] = None
reasoning_efforts: tuple[str, ...] = ()
#: The context sizes past which the model's list price steps up, ascending; empty when flat or unknown. C-9 keeps
#: the compaction threshold below the smallest one it can (``context.md`` section 1).
context_price_steps: tuple[int, ...] = ()
class MediaLoader(Protocol):
"""Supplied by the adapter layer; resolves an ``ImageBlock.media_token`` to its bytes at request time."""
async def load(self, media_token: str) -> tuple[bytes, str]:
"""Return the bytes and their mime type."""
...
class MediaSink(Protocol):
"""Supplied by the adapter layer; keeps a generated image as a local file (``vibey-hosted-tools.md`` §7.3).
The image never enters a message or the model's context: only its path, in the call's record.
"""
async def save_image(self, encoded: str) -> HostedImage:
"""Decode base64 ``encoded``, store it, and return its record: the file's absolute path, its type as its
bytes show it, and its size. Raises ``ValueError`` when ``encoded`` is not a supported image in base64, and
``OSError`` when it cannot be stored."""
...
@dataclass(frozen=True)
class ModelRequest:
endpoint: ModelEndpoint
system: str
messages: tuple[Message, ...]
tools: tuple[ToolSpec, ...]
max_tokens: int
reasoning_effort: Optional[str] = None
cache: Literal["default", "none"] = "default"
supports_images: bool = False
"""Resolved by the loop from ``ModelCapabilities``; an unknown capability counts as False."""
@dataclass(frozen=True)
class TextDelta:
index: int
delta: str
@dataclass(frozen=True)
class ThinkingDelta:
index: int
delta: str
@dataclass(frozen=True)
class ToolCallStart:
index: int
id: str
name: str
@dataclass(frozen=True)
class ToolCallDelta:
index: int
arguments_delta: str
@dataclass(frozen=True)
class BlockEnd:
index: int
@dataclass(frozen=True)
class Done:
message: AssistantMessage
@dataclass(frozen=True)
class MalformedToolCall:
"""A provider tool call whose final JSON arguments were not a JSON object.
This carries only canonical call identity. The malformed provider bytes never
cross the adapter boundary or enter the transcript.
"""
id: str
name: str
@dataclass(frozen=True)
class ProviderError:
kind: ErrorKind
message: str
retryable: bool
retry_after_s: Optional[float] = None
status: Optional[int] = None
partial: Optional[AssistantMessage] = None
#: The response streamed thinking and nothing else before this error (``THINKING_DROP_RETRY_KINDS``): it is
#: ``retryable``, and the loop retries it at most once per request (``provider.md``).
after_thinking: bool = False
#: A provider refusal which can change how history is rendered (``vibey-hosted-tools.md`` §3.5).
#: Most require no output. Corroborated search refusals also permit repair of an uncommitted partial.
refusal: Optional["Refusal"] = None
#: Permission to continue from the committed transcript, not replay this request. False by default:
#: only a classified transient failure grants it, even when streaming makes ``retryable`` false.
continuable: bool = False
#: Malformed final arguments are still strict protocol errors, but this
#: narrow metadata grants Vibey one transcript-only recovery. The partial
#: contains safe empty arguments for these calls; the loop must not execute them.
malformed_tool_calls: tuple[MalformedToolCall, ...] = ()
@dataclass(frozen=True)
class Refusal:
"""Why a refused request can be rendered differently on the next attempt (§3.5).
``pin_unavailable``: the gateway handed a pinned request back; ``tool`` and ``aspect`` name the narrow hosted rule
that fired, when one did. ``opaque_refused``: the provider refused an opaque payload a response of this Source
identity minted, replayed under an account that cannot read it (a key change, or a relay serving from another
account); ``payloads`` says which kind (``OPAQUE_PAYLOADS``): Anthropic names it, xAI's "Could not decrypt the
provided encrypted_content" does not, so it is both. ``source_id`` and ``source_identity`` are the refused
request's hop. ``search_history`` is a narrower Anthropic compatibility recovery: only completed historical
web searches become portable; in-flight content and native tool declarations stay intact. It is a run-local
replay decision, not a claim that the Source cannot execute searches or that a relay account changed.
"""
kind: Literal["pin_unavailable", "opaque_refused", "search_history"]
source_id: Optional[str] = None
source_identity: Optional[str] = None
tool: Optional[str] = None
aspect: Optional[str] = None
payloads: tuple["OpaquePayload", ...] = ()
#: The kinds of opaque payload a response carries for its own account: ``hosted``, a hosted call's native payload
#: (Anthropic's encrypted search results); ``signature``, signed or redacted thinking and other per-block signatures.
OpaquePayload = Literal["hosted", "signature"]
OPAQUE_PAYLOADS: tuple[OpaquePayload, ...] = ("hosted", "signature")
ProviderEvent = Union[TextDelta, ThinkingDelta, ToolCallStart, ToolCallDelta, BlockEnd, Done, ProviderError]
class ProviderAdapter(Protocol):
protocol: ProtocolName
def stream(self, request: ModelRequest, cancel: CancelToken) -> AsyncIterator[ProviderEvent]: ...