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
feat(voice): one five-second tool budget for every plugin in the live voice path
rubenluetke10-beep3ed89d4d435e
diff --git a/jarvis/core/tool_budget.py b/jarvis/core/tool_budget.pynew file mode 100644index 0000000000..d1f2b8c3b0--- /dev/null+++ b/jarvis/core/tool_budget.py@@ -0,0 +1,36 @@+"""The one time budget every tool in the live voice path is sized against.++A native tool call blocks the live model until its result arrives (ADR-0035+§3), so a slow tool is a mute Jarvis. The maintainer's standing rule+(2026-08-22): whatever a tool does for a spoken request is finished — or has+honestly handed back — within five seconds, for every plugin, not one. Live+2026-08-22 20:01:52 was the counter-example: a ``youtube_music`` play sat 199 s+on a stuck player host while every other tool of the day answered in under 3 s.++Three layers read this number, each from here so they cannot drift apart:++* the realtime session releases the live model with a pending result once a+ native call runs past it (``jarvis/realtime/session.py``);+* tools that wait on something (a player confirming playback, a browser+ registering a media session) size their confirm windows under it, leaving+ room for the request that precedes the wait;+* the REST plugins' shared HTTP pool uses it as the request timeout — a+ single API round trip that needs longer is a hung API, not a slow one, and+ the turn has already been released by then.++A tool that legitimately needs longer (a long job, a download) does not belong+in a synchronous voice call at all: it dispatches and reports back through the+orchestrator, which has its own progress bridge.+"""++from __future__ import annotations++#: Seconds one native tool call may take in the live voice path before the+#: model is released with an honest "still running" result.+VOICE_TOOL_BUDGET_S = 5.0++#: Default request timeout for the REST plugins' shared HTTP pool. Equal to the+#: voice budget on purpose: a round trip that is not back by then cannot make+#: the turn any more, and failing it here frees the connection and logs the+#: cause instead of letting the call ride to the old 20 s transport default.+REST_REQUEST_TIMEOUT_S = VOICE_TOOL_BUDGET_Sdiff --git a/jarvis/plugins/tool/_http_pool.py b/jarvis/plugins/tool/_http_pool.pyindex 88682af0af..2009f7d456 100644--- a/jarvis/plugins/tool/_http_pool.py+++ b/jarvis/plugins/tool/_http_pool.py@@ -25,7 +25,14 @@ class HttpClientPool:``httpx.MockTransport`` exactly as they did with the per-request clients."""- def __init__(self, *, timeout_s: float = 20.0, transport: Any | None = None) -> None:+ def __init__(self, *, timeout_s: float | None = None, transport: Any | None = None) -> None:+ if timeout_s is None:+ # The shared voice tool budget (5 s): a round trip not back by then+ # cannot make the spoken turn any more — fail it, free the+ # connection, log the cause. A tool that knows better passes its own.+ from jarvis.core.tool_budget import REST_REQUEST_TIMEOUT_S++ timeout_s = REST_REQUEST_TIMEOUT_Sself._timeout_s = timeout_sself._transport = transportself._client: Any | None = Nonediff --git a/jarvis/plugins/tool/youtube_music_rest.py b/jarvis/plugins/tool/youtube_music_rest.pyindex c94669eac5..da8b60ccb8 100644--- a/jarvis/plugins/tool/youtube_music_rest.py+++ b/jarvis/plugins/tool/youtube_music_rest.py@@ -99,16 +99,28 @@ _PRESS_PLAY_NOTE = ()# How long `play` watches the background player before it stops claiming to-# know. A page load plus buffering takes four to five seconds (measured-# 2026-08-18: position starts advancing ~4.5 s after load).-_PLAYER_CONFIRM_TIMEOUT_S = 9.0+# know. Sized under the shared voice tool budget (``VOICE_TOOL_BUDGET_S``, 5 s+# — ``jarvis/core/tool_budget.py``) with room for the search that precedes it+# (~0.4 s live) and the load: the live model is released at the budget, and a+# confirm still running then is wasted. A warm player reports "playing"+# (``paused`` false) well under a second after load; a cold one within about+# two (measured 2026-08-18: position advances ~4.5 s after load, the ``paused``+# flag flips earlier — that flag is the confirmation now, see+# ``_play_in_player``).+_PLAYER_CONFIRM_TIMEOUT_S = 3.5#: Per-read bound while confirming playback in the background player. The#: host answers "loading" at once when the page is still turning, so a read#: that takes longer than this is a stuck host, not a slow page — give up on#: that read and poll again rather than inherit the 10 s transport default.-_PLAYER_READ_TIMEOUT_S = 3.0-#: Bound for bringing the player window forward at the end of a confirm.-_PLAYER_SHOW_TIMEOUT_S = 5.0+_PLAYER_READ_TIMEOUT_S = 2.0+#: Bound for bringing the player window forward at the end of a confirm. A+#: window call the host cannot answer in this time is a stuck host.+_PLAYER_SHOW_TIMEOUT_S = 2.0+_STILL_STARTING_NOTE = (+ "YouTube Music is still loading the song in the background player; it "+ "normally starts within a few seconds. If it stays silent, ask to play it "+ "again."+)# Music category on YouTube. Songs on YouTube Music are videos in it._MUSIC_CATEGORY_ID = "10"@@ -118,9 +130,11 @@ _ART_TRACK_SUFFIX = " - Topic"# How long `play` watches the media session for the new track before it stops# claiming to know. A warm browser registers the session within a second; a# cold start needs four to five (measured live 2026-08-18: Edge from closed took-# ~4 s). Bounded so a voice turn never hangs on a browser that never starts,-# and the wait ends the moment playback is seen.-_CONFIRM_TIMEOUT_S = 6.0+# ~4 s). Bounded under the shared voice tool budget so a voice turn never hangs+# on a browser that never starts — a cold browser may still be starting when+# the wait ends, and the note says so; the wait ends the moment playback is+# seen.+_CONFIRM_TIMEOUT_S = 3.5_CONFIRM_STEP_S = 0.5@@ -494,8 +508,12 @@ class YouTubeMusicRestTool:)out.update(playback_confirmed=False, needs_attention="consent", note=_CONSENT_NOTE)return out- playing = last.get("has_video") and last.get("paused") is False- if playing and (last.get("position") or 0) > 0:+ # ``paused`` false on the <video> element IS the confirmation: the+ # page's own play() went through, which is exactly what a blocked+ # autoplay refuses. Waiting for the position to advance as well+ # (buffering, ~4.5 s from load) bought no extra truth and cost the+ # whole voice budget on a cold start.+ if last.get("has_video") and last.get("paused") is False:out.update(playback_confirmed=True, now=self._player_now(last))return out# The page is up but paused: one programmatic nudge before asking@@ -506,12 +524,26 @@ class YouTubeMusicRestTool:await asyncio.to_thread(player.play)except Exception as exc: # noqa: BLE001 — the nudge is best-effortlog.debug("background player nudge failed: %s", exc)- try:- await asyncio.to_thread(_call_with_timeout, player.show, _PLAYER_SHOW_TIMEOUT_S)- except Exception as exc: # noqa: BLE001 — showing is best-effort- log.debug("background player show failed: %s", exc)- out.update(playback_confirmed=False, needs_attention="press_play", note=_PRESS_PLAY_NOTE)- if last:+ if last.get("has_video") and last.get("paused"):+ # Positive evidence of a start that did not happen — a video that+ # stayed paused through the nudge — is the one case where the+ # window comes forward: there is a play button to press.+ try:+ await asyncio.to_thread(+ _call_with_timeout, player.show, _PLAYER_SHOW_TIMEOUT_S+ )+ except Exception as exc: # noqa: BLE001 — showing is best-effort+ log.debug("background player show failed: %s", exc)+ out.update(+ playback_confirmed=False, needs_attention="press_play", note=_PRESS_PLAY_NOTE+ )+ out["now"] = self._player_now(last)+ return out+ # No video element yet (page still loading, or the host never+ # answered): nothing to press, so no window — say the song is still+ # starting and let the budget-released turn move on.+ out.update(playback_confirmed=False, note=_STILL_STARTING_NOTE)+ if last and not last.get("loading"):out["now"] = self._player_now(last)return outdiff --git a/jarvis/realtime/session.py b/jarvis/realtime/session.pyindex ed02bf08db..e10fab6595 100644--- a/jarvis/realtime/session.py+++ b/jarvis/realtime/session.py@@ -55,6 +55,7 @@ from jarvis.brain.turn_planner import ()from jarvis.core.protocols import AudioChunk, BrainMessagefrom jarvis.core.redact import safe_preview+from jarvis.core.tool_budget import VOICE_TOOL_BUDGET_Sfrom jarvis.core.turn_language import (is_substantive_turn,normalize_language_tag,@@ -635,19 +636,19 @@ _CAPABILITY_LIMITED_DELEGATE_BRIDGE_DELAY_S = 1.0# (3 s since 2026-08-18, ADR-0033). Kept as a module attribute so tests can# pin it low._INSTANT_ACK_GRACE_S = SHORT_GRACE_S-# Hard ceiling for ONE native tool call in the live voice path. A native call-# blocks the live model until its result arrives (ADR-0035 §3), so an unbounded-# wait IS a mute call: live 2026-08-22 20:01:52 a ``youtube_music`` play sat-# 199 s on a stuck background-player host — instant ack at 3 s, then nothing-# until 20:05:12 — while every other tool of the day finished in under 3 s-# (``REALTIME_TOOL_COMPLETED`` durations: search_web 2.1–2.9 s, run-skill-# <30 ms, youtube_music 2.6 s when the player answered). Past this ceiling the-# model gets an honest "still running" result and answers; the tool keeps-# running to completion in the background (an action mid-flight is never-# cancelled) and its late outcome is logged and recorded, not dropped. The-# ceiling is generous on purpose: the slowest honest path by design (YouTube-# Music's cold-start confirm, ~9 s plus a window show) still fits under it.-_NATIVE_TOOL_DEADLINE_S = 15.0+# Hard ceiling for ONE native tool call in the live voice path — the shared+# voice tool budget (``jarvis/core/tool_budget.py``), which every tool sizes+# its own waits under. A native call blocks the live model until its result+# arrives (ADR-0035 §3), so an unbounded wait IS a mute call: live 2026-08-22+# 20:01:52 a ``youtube_music`` play sat 199 s on a stuck background-player+# host — instant ack at 3 s, then nothing until 20:05:12 — while every other+# tool of the day finished in under 3 s (``REALTIME_TOOL_COMPLETED``+# durations: search_web 2.1–2.9 s, run-skill <30 ms, youtube_music 2.6 s when+# the player answered). Past this ceiling the model gets an honest "still+# running" result and answers; the tool keeps running to completion in the+# background (an action mid-flight is never cancelled) and its late outcome is+# logged and recorded, not dropped.+_NATIVE_TOOL_DEADLINE_S = VOICE_TOOL_BUDGET_S# 20 messages, not 8: a failed screen action typically costs the user several# correction turns, and each background completion adds a context note. With 8,# the original task was trimmed out exactly when the recovery turn needed itdiff --git a/tests/unit/plugins/tool/test_youtube_music_rest.py b/tests/unit/plugins/tool/test_youtube_music_rest.pyindex 905c51fb2c..951c9208b1 100644--- a/tests/unit/plugins/tool/test_youtube_music_rest.py+++ b/tests/unit/plugins/tool/test_youtube_music_rest.py@@ -575,7 +575,9 @@ async def test_play_confirm_is_bounded_by_wall_clock_when_the_player_is_slow():"""Live 2026-08-22 20:01:52: every state read sat out its transport timeout,the loop counted only its naps, and one play took 199 s. The loop now runson a wall-clock deadline, so a slow host costs the deadline, not its- multiple — and the window is still brought forward at the end."""+ multiple — and a page that never got past loading brings no window+ forward (there is nothing to press yet); the note says it is still+ starting."""import time as _timeclass SlowPlayer(FakePlayer):@@ -592,8 +594,31 @@ async def test_play_confirm_is_bounded_by_wall_clock_when_the_player_is_slow():elapsed = _time.monotonic() - startedassert elapsed < 3.0, f"confirm loop ran {elapsed:.1f}s for a 1.0s deadline"- assert out["playback_confirmed"] is False and out["needs_attention"] == "press_play"- assert player.shown == 1+ assert out["playback_confirmed"] is False and "needs_attention" not in out+ assert "still loading" in out["note"]+ assert player.shown == 0, "no video to press play on yet — the window stays minimized"+++async def test_play_confirms_the_moment_the_video_is_unpaused():+ """``paused`` false is the confirmation; the position advancing later is+ buffering, not more truth — waiting for it cost the whole voice budget on+ a cold start (the live model is released at 5 s)."""+ player = FakePlayer([_page(position=0.0)])+ tool = _tool(_search_handler, player=player, playback="background")+ out = await tool.play(query="karma police")+ assert out["playback_confirmed"] is True+ assert out["now"]["is_playing"] is True and out["now"]["position_s"] == 0+++def test_the_player_confirm_fits_under_the_voice_tool_budget():+ from jarvis.core.tool_budget import VOICE_TOOL_BUDGET_S+ from jarvis.plugins.tool import youtube_music_rest as mod++ # Search (~0.4 s live) + load + confirm + a show must stay under the budget+ # the live model is released at.+ assert mod._PLAYER_CONFIRM_TIMEOUT_S + 1.0 < VOICE_TOOL_BUDGET_S+ assert mod._CONFIRM_TIMEOUT_S + 1.0 < VOICE_TOOL_BUDGET_S+ assert mod._PLAYER_SHOW_TIMEOUT_S <= 2.0async def test_play_keeps_polling_while_the_host_says_loading():diff --git a/tests/unit/realtime/test_native_tool_deadline.py b/tests/unit/realtime/test_native_tool_deadline.pyindex 7b11548d0b..10b6bb735f 100644--- a/tests/unit/realtime/test_native_tool_deadline.py+++ b/tests/unit/realtime/test_native_tool_deadline.py@@ -14,6 +14,7 @@ its result arrives (ADR-0035 §3) and nothing bounded that wait. Pinned here:* a tool that answers within the deadline is untouched — same result, nopending flag, counted as executed."""+from __future__ import annotationsimport asyncio@@ -198,7 +199,16 @@ async def test_a_tool_within_the_deadline_is_untouched(assert session._native_tool_failures == 0-def test_the_deadline_leaves_room_for_the_slowest_honest_tool() -> None:- """YouTube Music's cold-start confirm is ~9 s by design plus a window show;- the ceiling must sit above it, and well below the turn-stall watchdog."""- assert 12.0 <= session_module._NATIVE_TOOL_DEADLINE_S < session_module._TURN_STALL_TIMEOUT_S+def test_the_deadline_is_the_shared_voice_tool_budget() -> None:+ """One number, read from one place: the session's ceiling IS the voice tool+ budget every plugin sizes its waits under (maintainer 2026-08-22: five+ seconds for everything a tool does, not one plugin). It sits after the+ instant ack and well before the turn-stall watchdog."""+ from jarvis.core.tool_budget import VOICE_TOOL_BUDGET_S++ assert session_module._NATIVE_TOOL_DEADLINE_S == VOICE_TOOL_BUDGET_S == 5.0+ assert (+ session_module._INSTANT_ACK_GRACE_S+ < session_module._NATIVE_TOOL_DEADLINE_S+ < session_module._TURN_STALL_TIMEOUT_S+ )