Skip to content

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.

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.py
new file mode 100644
index 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_S
diff --git a/jarvis/plugins/tool/_http_pool.py b/jarvis/plugins/tool/_http_pool.py
index 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_S
self._timeout_s = timeout_s
self._transport = transport
self._client: Any | None = None
diff --git a/jarvis/plugins/tool/youtube_music_rest.py b/jarvis/plugins/tool/youtube_music_rest.py
index 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-effort
log.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 out
diff --git a/jarvis/realtime/session.py b/jarvis/realtime/session.py
index 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, BrainMessage
from jarvis.core.redact import safe_preview
+from jarvis.core.tool_budget import VOICE_TOOL_BUDGET_S
from 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 it
diff --git a/tests/unit/plugins/tool/test_youtube_music_rest.py b/tests/unit/plugins/tool/test_youtube_music_rest.py
index 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 runs
on 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 _time
class SlowPlayer(FakePlayer):
@@ -592,8 +594,31 @@ async def test_play_confirm_is_bounded_by_wall_clock_when_the_player_is_slow():
elapsed = _time.monotonic() - started
assert 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.0
async 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.py
index 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, no
pending flag, counted as executed.
"""
+
from __future__ import annotations
import 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
+ )