gateway_chat.py 22 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403
  1. """Normal classic/one-shot launch through the canonical gateway, never AIAgent."""
  2. from __future__ import annotations
  3. import argparse
  4. import asyncio
  5. import contextlib
  6. import os
  7. from pathlib import Path
  8. import sys
  9. import uuid
  10. from hermes_cli.gateway_client import RESUME_KEY_MISMATCH, GatewayClientError, connect_gateway
  11. from hermes_cli.gateway_connection import RESUME_REFUSALS
  12. # These options change execution or require frontend facilities not yet exposed by
  13. # the authority. Reject them, rather than mutate process-wide gateway settings.
  14. _UNSUPPORTED = (
  15. "image", "worktree", "w",
  16. "no_restore_cwd",
  17. "run_budget", "verbose", "compact",
  18. )
  19. _POLICY = ("model", "provider", "reasoning", "toolsets", "max_turns", "base_url", "ignore_rules", "api_key",
  20. "yolo", "safe_mode", "ignore_user_config", "skills", "checkpoints", "accept_hooks", "pass_session_id")
  21. # Where each refused option lives now; the refusal names it so the user is not left guessing.
  22. _RELOCATED = {
  23. "image": "`hermes --tui` or the Desktop app to attach the image",
  24. "worktree": "`hermes --tui -w`",
  25. "w": "`hermes --tui -w`",
  26. "no_restore_cwd": "`--in <dir>` (the gateway keeps the session's frozen cwd)",
  27. "run_budget": "`agent.run_budget_seconds` in config.yaml",
  28. "verbose": "`hermes logs --follow`, or `hermes chat --tui -v`",
  29. "compact": "`display.compact: true` in config.yaml",
  30. "create-if-missing without -c <name>": "`-c <name> --create-if-missing`",
  31. }
  32. _SAFE_MODE_EXAMPLE = 'hermes chat --safe-mode --provider openrouter --model anthropic/claude-sonnet-4 -q "hello"'
  33. # The documented environment equivalents of creation flags (the set Ink's localCreationOptions
  34. # maps). The auto-started owner no longer inherits them (R14 scrub), so they only take effect
  35. # by riding THIS session's session.create; a resume keeps the frozen route.
  36. _ENV_LAUNCH_FLAGS = (("yolo", "HERMES_YOLO_MODE"), ("ignore_rules", "HERMES_IGNORE_RULES"),
  37. ("safe_mode", "HERMES_SAFE_MODE"), ("ignore_user_config", "HERMES_IGNORE_USER_CONFIG"),
  38. ("accept_hooks", "HERMES_ACCEPT_HOOKS"))
  39. def env_launch_flags() -> dict:
  40. from utils import is_truthy_value
  41. return {field: True for field, name in _ENV_LAUNCH_FLAGS if is_truthy_value(os.environ.get(name))}
  42. def shell_client_env() -> dict:
  43. """This shell's allowlisted environment (``agent.session_client_env``) with the extra names of the
  44. profile's effective config (managed layer included), as the gateway reads them. A bypass launch's
  45. owner freezes code defaults, so it reads no profile."""
  46. from agent.session_client_env import collect_client_env
  47. if {'safe_mode', 'ignore_user_config'} & set(env_launch_flags()):
  48. return collect_client_env()
  49. from hermes_cli.config import get_config_path
  50. from hermes_cli.config_effective import load_user_config_effective
  51. return collect_client_env(config=load_user_config_effective(get_config_path()))
  52. def client_env_policy(parameters) -> dict:
  53. """``client_env`` for a new session (main's process read these from its shell; the shared gateway
  54. applies them to this session only), or nothing for a gateway that predates the field."""
  55. return {"client_env": shell_client_env()} if "client_env" in parameters else {}
  56. def bypass_launch(args) -> bool:
  57. """--safe-mode / --ignore-user-config (or their env opt-ins): the owner freezes code defaults,
  58. the client reads no profile."""
  59. env = env_launch_flags()
  60. return any(getattr(args, name, False) or env.get(name) for name in ("safe_mode", "ignore_user_config"))
  61. def continue_title(args):
  62. """``-c <name>`` (classic precedence: ignored when ``--resume`` is given)."""
  63. name = getattr(args, "continue_last", None)
  64. return name if isinstance(name, str) and not getattr(args, "resume", None) else None
  65. def wants_latest(args):
  66. """Bare ``-c`` or ``--resume latest`` (the keyword wins over a session titled "latest", which
  67. stays reachable by id or ``-c latest``)."""
  68. resume = getattr(args, "resume", None)
  69. if isinstance(resume, str):
  70. return resume.strip().lower() == "latest"
  71. return getattr(args, "continue_last", None) is True
  72. def validate_options(args):
  73. unsupported = [name for name in _UNSUPPORTED if getattr(args, name, None)]
  74. if getattr(args, "create_if_missing", False) and not continue_title(args):
  75. unsupported.append("create-if-missing without -c <name>")
  76. if unsupported:
  77. # A one-letter alias (``cli.main(w=True)``) is spelled ``-w``, never the nonexistent ``--w``.
  78. spell = {name: ("-" if len(name) == 1 else "--") + name.replace("_", "-") for name in unsupported}
  79. flags = ", ".join(spell[name] for name in unsupported)
  80. where = "".join(f"\n {spell[name]}: use {_RELOCATED[name]}" for name in unsupported)
  81. raise GatewayClientError(
  82. f"Unsupported gateway CLI options: {flags}. No local fallback or policy changes were made.{where}")
  83. # Creation flags repeated on resume are checked against the frozen route once the snapshot is
  84. # back (`check_resume_policy`): the same flags again are fine, a different value is refused.
  85. # A resume reuses the frozen route and reads no default (the TUI launcher's rule too).
  86. resuming = getattr(args, "resume", None) or getattr(args, "continue_last", None)
  87. if bypass_launch(args) and not getattr(args, "model", None) and not resuming:
  88. raise GatewayClientError("--safe-mode / --ignore-user-config (or HERMES_SAFE_MODE / HERMES_IGNORE_USER_CONFIG) "
  89. "read no profile default: pass --model explicitly."
  90. f"\n Example: {_SAFE_MODE_EXAMPLE}")
  91. def _caller_cwd(args) -> str:
  92. """The caller's working directory (``--in`` wins), resolved; filesystem work, so off the loop."""
  93. return str(Path(getattr(args, "in_dir", None) or os.getcwd()).expanduser().resolve())
  94. def _workspace_key(cwd):
  95. """The classic CLI's workspace identity for ``-c`` (git root, else the cwd)."""
  96. from hermes_cli.main import _resolve_workspace_key
  97. previous = os.getcwd()
  98. try:
  99. os.chdir(cwd)
  100. return _resolve_workspace_key()
  101. finally:
  102. os.chdir(previous)
  103. async def _resume(client, args, **params):
  104. """``session.resume``; ``--api-key`` re-supplies a launch-only key an owner restart revoked.
  105. The owner binds it only to a session launched with that same key (never durable); anything
  106. else is a route override and refused like every other creation flag on resume."""
  107. key = getattr(args, "api_key", None)
  108. try:
  109. return await client.rpc("session.resume", **params, **({"api_key": key} if key else {}))
  110. except GatewayClientError as exc:
  111. if key and str(exc) == "admission_conflict":
  112. raise GatewayClientError(RESUME_KEY_MISMATCH) from None
  113. raise
  114. async def _resume_latest(client, args):
  115. """Bare ``-c``: this terminal's breadcrumb session when the owner still has it, else (and for
  116. ``--resume latest``) the owner's most recent CLI session, this workspace first."""
  117. from hermes_cli.terminal_breadcrumbs import read_breadcrumb
  118. crumb = (read_breadcrumb() or {}).get("session_id") if getattr(args, "continue_last", None) is True else None
  119. if isinstance(crumb, str) and crumb:
  120. try:
  121. return await _resume(client, args, session_id=crumb)
  122. except GatewayClientError as exc:
  123. if str(exc) not in RESUME_REFUSALS:
  124. raise
  125. workspace = await asyncio.to_thread(_workspace_key, _caller_cwd(args))
  126. try:
  127. return await _resume(client, args, latest="cli", **({"workspace": workspace} if workspace else {}))
  128. except GatewayClientError as exc:
  129. if str(exc) != "not_found":
  130. raise
  131. raise GatewayClientError("No previous CLI session to continue. Start a new one with `hermes`, "
  132. "or list sessions with `hermes sessions list`.") from None
  133. async def run_gateway_chat(args, emitter=None):
  134. from hermes_cli.gateway_chat_view import GatewayChatView
  135. query = getattr(args, "query", None) or getattr(args, "q", None)
  136. oneshot_prompt = getattr(args, "oneshot", None)
  137. if isinstance(oneshot_prompt, str):
  138. query = oneshot_prompt
  139. quiet = bool(getattr(args, "quiet", False) or oneshot_prompt or emitter is not None)
  140. # Finite: answer one prompt and exit (-z, --oneshot, -Q, stream-json, or -q off a TTY).
  141. oneshot = bool(oneshot_prompt or getattr(args, "oneshot_exit", False) or quiet or
  142. (query and not (sys.stdin.isatty() and sys.stdout.isatty())))
  143. async with connect_gateway() as client:
  144. description = await client.rpc("runtime.describe")
  145. title = continue_title(args)
  146. create_if_missing = bool(title and getattr(args, "create_if_missing", False))
  147. latest = wants_latest(args)
  148. if latest:
  149. snapshot = await _resume_latest(client, args)
  150. check_resume_policy(args, snapshot)
  151. elif getattr(args, "resume", None) or (title and not create_if_missing):
  152. name = getattr(args, "resume", None) or title
  153. try:
  154. # Exact id first, then title (latest lineage continuation), as the classic CLI did.
  155. snapshot = await _resume(client, args, session_id=name)
  156. except GatewayClientError as exc:
  157. if str(exc) != "not_found":
  158. raise
  159. try:
  160. snapshot = await _resume(client, args, title=name)
  161. except GatewayClientError as exc:
  162. if str(exc) != "not_found":
  163. raise
  164. raise GatewayClientError(
  165. f"No session found matching '{name}'. Use 'hermes sessions list' to see available "
  166. "sessions, or pass -c <name> --create-if-missing to start a new session with that title.")
  167. check_resume_policy(args, snapshot)
  168. else:
  169. contract = description.get("session_create", {})
  170. # Finite runs are stored as ``oneshot`` (hidden from human pickers, still CLI history);
  171. # an explicit ``--source`` always wins. A remote gateway predating the label stores ``cli``.
  172. sources = contract.get("sources", [])
  173. from agent.session_source import create_surface
  174. source = create_surface(getattr(args, "source", None) or ("oneshot" if oneshot and "oneshot" in sources else "cli"))
  175. if source not in sources:
  176. raise GatewayClientError(f"Gateway does not support source {source!r}")
  177. parameters = contract.get("parameters", [])
  178. policy = _requested_policy(args)
  179. policy.pop("source", None)
  180. if create_if_missing:
  181. policy["title"] = title
  182. policy.update(env_launch_flags())
  183. policy.update(client_env_policy(parameters))
  184. cwd = await asyncio.to_thread(_caller_cwd, args)
  185. if "cwd" in parameters:
  186. policy["cwd"] = cwd
  187. elif getattr(args, "in_dir", None):
  188. raise GatewayClientError("Gateway does not support --in / caller cwd; update the gateway")
  189. else:
  190. print("Warning: this gateway cannot preserve caller cwd; it uses its configured execution directory.", file=sys.stderr)
  191. missing = sorted(set(policy) - set(parameters))
  192. if missing:
  193. raise GatewayClientError("Gateway does not support creation options: " + ", ".join(missing))
  194. snapshot = await client.rpc("session.create", request_id=uuid.uuid4().hex, source=source, **policy)
  195. if (warning := (snapshot.get("info") or {}).get("config_warning")) and not isinstance(oneshot_prompt, str):
  196. print(f"Warning: {warning}", file=sys.stderr)
  197. if not isinstance(oneshot_prompt, str): # main's -z writes nothing to stderr on success
  198. print("Session: " + snapshot["stored_session_id"], file=sys.stderr, flush=True)
  199. if not oneshot:
  200. from hermes_cli.terminal_breadcrumbs import write_breadcrumb
  201. await asyncio.to_thread(write_breadcrumb, snapshot["stored_session_id"])
  202. if emitter is not None:
  203. emitter.bind_session(snapshot["stored_session_id"])
  204. view = GatewayChatView(client, snapshot, quiet=quiet, emitter=emitter,
  205. usage_file=getattr(args, "usage_file", None))
  206. view.launch_api_key = getattr(args, "api_key", None) # /new keeps this launch's key
  207. view.unattended = isinstance(oneshot_prompt, str)
  208. view.resume_footer = oneshot and not quiet
  209. if (getattr(args, "resume", None) or title or latest) and not quiet:
  210. from agent.context_compressor import MODEL_ONLY_DISPLAY_METADATA_KEY
  211. for row in snapshot.get("messages", []):
  212. # A micro-compaction merge (model_only) is not printed: its original prompts are.
  213. metadata = row.get("display_metadata")
  214. merged = isinstance(metadata, dict) and metadata.get(MODEL_ONLY_DISPLAY_METADATA_KEY)
  215. if row.get("role") in {"user", "assistant"} and isinstance(row.get("content"), str) and not merged:
  216. print(f"{row['role']}: {row['content']}")
  217. return await view.run(query, oneshot=oneshot)
  218. _RESUME_POLICY_MISMATCH = "Resume retains gateway session policy; creation overrides are unsupported on resume."
  219. # A refused resume flag as the user typed it, and the slash command that changes it on the resumed session.
  220. _RESUME_FLAG_HINTS = {"model": ("-m/--model", "/model"), "provider": ("--provider", "/model"),
  221. "base_url": ("--base-url", "/model"), "reasoning": ("--reasoning", "/reasoning"),
  222. "yolo": ("--yolo", "/yolo"), "toolsets": ("-t/--toolsets", None),
  223. "skills": ("-s/--skills", None), "verbose": ("-v/--verbose", None), "cwd": ("--in", None)}
  224. def resume_policy_error(keys):
  225. """The resume refusal naming each flag that differs from the session's frozen launch, and the way forward."""
  226. hints = [_RESUME_FLAG_HINTS.get(key, ("--" + key.replace("_", "-"), None)) for key in keys]
  227. flags = ", ".join(dict.fromkeys(flag for flag, _ in hints))
  228. switch = " or ".join(dict.fromkeys(command for _, command in hints if command))
  229. one = len(hints) == 1
  230. them = "it" if one else "them"
  231. after = f" and use {switch} after resuming to switch" if switch else f", or start a new session to use {them}"
  232. return GatewayClientError(f"{_RESUME_POLICY_MISMATCH} {flags} {'differs' if one else 'differ'} from this "
  233. f"session's launch: resume without {them}{after}.")
  234. def exit_on_resume_refusal(exc):
  235. """A refused resume is a usage error on every classic path (interactive startup's copy): ``Error:``, exit 2."""
  236. if isinstance(exc, GatewayClientError) and str(exc).startswith((_RESUME_POLICY_MISMATCH, RESUME_KEY_MISMATCH)):
  237. print(f"Error: {exc}", file=sys.stderr)
  238. raise SystemExit(2) from None
  239. def _launch_flags(args):
  240. """The creation flags the user passed. Identity, not equality: ``--max-turns 0`` (unlimited)
  241. is a value, while ``0 == False`` would drop it to the profile default."""
  242. return {key: value for key in _POLICY if (value := getattr(args, key, None)) is not None and value is not False}
  243. def _requested_policy(args):
  244. policy = _launch_flags(args)
  245. if isinstance(policy.get("toolsets"), str):
  246. policy["toolsets"] = [name.strip() for name in policy["toolsets"].split(",") if name.strip()]
  247. if "skills" in policy:
  248. # `-s a,b -s c` (argparse append) or cli.main's comma string: one deduplicated list.
  249. raw = policy["skills"] if isinstance(policy["skills"], (list, tuple)) else [policy["skills"]]
  250. names = [name.strip() for item in raw for name in str(item).split(",") if name.strip()]
  251. policy["skills"] = list(dict.fromkeys(names))
  252. if not policy["skills"]:
  253. policy.pop("skills")
  254. if getattr(args, "source", None):
  255. from agent.session_source import create_surface
  256. policy["source"] = create_surface(args.source)
  257. return policy
  258. def check_resume_policy(args, snapshot):
  259. """A resume may repeat the flags the session was created with (scripts re-run one command
  260. line); anything that would CHANGE the frozen route is refused, as before."""
  261. requested = _requested_policy(args)
  262. if getattr(args, "in_dir", None):
  263. requested["cwd"] = str(Path(args.in_dir).expanduser().resolve())
  264. if not requested:
  265. return
  266. info = snapshot.get("info") if isinstance(snapshot, dict) else None
  267. frozen = dict((info or {}).get("launch_request") or {})
  268. if info and "cwd" in info:
  269. frozen["cwd"] = info["cwd"]
  270. if "model" in requested and requested["model"] == frozen.get("model_requested"):
  271. requested["model"] = frozen.get("model") # the alias the owner resolved at creation
  272. elif "model" in requested and requested["model"] != frozen.get("model") and "model_requested" not in frozen:
  273. # The owner froze the resolved id of a `-m <alias>`; the same alias again is the same route.
  274. from gateway.session_local_route import resolve_launch_route
  275. from hermes_cli.config_effective import load_user_config_effective
  276. from hermes_constants import get_hermes_home
  277. flags = {key: requested[key] for key in ("model", "provider", "base_url", "api_key") if key in requested}
  278. requested["model"] = resolve_launch_route(flags, load_user_config_effective(get_hermes_home() / "config.yaml"))["model"]
  279. # api_key is never durable; a repeated key is not a policy change.
  280. differs = [key for key, value in requested.items() if key != "api_key" and frozen.get(key) != value]
  281. if differs:
  282. raise resume_policy_error(differs)
  283. def _register_terminal_process() -> None:
  284. """The chat client is still a terminal on this HERMES_HOME: record it in the process ledger
  285. (purpose ``cli`` is never update-reapable) and warn once when another install shares the home."""
  286. from hermes_cli.process_identity import register_self
  287. from hermes_cli.shared_profile_warning import shared_profile_warning
  288. register_self("cli")
  289. warning = shared_profile_warning()
  290. if warning:
  291. print(f"Warning: {warning}", file=sys.stderr)
  292. def launch_from_args(args) -> int:
  293. from websockets.exceptions import WebSocketException
  294. emitter = None
  295. if getattr(args, "output_format", "text") == "stream-json":
  296. # Built before validation/connection so any failed start still closes the protocol
  297. # (init + result) instead of exiting with an empty stdout.
  298. from hermes_cli.stream_json import StreamJsonEmitter
  299. emitter = StreamJsonEmitter(model=getattr(args, "model", None) or "")
  300. def failed(message, code):
  301. print("Error: " + message, file=sys.stderr)
  302. if emitter is not None:
  303. return emitter.emit_result({"failed": True, "error": message}, exit_code=code)
  304. return code
  305. try:
  306. validate_options(args)
  307. if getattr(args, "list_tools", False) or getattr(args, "list_toolsets", False):
  308. # A catalog listing needs no session and no gateway (main printed it and exited).
  309. from hermes_cli.gateway_chat_listing import print_tool_listing
  310. return print_tool_listing(args)
  311. _register_terminal_process()
  312. from hermes_cli.gateway_chat_startup import ensure_launch_provider
  313. if emitter is None:
  314. if not ensure_launch_provider(args):
  315. return 0
  316. else:
  317. # Setup guidance is human text and the guard exits on a non-TTY: both must become
  318. # stderr diagnostics + a failed ``result`` when stdout is machine-readable.
  319. try:
  320. with contextlib.redirect_stdout(sys.stderr):
  321. configured = ensure_launch_provider(args)
  322. except SystemExit:
  323. configured = False
  324. if not configured:
  325. return failed("credentials or agent init failed", 1)
  326. query_file = getattr(args, "query_file", None)
  327. if query_file:
  328. # Main's --query-file contract (the Bot Mode DM transport): undecodable bytes are
  329. # replaced, and an unreadable or empty file is exit 2 with the file named.
  330. try:
  331. if query_file == "-":
  332. args.query = sys.stdin.read()
  333. else:
  334. with open(query_file, encoding="utf-8-sig", errors="replace") as handle:
  335. args.query = handle.read()
  336. except OSError as exc:
  337. return failed(f"cannot read --query-file {query_file}: {exc}", 2)
  338. if not args.query.strip():
  339. return failed(f"--query-file {query_file} is empty", 2)
  340. if not (getattr(args, "query", None) or getattr(args, "q", None) or getattr(args, "oneshot", None) or sys.stdin.isatty()):
  341. raise GatewayClientError("Noninteractive chat requires --query or --oneshot")
  342. return asyncio.run(run_gateway_chat(args, emitter=emitter))
  343. except (GatewayClientError, OSError, TimeoutError, WebSocketException) as exc:
  344. # WebSocket errors can embed credential URLs/remote bodies.
  345. message = str(exc) if isinstance(exc, GatewayClientError) else "Gateway connection/read failed; no local fallback"
  346. return failed(message, 2 if isinstance(exc, GatewayClientError) and ("Unsupported" in message or "unsupported" in message) else 1)
  347. except KeyboardInterrupt:
  348. print("Detached; accepted work continues at the gateway.", file=sys.stderr)
  349. if emitter is not None:
  350. return emitter.emit_result({"interrupted": True}, exit_code=130)
  351. return 130
  352. def launch_from_kwargs(options) -> int:
  353. return launch_from_args(argparse.Namespace(**options))