The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
fix(gateway): refuse local /voice tts the owner cannot play
David Dudok de Wit49b97b5e5de3
diff --git a/gateway/run_voice.py b/gateway/run_voice.pyindex f16cbdcb1df..447dc431b42 100644--- a/gateway/run_voice.py+++ b/gateway/run_voice.py@@ -383,6 +383,10 @@ class GatewayVoiceMixin:# agent already produced (#90103). Keep /voice scoped to human platforms.if getattr(event.source.platform, "value", None) == "a2a":return False+ # A local session's speech plays in its own client: LocalSessionAdapter has no audio delivery,+ # so an owner-side synthesis would be a paid provider call nobody hears.+ if event.source.platform == Platform.LOCAL:+ return Falsechat_id = event.source.chat_idvoice_mode = self._voice_mode.get(self._voice_key_for_source(event.source))is_voice_input = event.message_type == MessageType.VOICEdiff --git a/gateway/session_commands.py b/gateway/session_commands.pyindex 0eeeb89ce41..729d9931869 100644--- a/gateway/session_commands.py+++ b/gateway/session_commands.py@@ -93,8 +93,18 @@ _CONTROL_ARGUMENTS = {}+# The setting forms a local session cannot deliver: `/voice tts` asks the owner to voice every reply,+# and a local session's audio plays only in its client. Read like the handler reads it (no shlex): an+# unbalanced quote in any other `/voice` argument still reaches the handler.+_REFUSED_ARGUMENTS = {+ 'voice': lambda arg: arg.strip().lower() == 'tts',+}++def command_verdict(name, arg=''):"""``read`` / ``control`` / ``refused`` for a canonical registry command on a local session."""+ if _REFUSED_ARGUMENTS.get(name, lambda _a: False)(arg):+ return 'refused'if (name in _CONTROL_COMMANDS or name in _HANDLER_CONTROLS or name in _PROMPT_COMMANDSor name in _SETTING_COMMANDS or name in _APPROVAL_COMMANDSor _CONTROL_ARGUMENTS.get(name, lambda _a: False)(arg)):diff --git a/tests/gateway/test_auto_voice_reply_format.py b/tests/gateway/test_auto_voice_reply_format.pyindex 3c9476118b8..101c55b224d 100644--- a/tests/gateway/test_auto_voice_reply_format.py+++ b/tests/gateway/test_auto_voice_reply_format.py@@ -119,6 +119,36 @@ class TestAutoVoiceReplyFormat:assert runner._should_send_voice_reply(telegram, "hello", []) is True+ def test_should_send_voice_reply_local_session_never_synthesizes(self):+ """A local session cannot play owner audio. A saved mode ``all`` (``/voice tts``)+ must not start a provider call."""+ runner = _make_runner()+ local_adapter = _make_adapter(Platform.LOCAL)+ local_adapter._should_auto_tts_for_chat = MagicMock(return_value=True)+ runner.adapters[Platform.LOCAL] = local_adapter+ local = _make_event(Platform.LOCAL, chat_id="sess")+ runner._voice_mode[runner._voice_key_for_source(local.source)] = "all"++ assert runner._should_send_voice_reply(local, "the reply", []) is False++ telegram_adapter = _make_adapter(Platform.TELEGRAM)+ runner.adapters[Platform.TELEGRAM] = telegram_adapter+ telegram = _make_event(Platform.TELEGRAM, chat_id="999")+ runner._voice_mode[runner._voice_key_for_source(telegram.source)] = "all"+ assert runner._should_send_voice_reply(telegram, "hello", []) is True++ def test_should_send_voice_reply_local_session_ignores_global_auto_tts(self):+ """With no ``/voice`` mode, global ``voice.auto_tts`` (Desktop "Read replies aloud",+ which the desktop speaks itself) must not make the owner synthesize a local reply."""+ runner = _make_runner()+ local_adapter = _make_adapter(Platform.LOCAL)+ local_adapter._should_auto_tts_for_chat = MagicMock(return_value=True)+ runner.adapters[Platform.LOCAL] = local_adapter+ local = _make_event(Platform.LOCAL, chat_id="sess")+ assert runner._voice_key_for_source(local.source) not in runner._voice_mode++ assert runner._should_send_voice_reply(local, "the reply", []) is False+def test_sync_voice_mode_state_never_inherits_global_auto_tts_for_a2a(self):"""The adapter-side default must match the runner-side skip (#90103).diff --git a/tests/gateway/test_local_session_voice_tts.py b/tests/gateway/test_local_session_voice_tts.pynew file mode 100644index 00000000000..d2334c107d6--- /dev/null+++ b/tests/gateway/test_local_session_voice_tts.py@@ -0,0 +1,115 @@+"""A local session's ``/voice tts`` must not make the owner synthesize audio.++Ink sends ``slash.exec`` ``voice tts``. The messaging handler sets that chat's+voice mode to ``all`` and every later reply is synthesized, then handed to+``LocalSessionAdapter``. It inherits the base ``send_voice``, which only posts+a media-fallback notice through the adapter's no-op ``send``, so the audio is+dropped. Nothing plays, the provider is still billed, and Ink's ``/voice off``+does not clear the owner's mode.++The gateway daemon is real (``python -m gateway.run``). The model and the TTS+endpoint are one loopback HTTP server that records every request path.+"""+import asyncio+import json+import signal+import threading+import time+from http.server import ThreadingHTTPServer+from pathlib import Path++from tests.gateway.fixtures.local_recovery_probe import Model, child_env, daemon, rpc, websocket+++class RecordingModel(Model):+ def do_POST(self):+ self.server.paths.append(self.path)+ if self.path.endswith('/audio/speech'):+ self.rfile.read(int(self.headers['Content-Length']))+ payload = b'ID3' + b'\0' * 512+ self.send_response(200)+ self.send_header('Content-Type', 'audio/mpeg')+ self.send_header('Content-Length', str(len(payload)))+ self.end_headers()+ self.wfile.write(payload)+ return+ return super().do_POST()+++def test_local_voice_tts_is_refused_and_other_voice_forms_stay():+ """``/voice tts`` is a named refusal. ``/voice on|off|status`` stay controls."""+ from gateway.session_commands import command_verdict++ assert command_verdict('voice', 'tts') == 'refused'+ assert command_verdict('voice', ' TTS ') == 'refused'+ for arg in ('', 'on', 'off', 'status', 'channel', 'join', 'leave'):+ assert command_verdict('voice', arg) == 'control', arg+++def test_local_voice_refusal_reads_the_argument_as_the_handler_does():+ """Only the argument the handler stores as mode ``all`` is refused. Any other text, an+ unbalanced quote included, still reaches the handler instead of failing the request."""+ from gateway.session_commands import command_verdict++ for arg in ("it's", '"tts', 'tts now'):+ assert command_verdict('voice', arg) == 'control', arg+++def test_local_session_voice_tts_never_synthesizes_unplayable_audio(tmp_path):+ root = Path(__file__).resolve().parents[2]+ home, user, work = tmp_path / 'state', tmp_path / 'user', tmp_path / 'work'+ home.mkdir(mode=0o700)+ user.mkdir()+ work.mkdir()+ peer = ThreadingHTTPServer(('127.0.0.1', 0), RecordingModel)+ peer.requests, peer.paths = [], []+ peer.blocked, peer.release = threading.Event(), threading.Event()+ thread = threading.Thread(target=peer.serve_forever, daemon=True)+ thread.start()+ url = f'http://127.0.0.1:{peer.server_port}/v1'+ (home / 'config.yaml').write_text(json.dumps({+ 'gateway': {'multiplex_profiles': False},+ 'model': {'provider': 'custom', 'default': 'voice-model', 'base_url': url},+ 'auxiliary': {'title_generation': {'enabled': False}},+ 'tts': {'provider': 'openai', 'openai': {'base_url': url, 'api_key': 'loopback-only'}},+ }))+ env = child_env()+ env.update(HOME=str(user), USERPROFILE=str(user), HERMES_HOME=str(home), PYTHONPATH=str(root),+ OPENAI_API_KEY='loopback-only', OPENAI_BASE_URL=url, PYTHONUNBUFFERED='1')+ out = {}++ async def probe(desc):+ async with websocket(home, desc) as ws:+ created = await rpc(ws, 'session.create', request_id='voice', source='tui', toolsets=[], cwd=str(work))+ sid = created['result']['session_id']+ out['first'] = await rpc(ws, 'slash.exec', session_id=sid, command='voice tts')+ await rpc(ws, 'prompt.submit', session_id=sid, input_id='hello', text='HELLO')+ deadline = time.monotonic() + 45+ snap = None+ while time.monotonic() < deadline:+ snap = (await rpc(ws, 'session.resume', session_id=sid))['result']+ if (not snap['running'] and not snap['pending']+ and 'RECOVERY_ACK_HELLO' in json.dumps(snap['messages'])):+ break+ await asyncio.sleep(0.1)+ else:+ raise AssertionError(snap)+ # Voice synthesis is awaited before the turn settles, so the paths are final here.+ out['paths_after_turn'] = list(peer.paths)+ out['second'] = await rpc(ws, 'slash.exec', session_id=sid, command='voice tts')+ try:+ with daemon(root, home, env, barrier=False) as (proc, desc):+ asyncio.run(probe(desc))+ proc.send_signal(signal.SIGINT)+ proc.wait(timeout=20)+ finally:+ peer.shutdown()+ peer.server_close()+ thread.join(timeout=5)+ speech = [p for p in out['paths_after_turn'] if p.endswith('/audio/speech')]+ # No client of a local session can play an owner-side voice reply.+ assert not speech, ('owner synthesized TTS for a TUI session reply that nothing plays', out)+ # The owner names the refusal instead of acknowledging a mode it cannot deliver.+ for reply in (out['first'], out['second']):+ assert reply.get('error', {}).get('message') == 'unsupported_command', (+ '/voice tts claims a voice mode nothing delivers', out)diff --git a/tests/hermes_cli/test_gateway_command_parity_live_session.py b/tests/hermes_cli/test_gateway_command_parity_live_session.pyindex 1675392891e..601365962fb 100644--- a/tests/hermes_cli/test_gateway_command_parity_live_session.py+++ b/tests/hermes_cli/test_gateway_command_parity_live_session.py@@ -21,8 +21,7 @@ def test_sidecar_live_session_rpc_is_reported_broken_on_the_shared_gateway():def test_a_refused_subcommand_keeps_the_rest_of_the_command_routed():- """``/voice tts`` runs the owner's ``/voice`` handler (the session's voice state) and Ink no- longer names it refused, so the cell is the canonical route rather than a sidecar row."""+ """``/voice tts`` refuses on the shared gateway; ``/voice on|off|status`` still reach voice.toggle."""import syssys.path.insert(0, str(ROOT))from hermes_cli.commands import COMMAND_REGISTRY@@ -32,4 +31,4 @@ def test_a_refused_subcommand_keeps_the_rest_of_the_command_routed():spec.loader.exec_module(gen)cmd = next(c for c in COMMAND_REGISTRY if c.name == "voice")cell = gen.ink_cell(cmd, gen.gateway_cell("voice"), gen._ink_commands(), gen._served_methods())- assert cell == "canonical route"+ assert cell == "sidecar: voice.toggle; `tts` refused"diff --git a/ui-tui/src/__tests__/canonicalSidecarSessionVerbs.test.tsx b/ui-tui/src/__tests__/canonicalSidecarSessionVerbs.test.tsxindex c79166f25e5..0ac043562d6 100644--- a/ui-tui/src/__tests__/canonicalSidecarSessionVerbs.test.tsx+++ b/ui-tui/src/__tests__/canonicalSidecarSessionVerbs.test.tsx@@ -72,7 +72,7 @@ async function overlayKey(gw: GatewayClient, key: string, expected = '/agents kiconst SITES: [string, () => Promise<void>][] = [[- 'session.ts::/voice tts (the owner\'s /voice handler holds the session state)',+ 'session.ts::/voice tts (read-aloud runs only in a sidecar turn)',async () => {patchUiState({ sid: 'owner' })const { gw, request } = owner()@@ -87,9 +87,7 @@ const SITES: [string, () => Promise<void>][] = [voice: { setVoiceEnabled: vi.fn(), setVoiceRecordKey: vi.fn(), setVoiceTts: vi.fn() }} as never)('/voice tts')await new Promise(resolve => setImmediate(resolve))- // The session's voice state is the owner's: `/voice tts` runs its `/voice` handler, never the- // sidecar's voice.toggle.- expect(request).toHaveBeenCalledWith('slash.exec', { command: 'voice tts', session_id: 'owner' })+ expect(sys).toHaveBeenCalledWith('/voice tts is not available on the shared gateway yet')expect(request.mock.calls.some(([method]) => method === 'voice.toggle')).toBe(false)}],diff --git a/ui-tui/src/__tests__/canonicalSlashCommands.test.ts b/ui-tui/src/__tests__/canonicalSlashCommands.test.tsindex 6a6a7e2aa05..1b7e6145c9c 100644--- a/ui-tui/src/__tests__/canonicalSlashCommands.test.ts+++ b/ui-tui/src/__tests__/canonicalSlashCommands.test.ts@@ -81,10 +81,6 @@ function harness() {return { type: 'exec', output: 'π **Available Personalities**' }}- if (method === 'slash.exec' && params.command === 'voice tts') {- return { type: 'exec', output: 'Auto-TTS enabled.' }- }-throw new Error(`unknown_method: ${method}`)})@@ -265,14 +261,16 @@ it('/reasoning --global is the owner\'s /reasoning handler behind config.set; /sexpect(notices.some(line => /skin: default/.test(line))).toBe(true)})-it('/voice tts sets the session\'s voice state through the owner\'s /voice handler', async () => {+it('/voice tts refuses by name: the owner never speaks a TUI reply', async () => {const { request, slash, sys } = harness()slash('/voice tts')await flush()- expect(request).toHaveBeenCalledWith('slash.exec', { command: 'voice tts', session_id: 'owner' })- expect(sys.mock.calls.map(([text]) => String(text))).toEqual(['Auto-TTS enabled.'])+ expect(request.mock.calls.some(([method]) => method === 'slash.exec' || method === 'voice.toggle')).toBe(false)+ expect(sys.mock.calls.map(([text]) => String(text))).toEqual([+ '/voice tts is not available on the shared gateway yet'+ ])})it('bare /personality lists through the owner\'s /personality handler', async () => {diff --git a/ui-tui/src/app/slash/commands/session.ts b/ui-tui/src/app/slash/commands/session.tsindex d79649c4ec4..d197f203d3f 100644--- a/ui-tui/src/app/slash/commands/session.ts+++ b/ui-tui/src/app/slash/commands/session.ts@@ -394,13 +394,10 @@ export const sessionCommands: SlashCommand[] = [? normalized: 'status'- // `/voice tts` is the session's voice state, held by the owner's `/voice` handler (one behaviour- // on every surface); recording and playback stay in this terminal.+ // Read-aloud ran in the sidecar's own turn; a shared-gateway turn runs on the owner, which+ // never speaks a TUI reply, so the toggle would say "on" and stay silent.if (action === 'tts' && ctx.gateway.gw?.isCanonical) {- return ctx.gateway.gw- .request<SlashExecResponse>('slash.exec', { command: 'voice tts', session_id: ctx.sid })- .then(ctx.guarded<SlashExecResponse>(r => r.output && ctx.transcript.sys(r.output)))- .catch(ctx.guardedErr)+ return ctx.transcript.sys(t('canonical.controls.notAvailable', 'voice tts'))}ctx.gateway.rpc<VoiceToggleResponse>('voice.toggle', { action }).then(diff --git a/website/docs/developer-guide/gateway-command-parity.md b/website/docs/developer-guide/gateway-command-parity.mdindex 61766989284..59891960ca2 100644--- a/website/docs/developer-guide/gateway-command-parity.md+++ b/website/docs/developer-guide/gateway-command-parity.md@@ -128,7 +128,7 @@ handler does; `client-local (cli_only)` commands are terminal/UI features of a c| `/usage` | read (bare only (`reset` refused)) | HermesCLI._handle_usage_command | canonical route | slash.exec | slash.exec | || `/verbose` | control | HermesCLI._toggle_verbose | config.set | unavailable: terminal | slash.exec | per-session setting (gateway handler) || `/version` (/v) | read | HermesCLI._cmd_version | slash.exec | slash.exec | slash.exec | |-| `/voice` | control | HermesCLI._handle_voice_command | canonical route | unavailable: composer-voice | slash.exec | per-session setting (gateway handler) |+| `/voice` | control | HermesCLI._handle_voice_command | sidecar: voice.toggle; `tts` refused | unavailable: composer-voice | slash.exec | per-session setting (gateway handler) || `/wake` | refused | HermesCLI._handle_wake_command | local | action: wake | slash.exec: refused | client-local (cli_only) || `/whoami` | read | HermesCLI._handle_whoami_command | slash.exec | slash.exec | slash.exec | || `/worktree` | refused | HermesCLI._handle_worktree_command | slash.exec: refused | slash.exec: refused | slash.exec: refused | client-local (cli_only) |diff --git a/website/docs/user-guide/features/tts.md b/website/docs/user-guide/features/tts.mdindex 726667c83cf..3c62222592a 100644--- a/website/docs/user-guide/features/tts.md+++ b/website/docs/user-guide/features/tts.md@@ -277,7 +277,7 @@ tts:Local engines (Piper, KittenTTS) load their model lazily, so without help the *first* spoken reply after you turn speech on pays the whole model load β and on a fresh install the voice download β as silence before the first word. Hermes treats the speech-output toggles as the signal that TTS is about to be needed:- **Desktop** β **Read replies aloud** is a desktop-local preference, independent of the gateway's `voice.auto_tts` setting in Settings β Voice. It migrates the shared value once, then later gateway configuration changes do not override the desktop toggle. If local storage is full or unavailable, the choice still lasts for this window; persistence across a reload remains best-effort. Turning on **Read replies aloud**, or starting a **voice conversation**, pre-loads the configured engine in the background right away. Turning both off again unloads the resident model (a Piper voice is tens of MB; KittenTTS up to ~80MB) so it isn't parked in RAM for nothing.-- **CLI / TUI** β `/voice tts` (and `/voice on` when `voice.auto_tts` is set) do the same; `/voice off` releases.+- **CLI / TUI** β `/voice tts` (and `/voice on` when `voice.auto_tts` is set) do the same; `/voice off` releases. A TUI attached to the shared gateway refuses `/voice tts`, because the gateway cannot play speech in that terminal.Each toggle holds a *lease* on the engine; the model is only unloaded when the last lease across surfaces is released, so switching off read-aloud in one Desktop window never pulls the voice out from under a conversation running in another. The unload waits `tts.keep_warm_seconds` (default `60`) after the last release, and any toggle turning speech back on within that window keeps the loaded model, so a wake-word loop or a quickly restarted voice conversation doesn't reload the voice each time. Set it to `0` to unload immediately. For cloud providers there is no model to hold β the toggle only makes sure a lazily-installed SDK (edge-tts, ElevenLabs, Mistral) is present. Warm-up is best-effort: if the engine can't load, the toggle still succeeds and the first reply falls back to loading on demand as before.