Skip to content

The agent that grows with you

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.py
index 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 False
chat_id = event.source.chat_id
voice_mode = self._voice_mode.get(self._voice_key_for_source(event.source))
is_voice_input = event.message_type == MessageType.VOICE
diff --git a/gateway/session_commands.py b/gateway/session_commands.py
index 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_COMMANDS
or name in _SETTING_COMMANDS or name in _APPROVAL_COMMANDS
or _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.py
index 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.py
new file mode 100644
index 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.py
index 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 sys
sys.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.tsx
index 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 ki
const 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.ts
index 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; /s
expect(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.ts
index 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.md
index 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.md
index 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.