Skip to content

The agent that grows with you

refactor(tui): the slash-worker client moves out of the server.py facade

kshitijk4poorf9e3df0960f1
diff --git a/tui_gateway/AGENTS.md b/tui_gateway/AGENTS.md
index 721bf5f1dac..28abec71428 100644
--- a/tui_gateway/AGENTS.md
+++ b/tui_gateway/AGENTS.md
@@ -89,7 +89,7 @@ profile's does not, and that `os.environ` is unchanged afterwards.
| Approvals | `prompts.tsx` | server→client request `approval` → response `{choice}` |
| Clarify / sudo / secret | `prompts.tsx`, `maskedPrompt.tsx` | server→client requests `clarify` / `sudo` / `secret` (`server_requests.py`) |
| Session picker | `sessionPicker.tsx` | `session.list` / `session.resume` |
-| Slash commands | local handler + fallthrough | `slash.exec` → `_SlashWorker`; `command.dispatch` |
+| Slash commands | local handler + fallthrough | `slash.exec` → `_SlashWorker` (`slash_worker_client.py`); `command.dispatch` |
| Completions | `useCompletion` hook | `complete.slash`, `complete.path` (under a non-local `terminal.backend`, `complete.path` lists the directory through the session's terminal backend — never the gateway host, whose same-named tree would look right and be wrong) |
| Theming | `theme.ts` + `branding.tsx` | `gateway.ready` carries skin data |
| Connection operations (desktop card) | desktop `store/connection-request.ts` | `connection.request` → `connection.update`* → `connection.respond {op_id}`; `connectors.operation.status`. The op lives in `tools/connectors/live.py`; the card never parks the tool thread (`methods_connectors.py`). |
diff --git a/tui_gateway/server.py b/tui_gateway/server.py
index bf75ea0811f..5976dc01d20 100644
--- a/tui_gateway/server.py
+++ b/tui_gateway/server.py
@@ -31,6 +31,7 @@ from hermes_constants import (
from hermes_cli import config_backend as _config_backend
from hermes_cli.config_backend import Changes, ConfigBackendUnavailable, config_exists, supports_file_tooling
from hermes_cli.env_loader import load_hermes_dotenv
+# The slash-worker client (slash_worker_client.py) runs on these globals; tests patch them here.
from hermes_cli.process_identity import release_process_group_once_empty, spawn_owned
from tui_gateway.pet_sheet import _clone_pet_payload, _pet_row_frame_counts, _pet_sheet_revision, _pet_state_rows
from utils import is_truthy_value
@@ -239,167 +240,6 @@ _stdio_transport = StdioTransport(lambda: _real_stdout, _stdout_lock)
_detached_ws_transport = _DropTransport()
-def _prepend_tool_paths(env: dict[str, str]) -> dict[str, str]:
- """Prepend managed bin (managed-first policy for the Browser Use CLI), venv bin and
- ~/.local/bin to PATH so slash_worker children resolve Hermes-managed CLIs under the Desktop's minimal PATH.
- The PM store dirs go in front of all of them: a user's node/uv in ~/.local/bin never wins."""
- managed_bin = ""
- with contextlib.suppress(Exception):
- managed_bin = str(Path(get_hermes_home()) / "bin")
- venv_bin = str(Path(sys.executable).parent) # <venv>/bin (POSIX) or <venv>/Scripts (Windows)
- parts = [p for p in (managed_bin, venv_bin, str(Path.home() / ".local" / "bin"), env.get("PATH") or "") if p]
- env["PATH"] = os.pathsep.join(parts)
- with contextlib.suppress(Exception):
- import pm
-
- env["PATH"] = pm.store_first_path(env["PATH"])
- return env
-
-
-class _SlashWorker:
- """Persistent HermesCLI subprocess for slash commands."""
-
- def __init__(self, session_key: str, model: str, profile_home: str | None = None,
- provider: str | None = None):
- self._lock = threading.Lock()
- self._seq = 0
- self.stderr_tail: list[str] = []
- self.stdout_queue: queue.Queue[dict | None] = queue.Queue()
- # ``--provider`` pins the child to the parent agent's virtual provider: without it the
- # worker re-resolves provider from config, so a MoA session (provider=moa, model=<preset>)
- # dispatched its preset NAME to the configured real provider and 402/503'd (#57283).
- argv = [sys.executable, "-P", "-m", "tui_gateway.slash_worker", "--session-key", session_key] \
- + (["--model", model] if model else []) \
- + (["--provider", provider] if provider else [])
- self._closed = False
- from hermes_cli._subprocess_compat import windows_hide_flags
- # slash_worker runs the Hermes agent → needs provider credentials. Tier-1 secrets
- # (gateway/GitHub/infra) are still stripped (#29157). Global-remote / multi-profile sessions: the
- # worker must resolve config/skills/state against the session's profile home, not the gateway's
- # launch HERMES_HOME (#40677).
- from tools.environments.local import served_profile_child_env
- from agent.secret_scope import is_multiplex_active
-
- # The worker runs the agent → needs provider credentials; tier-1 secrets (gateway/GitHub/
- # infra) are still stripped. A served profile's worker gets THAT profile's home + secrets and
- # none of the launch profile's .env / TERMINAL_* residue, exactly what a standalone
- # `hermes -p X` would load itself. The launch profile is a profile too: once the process hosts
- # a second home (multiplex flipped), its worker must name its own home or the fail-closed
- # no-target/no-scope path raises UnscopedSecretError (#115427).
- env = _prepend_tool_paths(served_profile_child_env(
- target_home=profile_home or (_hermes_home if is_multiplex_active() else None),
- inherit_credentials=True))
- # Internal slash workers must import the same checkout as their parent; -P keeps their cwd off sys.path.
- module_root = str(Path(__file__).resolve().parent.parent)
- env["PYTHONPATH"] = os.pathsep.join(
- part for part in (module_root, env.get("PYTHONPATH", "")) if part
- )
- # spawn_owned: the worker leads its own process group (otherwise it inherits the gateway's
- # pgid and mcp_tool's orphan sweep, racing the spawn, killpg()s the TUI parent itself), and
- # that group dies with this process however it dies: SIGKILL/OOM of the gateway used to leave
- # a quick command's shell, and anything else the worker started in its group, running forever.
- # errors="replace": bytes invalid in the system locale (GBK Windows) must not raise
- # UnicodeDecodeError in the drain threads.
- # Prepend the Hermes venv bin dir and the user-local bin dir to PATH so slash_worker child processes
- # can resolve Hermes-managed CLIs (browser-use, uvx) even when the parent gateway was launched with
- # a minimal PATH (e.g. by the Desktop/Dashboard app). See #83845.
- self.proc = spawn_owned(
- argv, purpose="slash-worker", stdin=subprocess.PIPE, stdout=subprocess.PIPE,
- stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", bufsize=1,
- cwd=os.getcwd(), env=env, creationflags=windows_hide_flags())
- threading.Thread(target=self._drain_stdout, daemon=True).start()
- threading.Thread(target=self._drain_stderr, daemon=True).start()
-
- def _drain_stdout(self):
- for line in self.proc.stdout or []:
- with contextlib.suppress(json.JSONDecodeError):
- self.stdout_queue.put(json.loads(line))
- self.stdout_queue.put(None)
-
- def _drain_stderr(self):
- for line in self.proc.stderr or []:
- if text := line.rstrip("\n"):
- self.stderr_tail = (self.stderr_tail + [text])[-80:]
-
- def run(self, command: str) -> str:
- """Run one command; return its output text.
-
- A command like /prompt may also have parked a next-turn prompt (a "seed")
- on the worker CLI; it rides back on the reply's ``seed`` field and is
- retrieved separately via ``pop_seed()``.
- """
- if self.proc.poll() is not None:
- raise RuntimeError("slash worker exited")
- with self._lock:
- self._seq += 1
- rid = self._seq
- self.proc.stdin.write(json.dumps({"id": rid, "command": command}) + "\n")
- self.proc.stdin.flush()
- while True:
- try:
- msg = self.stdout_queue.get(timeout=_SLASH_WORKER_TIMEOUT_S)
- except queue.Empty:
- raise RuntimeError("slash worker timed out")
- if msg is None:
- break
- if msg.get("id") != rid:
- continue
- if not msg.get("ok"):
- raise RuntimeError(msg.get("error", "slash worker failed"))
- self._last_seed = str(msg.get("seed", "") or "")
- return str(msg.get("output", "")).rstrip()
- raise RuntimeError(
- f"slash worker closed pipe{': ' + chr(10).join(self.stderr_tail[-8:]) if self.stderr_tail else ''}")
-
- def pop_seed(self) -> str:
- """Return and clear the seed from the last ``run()`` (empty when none)."""
- seed, self._last_seed = getattr(self, "_last_seed", ""), ""
- return seed
-
- def close(self):
- if getattr(self, "_closed", False):
- return
- self._closed = True
- proc = self.proc
- try:
- _stop_worker_group(proc)
- finally:
- for stream in (proc.stdin, proc.stdout, proc.stderr):
- with contextlib.suppress(Exception):
- stream.close()
-
-
-def _stop_worker_group(proc) -> None:
- """TERM the slash worker, give it 1 s, then KILL; never raises.
-
- POSIX signals the worker's whole process group (``spawn_owned`` made it the leader): signalling
- the leader alone left a running quick command's shell, or anything else the worker started in
- its group, alive after every session close. The group is released from the owner-death
- supervisor once it is empty; a group that is not stays covered.
- """
- if os.name != "posix":
- for stop in (proc.terminate, proc.kill):
- if proc.poll() is not None:
- return
- with contextlib.suppress(Exception):
- stop()
- proc.wait(timeout=1) # also reaps the zombie a kill leaves behind
- return
- pgid = proc.pid
- # Only a leader still alive on entry proves the number is still this worker's group. A worker
- # that already died leaves its group to the owner-death supervisor rather than risk signalling
- # a recycled pgid.
- if proc.poll() is None:
- for sig in (signal.SIGTERM, signal.SIGKILL):
- # Members that outlive the leader keep the group (and its number) alive.
- with contextlib.suppress(OSError):
- os.killpg(pgid, sig) # windows-footgun: ok — POSIX-only, Windows returned above
- with contextlib.suppress(Exception):
- proc.wait(timeout=1)
- # Killed members are reaped by init asynchronously; one still alive after that stays covered.
- release_process_group_once_empty(pgid, proc=proc)
-
-
def _display_cfg() -> dict:
"""``display`` section of the behavioral config, or ``{}`` when absent/malformed."""
display = _load_cfg().get("display")
@@ -2162,7 +2002,7 @@ from hermes_state import _BARE_BILLING_PROVIDERS
from . import (
session_registry as _session_registry, agent_factory as _agent_factory,
- methods_voice as _methods_voice, methods_browser as _methods_browser, methods_slash as _methods_slash,
+ slash_worker_client as _slash_worker_client, methods_voice as _methods_voice, methods_browser as _methods_browser, methods_slash as _methods_slash,
methods_complete_helpers as _methods_complete_helpers, session_auto_continue as _session_auto_continue,
plugin_inject as _plugin_inject,
rpc_dispatch as _rpc_dispatch,
@@ -2187,7 +2027,7 @@ from . import (
methods_shared_metrics as _methods_shared_metrics, methods_plugin_catalog as _methods_plugin_catalog)
for _m in (
- _session_registry, _agent_factory,
+ _session_registry, _agent_factory, _slash_worker_client,
_session_transports, _session_reaper, _session_lifecycle, _session_workdir, _compute_host_bridge, _model_switch,
_session_compression, _change_watcher, _tool_progress, _session_notifications,
_prompt_attachments, _session_history, _agent_callbacks, _session_auto_continue, _plugin_inject, _rpc_dispatch,
diff --git a/tui_gateway/slash_worker_client.py b/tui_gateway/slash_worker_client.py
new file mode 100644
index 00000000000..c9c8a4fc260
--- /dev/null
+++ b/tui_gateway/slash_worker_client.py
@@ -0,0 +1,190 @@
+"""The gateway side of the persistent slash worker: ``_SlashWorker`` starts ``tui_gateway.slash_worker`` as
+an owned child (``spawn_owned``), talks JSON lines to it, and stops its whole process group on close.
+
+Bodies are rebound onto server.py's globals at install time (method_ctx.bind_module), so they reference
+server.py globals bare: ``_hermes_home`` and ``_SLASH_WORKER_TIMEOUT_S``. Tests patch the names on
+``tui_gateway.server`` (``spawn_owned``, ``_stop_worker_group``, ``os``), where these bodies read them.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import queue
+import signal
+import subprocess
+import sys
+import threading
+from pathlib import Path
+
+from hermes_cli.process_identity import release_process_group_once_empty, spawn_owned
+from hermes_constants import get_hermes_home
+
+from .method_ctx import bind_module
+
+
+def _prepend_tool_paths(env: dict[str, str]) -> dict[str, str]:
+ """Prepend managed bin (managed-first policy for the Browser Use CLI), venv bin and
+ ~/.local/bin to PATH so slash_worker children resolve Hermes-managed CLIs under the Desktop's minimal PATH.
+ The PM store dirs go in front of all of them: a user's node/uv in ~/.local/bin never wins."""
+ managed_bin = ""
+ with contextlib.suppress(Exception):
+ managed_bin = str(Path(get_hermes_home()) / "bin")
+ venv_bin = str(Path(sys.executable).parent) # <venv>/bin (POSIX) or <venv>/Scripts (Windows)
+ parts = [p for p in (managed_bin, venv_bin, str(Path.home() / ".local" / "bin"), env.get("PATH") or "") if p]
+ env["PATH"] = os.pathsep.join(parts)
+ with contextlib.suppress(Exception):
+ import pm
+
+ env["PATH"] = pm.store_first_path(env["PATH"])
+ return env
+
+
+class _SlashWorker:
+ """Persistent HermesCLI subprocess for slash commands."""
+
+ def __init__(self, session_key: str, model: str, profile_home: str | None = None,
+ provider: str | None = None):
+ self._lock = threading.Lock()
+ self._seq = 0
+ self.stderr_tail: list[str] = []
+ self.stdout_queue: queue.Queue[dict | None] = queue.Queue()
+ # ``--provider`` pins the child to the parent agent's virtual provider: without it the
+ # worker re-resolves provider from config, so a MoA session (provider=moa, model=<preset>)
+ # dispatched its preset NAME to the configured real provider and 402/503'd (#57283).
+ argv = [sys.executable, "-P", "-m", "tui_gateway.slash_worker", "--session-key", session_key] \
+ + (["--model", model] if model else []) \
+ + (["--provider", provider] if provider else [])
+ self._closed = False
+ from hermes_cli._subprocess_compat import windows_hide_flags
+ # slash_worker runs the Hermes agent → needs provider credentials. Tier-1 secrets
+ # (gateway/GitHub/infra) are still stripped (#29157). Global-remote / multi-profile sessions: the
+ # worker must resolve config/skills/state against the session's profile home, not the gateway's
+ # launch HERMES_HOME (#40677).
+ from tools.environments.local import served_profile_child_env
+ from agent.secret_scope import is_multiplex_active
+
+ # The worker runs the agent → needs provider credentials; tier-1 secrets (gateway/GitHub/
+ # infra) are still stripped. A served profile's worker gets THAT profile's home + secrets and
+ # none of the launch profile's .env / TERMINAL_* residue, exactly what a standalone
+ # `hermes -p X` would load itself. The launch profile is a profile too: once the process hosts
+ # a second home (multiplex flipped), its worker must name its own home or the fail-closed
+ # no-target/no-scope path raises UnscopedSecretError (#115427).
+ env = _prepend_tool_paths(served_profile_child_env(
+ target_home=profile_home or (_hermes_home if is_multiplex_active() else None),
+ inherit_credentials=True))
+ # Internal slash workers must import the same checkout as their parent; -P keeps their cwd off sys.path.
+ module_root = str(Path(__file__).resolve().parent.parent)
+ env["PYTHONPATH"] = os.pathsep.join(
+ part for part in (module_root, env.get("PYTHONPATH", "")) if part
+ )
+ # spawn_owned: the worker leads its own process group (otherwise it inherits the gateway's
+ # pgid and mcp_tool's orphan sweep, racing the spawn, killpg()s the TUI parent itself), and
+ # that group dies with this process however it dies: SIGKILL/OOM of the gateway used to leave
+ # a quick command's shell, and anything else the worker started in its group, running forever.
+ # errors="replace": bytes invalid in the system locale (GBK Windows) must not raise
+ # UnicodeDecodeError in the drain threads.
+ # Prepend the Hermes venv bin dir and the user-local bin dir to PATH so slash_worker child processes
+ # can resolve Hermes-managed CLIs (browser-use, uvx) even when the parent gateway was launched with
+ # a minimal PATH (e.g. by the Desktop/Dashboard app). See #83845.
+ self.proc = spawn_owned(
+ argv, purpose="slash-worker", stdin=subprocess.PIPE, stdout=subprocess.PIPE,
+ stderr=subprocess.PIPE, text=True, encoding="utf-8", errors="replace", bufsize=1,
+ cwd=os.getcwd(), env=env, creationflags=windows_hide_flags())
+ threading.Thread(target=self._drain_stdout, daemon=True).start()
+ threading.Thread(target=self._drain_stderr, daemon=True).start()
+
+ def _drain_stdout(self):
+ for line in self.proc.stdout or []:
+ with contextlib.suppress(json.JSONDecodeError):
+ self.stdout_queue.put(json.loads(line))
+ self.stdout_queue.put(None)
+
+ def _drain_stderr(self):
+ for line in self.proc.stderr or []:
+ if text := line.rstrip("\n"):
+ self.stderr_tail = (self.stderr_tail + [text])[-80:]
+
+ def run(self, command: str) -> str:
+ """Run one command; return its output text.
+
+ A command like /prompt may also have parked a next-turn prompt (a "seed")
+ on the worker CLI; it rides back on the reply's ``seed`` field and is
+ retrieved separately via ``pop_seed()``.
+ """
+ if self.proc.poll() is not None:
+ raise RuntimeError("slash worker exited")
+ with self._lock:
+ self._seq += 1
+ rid = self._seq
+ self.proc.stdin.write(json.dumps({"id": rid, "command": command}) + "\n")
+ self.proc.stdin.flush()
+ while True:
+ try:
+ msg = self.stdout_queue.get(timeout=_SLASH_WORKER_TIMEOUT_S)
+ except queue.Empty:
+ raise RuntimeError("slash worker timed out")
+ if msg is None:
+ break
+ if msg.get("id") != rid:
+ continue
+ if not msg.get("ok"):
+ raise RuntimeError(msg.get("error", "slash worker failed"))
+ self._last_seed = str(msg.get("seed", "") or "")
+ return str(msg.get("output", "")).rstrip()
+ raise RuntimeError(
+ f"slash worker closed pipe{': ' + chr(10).join(self.stderr_tail[-8:]) if self.stderr_tail else ''}")
+
+ def pop_seed(self) -> str:
+ """Return and clear the seed from the last ``run()`` (empty when none)."""
+ seed, self._last_seed = getattr(self, "_last_seed", ""), ""
+ return seed
+
+ def close(self):
+ if getattr(self, "_closed", False):
+ return
+ self._closed = True
+ proc = self.proc
+ try:
+ _stop_worker_group(proc)
+ finally:
+ for stream in (proc.stdin, proc.stdout, proc.stderr):
+ with contextlib.suppress(Exception):
+ stream.close()
+
+
+def _stop_worker_group(proc) -> None:
+ """TERM the slash worker, give it 1 s, then KILL; never raises.
+
+ POSIX signals the worker's whole process group (``spawn_owned`` made it the leader): signalling
+ the leader alone left a running quick command's shell, or anything else the worker started in
+ its group, alive after every session close. The group is released from the owner-death
+ supervisor once it is empty; a group that is not stays covered.
+ """
+ if os.name != "posix":
+ for stop in (proc.terminate, proc.kill):
+ if proc.poll() is not None:
+ return
+ with contextlib.suppress(Exception):
+ stop()
+ proc.wait(timeout=1) # also reaps the zombie a kill leaves behind
+ return
+ pgid = proc.pid
+ # Only a leader still alive on entry proves the number is still this worker's group. A worker
+ # that already died leaves its group to the owner-death supervisor rather than risk signalling
+ # a recycled pgid.
+ if proc.poll() is None:
+ for sig in (signal.SIGTERM, signal.SIGKILL):
+ # Members that outlive the leader keep the group (and its number) alive.
+ with contextlib.suppress(OSError):
+ os.killpg(pgid, sig) # windows-footgun: ok — POSIX-only, Windows returned above
+ with contextlib.suppress(Exception):
+ proc.wait(timeout=1)
+ # Killed members are reaped by init asynchronously; one still alive after that stays covered.
+ release_process_group_once_empty(pgid, proc=proc)
+
+
+def register(server) -> None:
+ """Publish the worker class and its helpers onto ``server``, rebound to its globals."""
+ bind_module(globals(), server)