The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
docs(pause): hermes pause holds interactive CLI, TUI and Desktop turns too
Teknium4be3eb413a7e
diff --git a/hermes_cli/subcommands/pause.py b/hermes_cli/subcommands/pause.pyindex 5b05684a399..6416df092b2 100644--- a/hermes_cli/subcommands/pause.py+++ b/hermes_cli/subcommands/pause.py@@ -1,8 +1,9 @@"""``hermes pause`` / ``hermes resume`` — the global emergency stop.``pause`` writes the ESTOP sentinel at ``$HERMES_HOME/ESTOP``; cron, kanban and new gateway-turns halt on their next check (in-flight work is never killed). ``resume`` removes it and-operation resumes on the next tick — no restart. Ported from gastownhall/gastown estop.go (MIT).+turns halt on their next check (in-flight work is never killed). Every local turn is a gateway+turn, so interactive CLI, TUI and Desktop turns are held too, with ``agent.estop.paused_reply``'s+notice. ``resume`` removes it and operation resumes on the next tick — no restart. Ported from gastownhall/gastown estop.go (MIT)."""from __future__ import annotations@@ -23,8 +24,9 @@ def cmd_pause(args: argparse.Namespace) -> int:print(f"⏸️ {verb}{detail}")print(f" sentinel: {path}")print(- " Cron dispatch, kanban dispatch, and new gateway turns are on hold.\n"- " In-flight work keeps running. Run `hermes resume` to lift the pause.")+ " Cron dispatch, kanban dispatch, and new gateway turns (messaging and interactive\n"+ " CLI, TUI and Desktop turns alike) are on hold. In-flight work keeps running.\n"+ " Run `hermes resume` to lift the pause.")return 0@@ -45,7 +47,9 @@ def build_pause_parser(subparsers) -> None:"pause", help="Emergency stop: pause cron/kanban dispatch and new gateway turns",description="Engage the global emergency stop. Halts NEW work only — cron ""dispatch, kanban dispatch, and new gateway turns — until "- "`hermes resume`. In-flight work is never killed.")+ "`hermes resume`. Interactive CLI, TUI and Desktop turns are gateway turns, so they "+ "are held too: each gets \"Hermes is paused\" with the reason. Turns already "+ "running finish; in-flight work is never killed.")pause_parser.add_argument("--reason", default=None, help="Optional reason stored in the sentinel and shown to users")pause_parser.set_defaults(func=cmd_pause)diff --git a/tests/gateway/fixtures/estop_interactive_peer.py b/tests/gateway/fixtures/estop_interactive_peer.pynew file mode 100644index 00000000000..7f5d85be2e7--- /dev/null+++ b/tests/gateway/fixtures/estop_interactive_peer.py@@ -0,0 +1,105 @@+"""GW-1 fixture: `hermes pause` holds every gateway turn, including interactive (TUI/Desktop/CLI) ones.++A real GatewayRunner + session authority + WS API in a fake HERMES_HOME, a loopback model. Phase 1+starts a turn that blocks in the model, engages the ESTOP and releases it: the running turn must+finish normally. Phase 2 submits a new interactive turn while paused: its completion must carry+``estop.paused_reply()`` (the reason and "run `hermes resume`") and the model is never called.+Phase 3 resumes and the next turn runs. Writes receipt.json into HERMES_HOME.+"""+import asyncio+from http.server import ThreadingHTTPServer+import json+import os+from pathlib import Path+import sys+import threading+import traceback+++async def probe():+ from gateway.run import GatewayRunner+ from gateway.session_authority import initialize_session_authority+ from gateway.run_api import start_gateway_api, stop_gateway_api+ from hermes_cli import web_server+ from hermes_cli.dashboard_auth.ws_tickets import mint_ticket+ from tests.gateway.fixtures.local_recovery_probe import Model+ from agent import estop+ from websockets.asyncio.client import connect++ home = Path(os.environ['HERMES_HOME'])+ peer = ThreadingHTTPServer(('127.0.0.1', 0), Model)+ peer.requests, peer.blocked, peer.release = [], threading.Event(), threading.Event()+ threading.Thread(target=peer.serve_forever, daemon=True).start()+ url = f'http://127.0.0.1:{peer.server_port}/v1'+ os.environ.update(OPENAI_API_KEY='loopback-only', OPENAI_BASE_URL=url)+ (home / 'config.yaml').write_text(json.dumps({+ 'model': {'provider': 'custom', 'default': 'loopback', 'base_url': url},+ 'auxiliary': {'title_generation': {'enabled': False}}, 'platform_toolsets': {'cli': []}}))+ runner = GatewayRunner()+ await initialize_session_authority(runner, profile_id=str(home), instance_id='estop-probe')+ api = await start_gateway_api(runner)+ web_server.app.state.auth_required = True+ receipt = {}+ try:+ ticket = mint_ticket(user_id='owner', provider='fixture')+ async with connect(api.api_origin.replace('http:', 'ws:') + '/api/ws?ticket=' + ticket) as ws:+ pending = {}+ frames = asyncio.Queue()++ async def pump():+ async for raw in ws:+ frame = json.loads(raw)+ if 'id' in frame and frame['id'] in pending:+ pending.pop(frame['id']).set_result(frame)+ elif frame.get('method') == 'event':+ await frames.put(frame['params'])+ pumper = asyncio.create_task(pump())++ async def rpc(method, **params):+ rid = f'{method}-{len(pending)}-{asyncio.get_running_loop().time()}'+ pending[rid] = asyncio.get_running_loop().create_future()+ await ws.send(json.dumps({'jsonrpc': '2.0', 'id': rid, 'method': method, 'params': params}))+ return await asyncio.wait_for(pending[rid], 30)++ async def complete():+ while True:+ event = await asyncio.wait_for(frames.get(), 60)+ if event.get('type') == 'message.complete':+ return event.get('payload') or {}++ sid = (await rpc('session.create', request_id='estop', source='tui', cwd=str(home),+ toolsets=[]))['result']['session_id']+ # Phase 1: a turn already running when the pause lands finishes.+ await rpc('prompt.submit', session_id=sid, input_id='running', text='BLOCK_STARTED')+ assert await asyncio.to_thread(peer.blocked.wait, 30), 'model never reached'+ estop.engage(reason='maintenance window')+ peer.release.set()+ receipt['running'] = await complete()+ # Phase 2: a new interactive turn while paused gets the named refusal; no model call.+ calls = len(peer.requests)+ receipt['paused_submit'] = (await rpc('prompt.submit', session_id=sid, input_id='paused',+ text='NEW_WHILE_PAUSED')).get('result')+ receipt['paused'] = await complete()+ receipt['paused_model_calls'] = len(peer.requests) - calls+ receipt['expected_notice'] = estop.paused_reply()+ # Phase 3: resume; the next turn runs.+ estop.disengage()+ await rpc('prompt.submit', session_id=sid, input_id='after', text='AFTER_RESUME')+ receipt['after'] = await complete()+ pumper.cancel()+ finally:+ await stop_gateway_api(api)+ peer.shutdown()+ (home / 'receipt.json').write_text(json.dumps(receipt, default=str))+++if __name__ == '__main__':+ status = 0+ try:+ asyncio.run(probe())+ except BaseException:+ traceback.print_exc()+ status = 1+ sys.stdout.flush()+ sys.stderr.flush()+ os._exit(status)diff --git a/tests/gateway/test_estop_interactive_turns.py b/tests/gateway/test_estop_interactive_turns.pynew file mode 100644index 00000000000..8809259e38d--- /dev/null+++ b/tests/gateway/test_estop_interactive_turns.py@@ -0,0 +1,66 @@+"""GW-1 (#134889): `hermes pause` holds every gateway turn, interactive ones included.++Since #106742 every local turn is a gateway turn, so the emergency stop holding CLI, TUI and Desktop+turns is the stop working as designed. What every surface must get is the same named refusal+(``agent.estop.paused_reply``: the reason and "run `hermes resume`"), and a turn already running+when the pause lands must finish. Real GatewayRunner + authority + WS API, loopback model.+"""+import json+from pathlib import Path+import subprocess+import sys++import pytest++from tests.gateway.fixtures.local_recovery_probe import child_env++[email protected](scope='module')+def receipt(tmp_path_factory):+ root = Path(__file__).resolve().parents[2]+ tmp = tmp_path_factory.mktemp('estop')+ home, user = tmp / 'state', tmp / 'user'+ home.mkdir()+ user.mkdir()+ env = child_env()+ env.update(HOME=str(user), USERPROFILE=str(user), HERMES_HOME=str(home), PYTHONPATH=str(root),+ PYTHONUNBUFFERED='1')+ result = subprocess.run([sys.executable, str(root / 'tests/gateway/fixtures/estop_interactive_peer.py')],+ cwd=root, env=env, capture_output=True, text=True, timeout=180, check=False)+ assert result.returncode == 0, result.stdout + result.stderr+ return json.loads((home / 'receipt.json').read_text())+++def _text(payload):+ return str(payload.get('text') or payload.get('content') or payload.get('final_response') or '')+++def test_a_turn_already_running_when_pause_lands_finishes(receipt):+ assert 'RECOVERY_ACK_BLOCK_STARTED' in _text(receipt['running']), receipt['running']+++def test_a_new_interactive_turn_gets_the_named_refusal_with_reason_and_resume(receipt):+ notice = receipt['expected_notice']+ assert 'maintenance window' in notice and 'hermes resume' in notice, notice+ assert _text(receipt['paused']).strip() == notice, receipt['paused']+ assert receipt['paused_model_calls'] == 0, receipt+++def test_resume_lets_the_next_turn_run(receipt):+ assert 'RECOVERY_ACK_AFTER_RESUME' in _text(receipt['after']), receipt['after']+++def test_pause_help_and_docs_say_interactive_turns_are_held_too():+ """The decided contract is documented where operators read it (`hermes pause --help`, the CLI+ reference): interactive CLI, TUI and Desktop turns are gateway turns and are held too."""+ import argparse+ from hermes_cli.subcommands.pause import build_pause_parser+ parser = argparse.ArgumentParser(prog='hermes')+ build_pause_parser(parser.add_subparsers())+ sub = parser._subparsers._group_actions[0].choices['pause']+ text = ' '.join(sub.format_help().split())+ for needle in ('CLI', 'TUI', 'Desktop', 'hermes resume'):+ assert needle in text, text+ doc = (Path(__file__).resolve().parents[2] / 'website/docs/reference/cli-commands.md').read_text()+ row = next(line for line in doc.splitlines() if line.startswith('| `hermes pause`'))+ assert 'CLI, TUI and Desktop' in row and 'finish' in row, rowdiff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.mdindex c82066bdb98..9a6b5635594 100644--- a/website/docs/reference/cli-commands.md+++ b/website/docs/reference/cli-commands.md@@ -68,7 +68,7 @@ The install also ships `hermes-agent`, a minimal runner that sends one query and| `hermes status` | Show agent, auth, and platform status. || `hermes usage` | Show the configured account's rate-limit windows (the `/usage` block) without a session; `--json` for scripts. || `hermes cron` | Inspect and tick the cron scheduler. |-| `hermes pause` / `hermes resume` | Global emergency stop: no new cron fires (built-in ticker, managed-cron webhook, misfire catch-up), kanban dispatch or gateway turns start until resumed; in-flight work is never killed. |+| `hermes pause` / `hermes resume` | Global emergency stop: no new cron fires (built-in ticker, managed-cron webhook, misfire catch-up), kanban dispatch or gateway turns start until resumed. Interactive CLI, TUI and Desktop turns are gateway turns, so they are held too, and each surface shows "Hermes is paused" with the reason and "run `hermes resume`". Turns already running finish; in-flight work is never killed. || `hermes kanban` | Multi-profile collaboration board (tasks, links, dispatcher). || `hermes project` | Manage named, multi-folder workspaces (projects). Anchors desktop session grouping and, when bound to a kanban board, gives tasks a deterministic worktree + branch convention. State is per-profile. || `hermes webhook` | Manage dynamic webhook subscriptions for event-driven activation. |