tts_command_provider.py 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374
  1. """Shared runner for user-configured shell ("command") TTS/STT providers.
  2. ``tts.providers.<name>: {type: command, command: "piper -f {output_path} < {input_path}"}``
  3. (and the ``stt.`` twin): ``{placeholders}`` are shell-quoted for their surrounding quote
  4. context, ``{{``/``}}`` stay literal. Owns the quote-aware rendering, the idle-timeout
  5. process runner and the generic ``<section>.providers.<name>`` readers, re-imported by
  6. ``tts_tool``/``transcription_tools`` under their historical private names. TTS placeholders:
  7. ``{input_path}``/``{text_path}``, ``{output_path}``, ``{format}``, ``{voice}``, ``{model}``,
  8. ``{speed}``. Built-in provider names always win over a same-named ``providers`` entry.
  9. """
  10. from __future__ import annotations
  11. import os
  12. import queue
  13. import re
  14. import shlex
  15. import subprocess
  16. import tempfile
  17. import threading
  18. import time
  19. from functools import partial
  20. from pathlib import Path
  21. from typing import Any, Dict, FrozenSet, Optional
  22. from hermes_cli.process_identity import release_process_group_once_empty, spawn_owned
  23. from utils import is_truthy_value
  24. def shell_quote_context(command_template: str, position: int) -> Optional[str]:
  25. """Return the shell quote char (``'``/``"``) active right before *position*, or None."""
  26. quote: Optional[str] = None
  27. escaped = False
  28. i = 0
  29. while i < position:
  30. char = command_template[i]
  31. if quote == "'":
  32. if char == "'":
  33. quote = None
  34. elif quote == '"':
  35. if escaped:
  36. escaped = False
  37. elif char == "\\":
  38. escaped = True
  39. elif char == '"':
  40. quote = None
  41. elif char in ("'", '"'):
  42. quote = char
  43. elif char == "\\":
  44. i += 1
  45. i += 1
  46. return quote
  47. def quote_command_placeholder(value: str, quote_context: Optional[str]) -> str:
  48. """Quote a placeholder value for its position in a shell command template."""
  49. if quote_context == "'":
  50. return value.replace("'", r"'\''")
  51. if quote_context == '"':
  52. return value.replace("\\", "\\\\").replace('"', r'\"').replace("$", r"\$").replace("`", r"\`")
  53. return subprocess.list2cmdline([value]) if os.name == "nt" else shlex.quote(value)
  54. def render_command_template(command_template: str, placeholders: dict[str, str]) -> str:
  55. """Replace ``{name}`` placeholders (quote-aware) while preserving ``{{``/``}}``."""
  56. names = "|".join(re.escape(name) for name in placeholders)
  57. pattern = re.compile(rf"(?<!\$)(?:\{{\{{(?P<double>{names})\}}\}}|\{{(?P<single>{names})\}})")
  58. replacements: list[tuple[str, str]] = []
  59. def replace_match(match: re.Match[str]) -> str:
  60. name = match.group("double") or match.group("single")
  61. token = f"__HERMES_CMD_PLACEHOLDER_{len(replacements)}__"
  62. quoted = quote_command_placeholder(placeholders[name], shell_quote_context(command_template, match.start()))
  63. replacements.append((token, quoted))
  64. return token
  65. rendered = pattern.sub(replace_match, command_template).replace("{{", "{").replace("}}", "}")
  66. for token, value in replacements:
  67. rendered = rendered.replace(token, value)
  68. return rendered
  69. def _signal_process_tree(psutil: Any, proc: subprocess.Popen, method: str) -> None:
  70. """Apply ``terminate``/``kill`` to *proc* and all descendants (best effort)."""
  71. try:
  72. parent = psutil.Process(proc.pid)
  73. for child in parent.children(recursive=True):
  74. try:
  75. getattr(child, method)()
  76. except psutil.NoSuchProcess:
  77. pass
  78. getattr(parent, method)()
  79. except psutil.NoSuchProcess:
  80. return
  81. except Exception:
  82. getattr(proc, method)()
  83. def terminate_command_process_tree(proc: subprocess.Popen) -> None:
  84. """Best-effort termination of a shell process and all of its children."""
  85. if proc.poll() is not None:
  86. return
  87. if os.name == "nt":
  88. try:
  89. # CREATE_NO_WINDOW: taskkill is a console-subprocess — the kill itself must not
  90. # flash a window on windowless hosts, same class of defect as the spawn above.
  91. from hermes_cli._subprocess_compat import windows_hide_flags
  92. subprocess.run(["taskkill", "/F", "/T", "/PID", str(proc.pid)], stdout=subprocess.DEVNULL,
  93. stderr=subprocess.DEVNULL, timeout=5, stdin=subprocess.DEVNULL,
  94. creationflags=windows_hide_flags(), check=False)
  95. except Exception:
  96. proc.kill()
  97. return
  98. try:
  99. import psutil # type: ignore
  100. except ImportError:
  101. psutil = None
  102. # Without psutil only the shell itself is signalled (children may survive).
  103. signal = ((lambda m: getattr(proc, m)()) if psutil is None
  104. else (lambda m: _signal_process_tree(psutil, proc, m)))
  105. signal("terminate")
  106. try:
  107. proc.wait(timeout=2)
  108. except subprocess.TimeoutExpired:
  109. signal("kill")
  110. def command_env_passthrough(config: dict[str, Any]) -> list:
  111. """``env_passthrough`` allowlist: parent env vars copied back into the secret-scrubbed child env."""
  112. raw = config.get("env_passthrough")
  113. return [str(x).strip() for x in raw if str(x).strip()] if isinstance(raw, (list, tuple)) else []
  114. def command_failure_detail(exc: subprocess.CalledProcessError) -> str:
  115. """``stderr: ...; stdout: ...`` for a failed command provider, or ``no command output``."""
  116. parts = [f"{stream}: {text.strip()}" for stream, text in (("stderr", exc.stderr), ("stdout", exc.stdout)) if text]
  117. return "; ".join(parts) or "no command output"
  118. def provider_popen_group_kwargs(os_name: str) -> dict[str, Any]:
  119. """Process-group spawn kwargs for a command-provider child, per platform.
  120. On Windows the shell=True spawn routes through cmd.exe, a console-subsystem
  121. shim: with only CREATE_NEW_PROCESS_GROUP it allocates a *visible* console
  122. window flash on every provider run from a windowless host (pythonw gateway,
  123. TUI, Desktop). The shared detach bundle (hermes_cli._subprocess_compat.
  124. windows_detach_flags_without_breakaway) adds CREATE_NO_WINDOW so the child
  125. owns a hidden console its descendants inherit instead — deliberately without
  126. CREATE_BREAKAWAY_FROM_JOB: this child is foreground-owned and killed by us on
  127. idle timeout, so job teardown propagation must keep working. POSIX: the child
  128. leads its own group (``spawn_owned``) so the tree can be signalled on idle
  129. timeout, and the group dies with this process: the idle timer lives here, so
  130. a stalled command used to outlive a SIGKILLed Hermes forever.
  131. """
  132. from hermes_cli._subprocess_compat import windows_detach_flags_without_breakaway
  133. if os_name == "nt":
  134. return {"creationflags": windows_detach_flags_without_breakaway()}
  135. return {}
  136. def run_command_provider(
  137. command: str, timeout: float, env_passthrough: Optional[list] = None,
  138. ) -> subprocess.CompletedProcess:
  139. """Run a command-provider shell command with process-tree idle cleanup.
  140. ``timeout`` is an IDLE timeout, reset whenever the command emits output — a slow-but-alive
  141. provider survives, a silently stalled one is killed. Child env is scrubbed of Hermes secrets
  142. while propagating delegated-child lineage markers."""
  143. from agent.delegation_context import delegated_child_subprocess_env
  144. from tools.env_passthrough import resolve_passthrough_value
  145. from tools.environments.local import hermes_subprocess_env
  146. scrubbed = hermes_subprocess_env(inherit_credentials=False)
  147. for key in env_passthrough or []:
  148. # Under the multiplexer os.environ is the LAUNCH profile's .env: resolve through the served
  149. # profile's secret scope so its own key is forwarded and never another profile's.
  150. value = resolve_passthrough_value(key, os.environ.get(key))
  151. if value is not None:
  152. scrubbed[key] = value
  153. # Own process group so the whole tree can be signalled on idle timeout; on Windows the
  154. # shared bundle also hides the console (shell=True spawns via cmd.exe, which otherwise
  155. # flashes a window on windowless hosts). Lossy UTF-8 decode: locale-mismatched bytes
  156. # must not raise in the reader threads.
  157. group = provider_popen_group_kwargs(os.name)
  158. proc = spawn_owned(command, purpose="tts-command", shell=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
  159. text=True, encoding="utf-8", errors="replace", env=delegated_child_subprocess_env(scrubbed),
  160. stdin=subprocess.DEVNULL, **group)
  161. output_queue: queue.Queue[tuple[str, Optional[str]]] = queue.Queue()
  162. chunks: dict[str, list[str]] = {"stdout": [], "stderr": []}
  163. open_streams = {"stdout", "stderr"}
  164. def read_stream(name: str, stream: Any) -> None:
  165. encoding = getattr(stream, "encoding", None) or "utf-8"
  166. read1 = getattr(getattr(stream, "buffer", None), "read1", None)
  167. try:
  168. while True:
  169. chunk = stream.read(65536) if read1 is None else read1(65536).decode(encoding, errors="replace")
  170. if not chunk:
  171. break
  172. output_queue.put((name, chunk))
  173. finally:
  174. output_queue.put((name, None))
  175. readers = [threading.Thread(target=read_stream, args=(name, stream), daemon=True)
  176. for name, stream in (("stdout", proc.stdout), ("stderr", proc.stderr))]
  177. for reader in readers:
  178. reader.start()
  179. deadline = time.monotonic() + timeout
  180. timed_out = False
  181. while open_streams:
  182. remaining = deadline - time.monotonic()
  183. if remaining <= 0:
  184. timed_out = True
  185. break
  186. try:
  187. name, chunk = output_queue.get(timeout=min(0.05, remaining))
  188. except queue.Empty:
  189. continue
  190. if chunk is None:
  191. open_streams.discard(name)
  192. continue
  193. chunks[name].append(chunk)
  194. deadline = time.monotonic() + timeout
  195. if not timed_out:
  196. try:
  197. proc.wait(timeout=max(0.0, deadline - time.monotonic()))
  198. except subprocess.TimeoutExpired:
  199. timed_out = True
  200. if timed_out:
  201. terminate_command_process_tree(proc)
  202. for reader in readers:
  203. reader.join(timeout=0.5)
  204. while not output_queue.empty():
  205. name, chunk = output_queue.get_nowait()
  206. if chunk:
  207. chunks[name].append(chunk)
  208. if proc.poll() is not None:
  209. release_process_group_once_empty(proc.pid, proc=proc) # a tree we failed to stop stays covered
  210. stdout, stderr = "".join(chunks["stdout"]), "".join(chunks["stderr"])
  211. if timed_out:
  212. raise subprocess.TimeoutExpired(command, timeout, output=stdout, stderr=stderr) from (
  213. subprocess.TimeoutExpired(command, timeout))
  214. if proc.returncode:
  215. raise subprocess.CalledProcessError(proc.returncode, command, output=stdout, stderr=stderr)
  216. return subprocess.CompletedProcess(command, proc.returncode, stdout, stderr)
  217. # ---- Generic ``<section>.providers.<name>`` config layer (TTS and STT share it) ----
  218. def _get_provider_section(config: dict[str, Any], name: str) -> dict[str, Any]:
  219. """Return ``config[name]`` if it's a dict, else an empty dict."""
  220. section = config.get(name) if isinstance(config, dict) else None
  221. return section if isinstance(section, dict) else {}
  222. def _named_provider_config(config: dict[str, Any], name: str, builtins: frozenset[str]) -> dict[str, Any]:
  223. """``<section>.providers.<name>`` (canonical), else ``<section>.<name>`` for non-built-in names
  224. only — refused for built-ins so a user's ``openai:`` block still means OpenAI, not a command."""
  225. section = _get_provider_section(config, "providers").get(name)
  226. if isinstance(section, dict):
  227. return section
  228. return _get_provider_section(config, name) if name.lower() not in builtins else {}
  229. def _is_command_provider_config(config: dict[str, Any]) -> bool:
  230. """True when *config* declares a command-type provider (has a non-empty ``command``)."""
  231. if not isinstance(config, dict):
  232. return False
  233. ptype = str(config.get("type") or "").strip().lower()
  234. command = config.get("command")
  235. return ptype in ("", "command") and isinstance(command, str) and bool(command.strip())
  236. def _resolve_command_config(
  237. provider: str, config: dict[str, Any], reserved: frozenset[str]) -> Optional[dict[str, Any]]:
  238. """Config of a user-declared command provider; None for *reserved* names, unknown or non-command."""
  239. key = (provider or "").lower().strip()
  240. if not key or key in reserved:
  241. return None
  242. named = _named_provider_config(config, key, reserved)
  243. return named if _is_command_provider_config(named) else None
  244. def _command_timeout(config: dict[str, Any], default: float) -> float:
  245. """Timeout in seconds (``timeout`` > ``timeout_seconds``); invalid or non-positive -> *default*."""
  246. raw = config.get("timeout", config.get("timeout_seconds", default))
  247. try:
  248. value = float(raw)
  249. except (TypeError, ValueError):
  250. return float(default)
  251. return value if value > 0 else float(default)
  252. def _command_output_format(config: dict[str, Any], formats: frozenset[str], default: str) -> str:
  253. """Validated ``format``/``output_format`` from *config*, else *default*."""
  254. raw = config.get("format") or config.get("output_format") or default
  255. fmt = str(raw).lower().strip().lstrip(".")
  256. return fmt if fmt in formats else default
  257. # ---- TTS ``tts.providers.<name>`` layer -----------------------------------
  258. # Any ``tts.provider`` value NOT in this set refers to ``tts.providers.<name>``.
  259. BUILTIN_TTS_PROVIDERS = frozenset({
  260. "edge", "elevenlabs", "openai", "minimax", "xai", "mistral", "gemini",
  261. "neutts", "kittentts", "piper", "deepinfra"})
  262. DEFAULT_COMMAND_TTS_TIMEOUT_SECONDS = 120
  263. DEFAULT_COMMAND_TTS_OUTPUT_FORMAT = "mp3"
  264. COMMAND_TTS_OUTPUT_FORMATS = frozenset({"mp3", "wav", "ogg", "flac", "m4a", "aac", "amr", "opus"})
  265. DEFAULT_COMMAND_TTS_MAX_TEXT_LENGTH = 5000
  266. _get_named_provider_config = partial(_named_provider_config, builtins=BUILTIN_TTS_PROVIDERS)
  267. _resolve_command_provider_config = partial(_resolve_command_config, reserved=BUILTIN_TTS_PROVIDERS)
  268. _get_command_tts_timeout = partial(_command_timeout, default=DEFAULT_COMMAND_TTS_TIMEOUT_SECONDS)
  269. def _iter_command_providers(tts_config: dict[str, Any]):
  270. """Yield (name, config) pairs for every declared command-type provider."""
  271. for name, cfg in _get_provider_section(tts_config, "providers").items():
  272. if isinstance(name, str) and name.lower() not in BUILTIN_TTS_PROVIDERS and _is_command_provider_config(cfg):
  273. yield name, cfg
  274. def _get_command_tts_output_format(config: dict[str, Any], output_path: Optional[str] = None) -> str:
  275. """Validated output format: the output path's suffix wins, then ``format``/``output_format``."""
  276. suffix = Path(output_path).suffix.lower().strip().lstrip(".") if output_path else ""
  277. if suffix in COMMAND_TTS_OUTPUT_FORMATS:
  278. return suffix
  279. return _command_output_format(config, COMMAND_TTS_OUTPUT_FORMATS, DEFAULT_COMMAND_TTS_OUTPUT_FORMAT)
  280. def _is_command_tts_voice_compatible(config: dict[str, Any]) -> bool:
  281. """True only when the user explicitly opted in to voice delivery."""
  282. return is_truthy_value(config.get("voice_compatible", False))
  283. def _configured_command_tts_output_path(path: Path, config: dict[str, Any]) -> Path:
  284. """Return an output path whose extension matches the provider's output_format."""
  285. return path.with_suffix(f".{_get_command_tts_output_format(config)}")
  286. def _generate_command_tts(
  287. text: str, output_path: str, provider_name: str, config: dict[str, Any], tts_config: dict[str, Any],
  288. ) -> str:
  289. """Generate speech by running a user-configured shell command; returns the audio path it wrote.
  290. Raises ``ValueError`` for bad provider config, ``RuntimeError`` for timeouts / bad exits / no output."""
  291. command_template = str(config.get("command") or "").strip()
  292. if not command_template:
  293. raise ValueError(f"tts.providers.{provider_name}.command is not configured")
  294. output = Path(output_path).expanduser()
  295. output.parent.mkdir(parents=True, exist_ok=True)
  296. if output.exists():
  297. output.unlink()
  298. timeout = _get_command_tts_timeout(config)
  299. with tempfile.TemporaryDirectory() as tmpdir:
  300. text_path = Path(tmpdir) / "input.txt"
  301. text_path.write_text(text, encoding="utf-8")
  302. placeholders = {
  303. "input_path": str(text_path), "text_path": str(text_path), "output_path": str(output),
  304. "format": _get_command_tts_output_format(config, str(output)),
  305. "voice": str(config.get("voice", "")), "model": str(config.get("model", "")),
  306. "speed": str(config.get("speed", tts_config.get("speed", ""))),
  307. }
  308. command = render_command_template(command_template, placeholders)
  309. try:
  310. run_command_provider(command, timeout, env_passthrough=command_env_passthrough(config))
  311. except subprocess.TimeoutExpired as exc:
  312. raise RuntimeError(f"TTS provider '{provider_name}' timed out after {timeout:g}s") from exc
  313. except subprocess.CalledProcessError as exc:
  314. raise RuntimeError(
  315. f"TTS provider '{provider_name}' exited with code {exc.returncode}: {command_failure_detail(exc)}"
  316. ) from exc
  317. if not output.exists() or output.stat().st_size <= 0:
  318. raise RuntimeError(f"TTS provider '{provider_name}' produced no output at {output}")
  319. return str(output)