Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
"""Provider-neutral realtime factory tests (AP-21/AP-22)."""
from __future__ import annotations
from types import SimpleNamespace
import pytest
import dodaios.realtime.factory as factory
from dodaios.core.config import VoiceConfig
from dodaios.realtime.factory import (
_provider_candidates,
_resolve_realtime_provider,
build_realtime_session,
realtime_available_provider,
realtime_browser_audio,
realtime_requires_webrtc_offer,
)
class _BaseProvider:
supports_realtime = True
input_sample_rate = 16_000
output_sample_rate = 24_000
def __init__(self, *, api_key=None):
self.api_key = api_key
async def can_open_duplex_session(self):
return bool(self.api_key)
async def open_session(self, cfg): # pragma: no cover - factory does not open
raise NotImplementedError
class _OpenAIProvider(_BaseProvider):
name = "openai-realtime"
credential_family = "openai"
credential_candidates = (("openai_api_key", "OPENAI_API_KEY"),)
class _GeminiProvider(_BaseProvider):
name = "gemini-live"
credential_candidates = (("gemini_api_key", "GEMINI_API_KEY"),)
# Mirrors the real adapter: its calls need browser echo-cancelled audio.
browser_audio = True
browser_audio_unsupported_renderers = frozenset({"gtkwebkit2"})
class _AcmeProvider(_BaseProvider):
name = "acme-realtime"
credential_candidates = (("acme_api_key", "ACME_API_KEY"),)
class _SubscriptionProvider(_BaseProvider):
name = "codex-subscription-realtime"
credential_family = "openai-chatgpt-subscription"
credential_candidates = ()
requires_webrtc_offer = True
implicit_usage_fallback_allowed = False
login_ready = False
def __init__(self):
super().__init__(api_key="external-login")
@classmethod
def external_login_ready(cls):
return cls.login_ready
_PLUGINS = {
"openai-realtime": _OpenAIProvider,
"gemini-live": _GeminiProvider,
"acme-realtime": _AcmeProvider,
"codex-subscription-realtime": _SubscriptionProvider,
}
def _cfg(
mode: str = "realtime",
provider: str = "openai-realtime",
profile: str = "",
) -> SimpleNamespace:
return SimpleNamespace(
voice=SimpleNamespace(mode=mode, profile=profile),
brain=SimpleNamespace(
reply_language="en",
providers={},
realtime=SimpleNamespace(
provider=provider,
fallback_provider=None,
fallback_provider_2=None,
),
),
)
def _fake_registry(
monkeypatch, keys: set[str], *, subscription_login: bool = False
) -> None:
import dodaios.realtime.factory as factory
monkeypatch.setattr(factory, "list_plugins", lambda _group: list(_PLUGINS))
monkeypatch.setattr(factory, "load", lambda _group, name, protocol=None: _PLUGINS[name])
_SubscriptionProvider.login_ready = subscription_login
def _get_secret(candidates):
slot = candidates[0][0]
family = (
"openai" if slot.startswith("openai")
else "acme" if slot.startswith("acme")
else "gemini"
)
return f"{family}-key" if family in keys else None
monkeypatch.setattr(factory, "get_secret_any", _get_secret)
@pytest.mark.parametrize(
("configured", "keys", "expected"),
[
("openai-realtime", {"openai"}, "openai-realtime"),
("gemini-live", {"gemini"}, "gemini-live"),
("openai-realtime", {"gemini"}, "gemini-live"),
("gemini-live", {"openai"}, "openai-realtime"),
("openai-realtime", {"openai", "gemini"}, "openai-realtime"),
("acme-realtime", {"acme"}, "acme-realtime"),
("openai-realtime", {"acme"}, "acme-realtime"),
("openai-realtime", set(), None),
],
)
def test_key_aware_cross_family_resolution(
monkeypatch, configured, keys, expected
) -> None:
_fake_registry(monkeypatch, keys)
config = _cfg(provider=configured)
resolved = _resolve_realtime_provider(config)
assert (resolved.name if resolved else None) == expected
assert realtime_available_provider(config) == expected
def test_explicit_fallback_order_precedes_other_installed_plugins(monkeypatch):
_fake_registry(monkeypatch, {"openai", "gemini"})
config = _cfg(provider="openai-realtime")
config.brain.realtime.fallback_provider = "gemini-live"
assert [provider.name for provider in _provider_candidates(config)] == [
"openai-realtime",
"gemini-live",
]
def test_external_login_provider_is_candidate_without_a_fake_api_key(monkeypatch):
_fake_registry(monkeypatch, set(), subscription_login=True)
config = _cfg(provider="codex-subscription-realtime")
providers = _provider_candidates(config)
assert [provider.name for provider in providers] == [
"codex-subscription-realtime"
]
assert providers[0].credential_family == "openai-chatgpt-subscription"
def test_subscription_primary_never_uses_ambient_api_fallback(
monkeypatch,
):
_fake_registry(monkeypatch, {"openai"}, subscription_login=False)
config = _cfg(provider="codex-subscription-realtime")
assert _provider_candidates(config) == []
def test_subscription_and_api_credentials_remain_distinct_fallbacks(monkeypatch):
_fake_registry(monkeypatch, {"openai"}, subscription_login=True)
config = _cfg(provider="codex-subscription-realtime")
config.brain.realtime.fallback_provider = "openai-realtime"
providers = _provider_candidates(config)
assert [provider.name for provider in providers] == [
"codex-subscription-realtime",
"openai-realtime",
]
assert [provider.credential_family for provider in providers] == [
"openai-chatgpt-subscription",
"openai",
]
assert realtime_requires_webrtc_offer(config) is True
def test_api_provider_does_not_request_unneeded_browser_sdp(monkeypatch):
_fake_registry(monkeypatch, {"openai"}, subscription_login=True)
config = _cfg(provider="openai-realtime")
assert realtime_requires_webrtc_offer(config) is False
def test_logged_in_subscription_is_never_an_ambient_candidate(monkeypatch):
_fake_registry(monkeypatch, set(), subscription_login=True)
config = _cfg(provider="openai-realtime")
assert _provider_candidates(config) == []
assert realtime_available_provider(config) is None
def test_unpinned_browser_audio_follows_the_automatically_chosen_provider(monkeypatch):
# Issue #399: a Gemini-only install without a pin opens its call on
# Gemini Live, yet browser_audio read only the (absent) pin and said no.
_fake_registry(monkeypatch, {"gemini"})
config = _cfg(provider="")
assert realtime_available_provider(config) == "gemini-live"
assert realtime_browser_audio(config) is True
def test_unpinned_browser_audio_is_false_without_a_ready_provider(monkeypatch):
_fake_registry(monkeypatch, set())
assert realtime_browser_audio(_cfg(provider="")) is False
assert realtime_browser_audio(None) is False
def test_unpinned_browser_audio_reads_only_up_to_the_first_ready_provider(monkeypatch):
# The first installed provider with a key decides; credentials of the
# providers behind it are never read on this path.
_fake_registry(monkeypatch, {"openai", "gemini"})
read: list[str] = []
resolve = factory.get_secret_any
def _spy(candidates):
read.append(candidates[0][0])
return resolve(candidates)
monkeypatch.setattr(factory, "get_secret_any", _spy)
assert realtime_browser_audio(_cfg(provider="")) is False
assert read == ["openai_api_key"]
def test_pinned_browser_audio_answers_for_the_pin_without_reading_credentials(monkeypatch):
_fake_registry(monkeypatch, {"openai", "gemini"})
def _no_credential_reads(_candidates):
raise AssertionError("a pinned provider must answer without reading credentials")
monkeypatch.setattr(factory, "get_secret_any", _no_credential_reads)
assert realtime_browser_audio(_cfg(provider="gemini-live")) is True
assert realtime_browser_audio(_cfg(provider="openai-realtime")) is False
def test_gemini_browser_audio_uses_native_desktop_audio_on_webkitgtk(monkeypatch):
_fake_registry(monkeypatch, {"gemini"})
config = _cfg(provider="gemini-live")
assert realtime_browser_audio(config, desktop_renderer="gtkwebkit2") is False
assert realtime_browser_audio(config, desktop_renderer="edgechromium") is True
# Remote browser callers do not pass an embedded renderer.
assert realtime_browser_audio(config) is True
def test_pipeline_mode_never_builds_realtime_session(monkeypatch):
_fake_registry(monkeypatch, {"openai"})
assert (
build_realtime_session(
cfg=_cfg(mode="pipeline"),
bus=None,
session_id="s",
send_binary=None,
send_json=None,
)
is None
)
def test_realtime_tool_mode_defaults_to_hybrid_native_tools() -> None:
"""ADR-0035: the live model holds the catalog itself; the Tool Model is
for computer use. ``delegate`` and ``direct`` remain explicit choices."""
assert VoiceConfig().realtime_tool_mode == "hybrid"
# 0 = unbounded: the whole catalog is declared (maintainer mandate
# 2026-08-24 — declaration budgets are not a cost lever).
assert VoiceConfig().realtime_tool_declaration_budget_tokens == 0
def test_one_realtime_key_builds_without_a_classic_brain(monkeypatch) -> None:
_fake_registry(monkeypatch, {"gemini"})
session = build_realtime_session(
cfg=_cfg(provider="openai-realtime"),
bus=None,
session_id="realtime-only",
send_binary=lambda _data: None,
send_json=lambda _message: None,
brain=None,
)
assert session is not None
assert session._brain is None
assert session._tool_mode == "delegate"
assert session._delegate_enabled is False
assert [provider.name for provider in session._providers] == ["gemini-live"]
def test_realtime_without_any_key_degrades_to_pipeline(monkeypatch):
_fake_registry(monkeypatch, set())
assert (
build_realtime_session(
cfg=_cfg(),
bus=None,
session_id="s",
send_binary=None,
send_json=None,
)
is None
)
def test_build_passes_every_keyed_family_for_handshake_fallback(monkeypatch):
_fake_registry(monkeypatch, {"openai", "gemini"})
session = build_realtime_session(
cfg=_cfg(),
bus=None,
session_id="s",
send_binary=lambda _data: None,
send_json=lambda _message: None,
half_duplex=True,
)
assert session is not None
assert [provider.name for provider in session._providers] == [
"openai-realtime",
"gemini-live",
]
assert session._half_duplex is True
def test_same_family_delegate_chain_logs_ap22_warning(caplog):
"""BUG-089: realtime + whole brain chain on ONE family = one quota hit
silences both tiers; the build names the risk and the in-app fix."""
import logging
from dodaios.realtime.factory import _warn_on_same_family_delegate_chain
cfg = SimpleNamespace(
brain=SimpleNamespace(
primary="gemini",
deep_brain="antigravity",
routing_provider="gemini",
local_fallback="gemini",
)
)
with caplog.at_level(logging.WARNING, logger="dodaios.realtime.factory"):
_warn_on_same_family_delegate_chain(cfg, "gemini-live")
assert any("AP-22" in record.message for record in caplog.records)
def test_cross_family_delegate_chain_stays_quiet(caplog):
import logging
from dodaios.realtime.factory import _warn_on_same_family_delegate_chain
cfg = SimpleNamespace(
brain=SimpleNamespace(
primary="gemini",
deep_brain=None,
routing_provider="claude-api",
local_fallback="openrouter",
)
)
with caplog.at_level(logging.WARNING, logger="dodaios.realtime.factory"):
_warn_on_same_family_delegate_chain(cfg, "gemini-live")
assert not [record for record in caplog.records if "AP-22" in record.message]
class _WarmProbe:
"""Minimal realtime provider exposing the optional warm capability."""
supports_realtime = True
eager_warm_as_fallback = True
def __init__(self) -> None:
self.calls = 0
async def warm_transport(self, cfg) -> None: # noqa: ANN001 - probe shape
del cfg
self.calls += 1
class _NoWarmProbe:
supports_realtime = True
@pytest.mark.asyncio
async def test_warm_selected_transports_skips_providers_without_the_capability(
monkeypatch,
) -> None:
"""A capability probe, never a provider-id check (AP-21)."""
warm = _WarmProbe()
loaded = {"warm-me": warm, "plain": _NoWarmProbe()}
monkeypatch.setattr(
factory, "_explicit_provider_ids", lambda _cfg: ["plain", "warm-me"]
)
monkeypatch.setattr(
factory, "load", lambda _group, pid, protocol=None: loaded[pid]
)
await factory.realtime_warm_selected_transports(_cfg())
assert warm.calls == 1
@pytest.mark.asyncio
async def test_warm_selected_transports_does_not_prewarm_a_heavy_fallback(
monkeypatch,
) -> None:
"""An inactive fallback must not compete with the primary for GPU/RAM."""
primary = _WarmProbe()
fallback = _WarmProbe()
fallback.eager_warm_as_fallback = False
loaded = {"primary": primary, "heavy-fallback": fallback}
monkeypatch.setattr(
factory,
"_explicit_provider_ids",
lambda _cfg: ["primary", "heavy-fallback"],
)
monkeypatch.setattr(
factory, "load", lambda _group, pid, protocol=None: loaded[pid]
)
await factory.realtime_warm_selected_transports(_cfg())
assert primary.calls == 1
assert fallback.calls == 0
class _PrespawnProbe:
"""Minimal realtime provider exposing the spawn-only prestart."""
supports_realtime = True
def __init__(self) -> None:
self.calls = 0
async def prespawn_transport(self, cfg) -> bool: # noqa: ANN001 - probe shape
del cfg
self.calls += 1
return True
@pytest.mark.asyncio
@pytest.mark.parametrize("eager_fallback", [False, True])
async def test_prespawn_only_starts_primary_and_opted_in_fallback(
monkeypatch, eager_fallback
) -> None:
"""A process spawn can load a whole GPU stack even without awaiting readiness."""
primary = _PrespawnProbe()
fallback = _PrespawnProbe()
fallback.eager_warm_as_fallback = eager_fallback
loaded = {"primary": primary, "plain": _NoWarmProbe(), "fallback": fallback}
def _load(_group, pid, protocol=None): # noqa: ANN001 - probe shape
if pid == "broken":
raise RuntimeError("plugin exploded")
return loaded[pid]
monkeypatch.setattr(
factory,
"_explicit_provider_ids",
lambda _cfg: ["primary", "plain", "broken", "fallback"],
)
monkeypatch.setattr(factory, "load", _load)
await factory.realtime_prespawn_transports(_cfg())
assert primary.calls == 1
assert fallback.calls == int(eager_fallback)
@pytest.mark.asyncio
async def test_prespawn_skips_a_pipeline_mode_install(monkeypatch) -> None:
"""A stale realtime pin must not spawn a server for a disabled feature."""
probe = _PrespawnProbe()
monkeypatch.setattr(factory, "_explicit_provider_ids", lambda _cfg: ["probe"])
monkeypatch.setattr(
factory, "load", lambda _group, _pid, protocol=None: probe
)
await factory.realtime_prespawn_transports(_cfg(mode="pipeline"))
assert probe.calls == 0
@pytest.mark.asyncio
async def test_prespawn_ignores_unselected_plugins(monkeypatch) -> None:
"""An installed but unselected plugin must never spawn a process."""
probe = _PrespawnProbe()
monkeypatch.setattr(factory, "_explicit_provider_ids", lambda _cfg: [])
monkeypatch.setattr(
factory, "load", lambda _group, _pid, protocol=None: probe
)
await factory.realtime_prespawn_transports(_cfg())
assert probe.calls == 0
@pytest.mark.asyncio
async def test_warm_selected_transports_survives_one_broken_provider(
monkeypatch,
) -> None:
"""Warming is advisory: a plugin that explodes must not stop the others,
and must never reach the caller."""
warm = _WarmProbe()
def _load(_group, pid, protocol=None): # noqa: ANN001 - probe shape
if pid == "broken":
raise RuntimeError("plugin exploded")
return warm
monkeypatch.setattr(
factory, "_explicit_provider_ids", lambda _cfg: ["broken", "warm-me"]
)
monkeypatch.setattr(factory, "load", _load)
await factory.realtime_warm_selected_transports(_cfg())
assert warm.calls == 1
@pytest.mark.asyncio
async def test_warm_selected_transports_ignores_unselected_plugins(
monkeypatch,
) -> None:
"""An installed but unselected plugin must not spawn a process or touch a
credential on its own."""
warm = _WarmProbe()
monkeypatch.setattr(factory, "_explicit_provider_ids", lambda _cfg: [])
monkeypatch.setattr(
factory, "load", lambda _group, _pid, protocol=None: warm
)
await factory.realtime_warm_selected_transports(_cfg())
assert warm.calls == 0
@pytest.mark.asyncio
async def test_warm_selected_transports_skips_a_pipeline_mode_install(
monkeypatch,
) -> None:
"""A stale realtime pin must not spawn a transport for a disabled feature.
Warming a subscription transport means spawning a process, running a live
account check, and HOLDING the profile lock — which is what made the user's
own Codex login report "busy" on an install whose voice runs the classic
pipeline. Gate on the same switch ``build_realtime_session`` reads.
"""
warm = _WarmProbe()
monkeypatch.setattr(
factory, "_explicit_provider_ids", lambda _cfg: ["warm-me"]
)
monkeypatch.setattr(
factory, "load", lambda _group, _pid, protocol=None: warm
)
await factory.realtime_warm_selected_transports(_cfg(mode="pipeline"))
assert warm.calls == 0
@pytest.mark.asyncio
async def test_warm_selected_transports_still_warms_the_realtime_install(
monkeypatch,
) -> None:
"""The mirror: the case warming EXISTS for keeps working.
Warming is about the cold start before the first wake word, so it must
depend on the configured mode alone — never on a call being in flight.
"""
warm = _WarmProbe()
monkeypatch.setattr(
factory, "_explicit_provider_ids", lambda _cfg: ["warm-me"]
)
monkeypatch.setattr(
factory, "load", lambda _group, _pid, protocol=None: warm
)
await factory.realtime_warm_selected_transports(
_cfg(mode="realtime", provider="openai-realtime")
)
assert warm.calls == 1
@pytest.mark.asyncio
async def test_warm_selected_transports_skips_the_subscription_pipeline_profile(
monkeypatch,
) -> None:
"""An explicit classic profile must not warm an unused duplex transport."""
warm = _WarmProbe()
monkeypatch.setattr(
factory,
"_explicit_provider_ids",
lambda _cfg: ["warm-me"],
)
monkeypatch.setattr(
factory,
"load",
lambda _group, _pid, protocol=None: warm,
)
await factory.realtime_warm_selected_transports(
_cfg(
mode="realtime",
provider="openai-realtime",
profile="codex-subscription-voice",
)
)
assert warm.calls == 0
@pytest.mark.asyncio
async def test_warm_selected_transports_keeps_codex_realtime_provider_realtime(
monkeypatch,
) -> None:
warm = _WarmProbe()
monkeypatch.setattr(
factory,
"_explicit_provider_ids",
lambda _cfg: ["codex-subscription-realtime"],
)
monkeypatch.setattr(
factory,
"load",
lambda _group, _pid, protocol=None: warm,
)
await factory.realtime_warm_selected_transports(
_cfg(mode="realtime", provider="codex-subscription-realtime")
)
assert warm.calls == 1
def test_declared_handshake_budget_reaches_the_surface(monkeypatch) -> None:
"""A surface must not call a start attempt dead inside a declared budget.
The browser gave every attempt a fixed 20 s while the subscription
transport declares 45 s and documents 15-25 s cold starts, so a cold
subscription call could be reported as a timed-out connection while the
backend was still legitimately negotiating.
"""
class _SlowStart(_BaseProvider):
name = "codex-subscription-realtime"
credential_candidates = ()
handshake_budget_s = 45.0
@classmethod
def external_login_ready(cls):
return True
monkeypatch.setattr(factory, "list_plugins", lambda _group: ["codex-subscription-realtime"])
monkeypatch.setattr(factory, "load", lambda _group, _name, protocol=None: _SlowStart)
budget = factory.realtime_handshake_budget_s(
_cfg(provider="codex-subscription-realtime")
)
assert budget == 45.0
def test_handshake_budget_never_drops_below_the_shared_default(monkeypatch) -> None:
"""A provider that declares nothing keeps the historical ceiling."""
_fake_registry(monkeypatch, {"openai"})
from dodaios.realtime.session import _PROVIDER_HANDSHAKE_TOTAL_TIMEOUT_S
assert factory.realtime_handshake_budget_s(_cfg()) == pytest.approx(
_PROVIDER_HANDSHAKE_TOTAL_TIMEOUT_S
)
def test_a_subscription_brain_behind_subscription_voice_warns(monkeypatch, caplog) -> None:
"""AP-22: the one chain where a single 429 silences voice AND actions.
``codex`` without an OpenAI key runs on the SAME ChatGPT plan as the
subscription voice. Resolving it to the generic ``openai`` family meant
this exact configuration never produced the warning it exists for.
"""
monkeypatch.setattr(factory, "get_secret_any", lambda _candidates: None)
config = _cfg(provider="codex-subscription-realtime")
config.brain.primary = "codex"
config.brain.deep_brain = "codex"
config.brain.routing_provider = None
config.brain.local_fallback = None
with caplog.at_level("WARNING"):
factory._warn_on_same_family_delegate_chain(
config,
"codex-subscription-realtime",
credential_family="openai-chatgpt-subscription",
)
assert any("AP-22" in record.message for record in caplog.records)
def test_a_metered_codex_brain_behind_subscription_voice_does_not_warn(
monkeypatch, caplog
) -> None:
"""With an OpenAI key the brain bills a DIFFERENT pool — no false alarm."""
monkeypatch.setattr(factory, "get_secret_any", lambda _candidates: "openai-key")
config = _cfg(provider="codex-subscription-realtime")
config.brain.primary = "codex"
config.brain.deep_brain = None
config.brain.routing_provider = None
config.brain.local_fallback = None
with caplog.at_level("WARNING"):
factory._warn_on_same_family_delegate_chain(
config,
"codex-subscription-realtime",
credential_family="openai-chatgpt-subscription",
)
assert not [record for record in caplog.records if "AP-22" in record.message]