| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522 |
- """The AIAgent surface main's HermesCLI uses, backed by the shared gateway session (CALLMAP §3.2-3.3).
- ``run_conversation`` submits ``prompt.submit`` and replays the gateway's event stream, on the
- calling (agent) thread, into the SAME callbacks HermesCLI passed to ``AIAgent`` on main, then
- returns a dict shaped like ``AIAgent.run_conversation``'s. The CLI process never builds an agent,
- never runs a tool and never writes ``state.db``: the turn runs in the gateway.
- Event contract: wave_a.md (frozen). Every frame is a gateway ``event`` with params
- ``{type, session_id, execution_generation, admission_id?, payload}``.
- """
- from __future__ import annotations
- import json
- import logging
- import queue
- import threading
- import time
- import uuid
- from contextlib import suppress
- from hermes_cli.gateway_client import GatewayClientError, GatewayRPCError
- from hermes_cli.gateway_connection import DISCONNECTED, NOT_SENT, CallStopped, lost_before
- logger = logging.getLogger(__name__)
- # How long a turn waits for its settlement after an interrupt (main: cli_chat_turn_mixin 10 s).
- INTERRUPT_SETTLE_SECONDS = 10.0
- _POLL = 0.1
- # ``steer()`` / ``redirect()``'s reply when the owner consumed the text as a typed voice stop (TUI-26):
- # truthy, so a caller that only asks "taken?" never re-queues it.
- VOICE_STOPPED = "voice_stopped"
- _RESULT_DEFAULTS = {
- "final_response": "", "failed": False, "partial": False, "error": None, "failure_reason": None,
- "completed": True, "interrupted": False, "interrupt_message": None, "api_calls": 0,
- "pending_steer": None, "last_reasoning": None, "response_previewed": False,
- "response_transformed": False, "pre_transform_response": None, "billing_block": None,
- "auxiliary_usage": {},
- }
- # ``session.usage`` / ``session.stats`` (wave_a2 contract, session-cumulative) → the agent attributes
- # main's status bar, spinner (``↓ N tok``) and /usage read off ``AIAgent``.
- _COUNTER_FROM_USAGE = {
- "session_input_tokens": "input_tokens", "session_output_tokens": "output_tokens",
- "session_prompt_tokens": "prompt_tokens", "session_completion_tokens": "completion_tokens",
- "session_total_tokens": "total_tokens", "session_cache_read_tokens": "cache_read_tokens",
- "session_cache_write_tokens": "cache_write_tokens", "session_reasoning_tokens": "reasoning_tokens",
- "session_api_calls": "api_calls",
- }
- class _CompressorView:
- """``agent.context_compressor`` as the status bar / banner read it (plain attributes)."""
- def __init__(self):
- self.last_prompt_tokens = 0
- self.last_real_prompt_tokens = None
- self.context_length = 0
- self.compression_count = 0
- self._config_context_length = None
- self.threshold_tokens = 0
- class _Turn:
- """One ``run_conversation``; what each consumer got of the reply's current segment (``shown``: the
- terminal, ``spoken``: ``stream_callback``) and the closed segments and interims (``seen``), for the
- settlement after a replay gap."""
- def __init__(self, session_id):
- self.session_id, self.admission = session_id, None
- # Parts, joined on read: ``+=`` on an attribute copies the whole segment per delta (quadratic).
- self._shown, self._spoken = [], []
- self.seen, self.answered, self.gapped = set(), set(), False
- @property
- def shown(self):
- return "".join(self._shown)
- @property
- def spoken(self):
- return "".join(self._spoken)
- def close_segment(self):
- self.seen |= {self.shown.strip(), self.spoken.strip()}
- self._shown, self._spoken = [], []
- class GatewayAgent:
- """Gateway-backed stand-in for ``run_agent.AIAgent`` (constructed at the same call site)."""
- platform = "cli"
- _supports_active_turn_redirect = True
- def __init__(self, *, session_db=None, session_id=None, model=None, provider=None, base_url=None,
- api_mode=None, max_iterations=90, quiet_mode=True, tool_progress_mode="all",
- reasoning_config=None, service_tier=None, clarify_callback=None, connection_callback=None,
- connection_update_callback=None,
- reasoning_callback=None, thinking_callback=None, tool_progress_callback=None,
- tool_start_callback=None, tool_complete_callback=None, stream_delta_callback=None,
- tool_gen_callback=None, notice_callback=None, notice_clear_callback=None,
- reaction_callback=None, interim_assistant_callback=None, connection=None,
- push_reasoning=False, model_confirm_callback=None, modal_withdraw_callback=None,
- one_turn=False, one_turn_reasoning=None, one_turn_alias="", **_ignored):
- conn = connection or getattr(session_db, "connection", None)
- if conn is None:
- raise GatewayClientError("Gateway session unavailable; no local fallback")
- self.connection = conn
- self._session_db = session_db
- self.session_id = session_id
- self.model = model or ""
- self.provider = provider or ""
- self.base_url = base_url or ""
- self.api_mode = api_mode
- self.api_key = None # never on this side of the wire
- self.max_iterations = max_iterations
- self.quiet_mode = quiet_mode
- self._service_tier = None
- self.clarify_callback = clarify_callback
- # The manage_connections card: the gateway runs the operation and streams connection.request /
- # connection.update; the card answers through connection_respond / connection_retry.
- self.connection_callback = connection_callback
- self.connection_update_callback = connection_update_callback
- self._reasoning_callback = None
- self._show_reasoning_sent = None
- self.thinking_callback = thinking_callback
- self.tool_progress_callback = tool_progress_callback
- self.tool_start_callback = tool_start_callback
- self.tool_complete_callback = tool_complete_callback
- self.stream_delta_callback = stream_delta_callback
- self.tool_gen_callback = tool_gen_callback
- self.notice_callback = notice_callback
- self.notice_clear_callback = notice_clear_callback
- self.reaction_callback = reaction_callback
- self.interim_assistant_callback = interim_assistant_callback
- # The CLI's confirm prompt for the owner's model-guard refusal; None where nobody can answer (-q).
- self.model_confirm_callback = model_confirm_callback
- # Closes the CLI's open modal for one server-request method when the gateway withdraws it
- # (``request.cancel``: another viewer answered, the turn ended); called off the agent thread.
- self.modal_withdraw_callback = modal_withdraw_callback
- self._open_request = None # (request id, method) of the server request a modal is answering
- # Set by the CLI after construction: a ``session.control.update`` mid-turn (a tool moved the goal
- # or loop) marks its mirrored managers stale; the dock re-reads them off this thread.
- self.control_update_callback = None
- self.suppress_status_output = False
- self._print_fn = None
- # Inert private attributes main's CLI writes (CALLMAP §3.2).
- self._last_flushed_db_idx = 0
- self._session_messages: list = []
- self._db_flush_scan_prefix = None
- self._persist_user_message_idx = self._persist_user_message_override = None
- self._persist_user_message_timestamp = None
- self._pending_cli_user_message = None
- self._voice_turn_pending = False
- self._auto_load_skills_result = None
- self._auto_load_skills_resolved = False
- self._session_db_created = True
- self._fallback_activated = False
- self._rate_limited_until = None
- self._primary_runtime = None
- self._interrupt_requested = False
- self._active_children: list = []
- self._turn_ask_index = None
- self._usage_stale = False
- self._current_task_id = self._current_turn_id = self._current_api_request_id = ""
- self._memory_manager = None
- self._memory_store = None
- self._checkpoint_mgr = None
- self.context_compressor = _CompressorView()
- self._reset_session_figures()
- # Main's store type, the one /new, /resume and /branch swap in: a read-only mirror of the gateway's
- # todo snapshot (``_set_todos``), read by the pet's done-plan beat.
- from tools.todo_tool import TodoStore
- self._todo_store = TodoStore()
- # Part of the _compress_context seam: it sets the owner's report here and compress_now reads it.
- self.compression_summary = None
- self._generation = None
- self._admission = None
- self._turn = None # a turn a later one replaced stops taking frames
- self._epoch = None # the connection epoch this turn was submitted on
- self._interrupt_sent_at = None
- self._rate_limit_state = None
- self._config_context_length = None
- # Session-scope settings the gateway applies (its turn renders tools in this mode, its agent asks
- # for this effort): written once main's rebuilt agent is ready, then on every change.
- self._tool_progress_mode = "all"
- self.tool_progress_mode = tool_progress_mode
- self._reasoning_config = None
- # Only a user-picked effort (/reasoning, a model pick's --reasoning) is committed at build; the
- # config-resolved level must never override the session's frozen launch policy on resume.
- # ``reasoning_pushed``: the commit landed, so the CLI stops re-sending it on every later rebuild.
- self.reasoning_pushed = False
- if push_reasoning:
- self.reasoning_pushed = self.pin_reasoning(reasoning_config)
- else:
- self._reasoning_config = reasoning_config
- # Main's /moa rebuilds its agent on the MoA virtual provider for one turn (the session's info
- # below then overwrites ``model``): that preset rides the turn's submit as its model_override.
- self._moa_preset = model if provider == "moa" else None
- # ``/model --once``: chat retires the agent that switch_model touched and builds this one.
- # Capture the pick, and the alias it resolved through, before ``_apply_info`` copies the session
- # model over it.
- self._turn_route = self._route_off_session(model, provider, one_turn_alias) if one_turn else None
- self._taken_turn_route = None # the pick the admission being sent took (``_take_turn_route``)
- # ``/model B --once --reasoning X``: X rides that admission's ``model_override``, never a session pin.
- self._turn_reasoning = one_turn_reasoning if one_turn else None
- self._apply_info(self._state().info)
- if self._turn_route:
- self.model = model # the resolved model, never the alias the admission sends
- if self._turn_route.get("provider"):
- self.provider = self._turn_route["provider"]
- self.reasoning_callback = reasoning_callback
- self.service_tier = service_tier
- state = self._state()
- state.usage_listeners.append(self.apply_session_usage)
- state.request_listeners.append(self._on_request_withdrawn)
- if state.usage:
- self.apply_session_usage(state.usage)
- # -- session-scope settings ------------------------------------------------------------------
- @property
- def tool_progress_mode(self):
- return self._tool_progress_mode
- @tool_progress_mode.setter
- def tool_progress_mode(self, mode):
- """``/verbose`` / ``/focus``: ``config.set verbose`` with the explicit mode (never ``cycle``, which
- could drift from the CLI's own cycle)."""
- if mode == self._tool_progress_mode or mode not in {"off", "new", "all", "verbose"}:
- self._tool_progress_mode = mode
- return
- self._tool_progress_mode = mode
- try:
- self.connection.call("config.set", session_id=self.session_id, key="verbose", value=mode)
- except GatewayClientError as exc:
- logger.debug("config.set verbose failed: %s", exc)
- @property
- def reasoning_config(self):
- return self._reasoning_config
- @reasoning_config.setter
- def reasoning_config(self, config):
- """/new's re-derived effort and a one-turn restore: ``session.mutate reasoning`` when it differs from
- the session's effort (an inherited level stays inherited)."""
- self._set_reasoning(config, explicit=False)
- def pin_reasoning(self, config):
- """``/reasoning <level>`` (session scope; main rebuilds its agent with the new config) and a model
- pick's ``--reasoning``: always ``session.mutate reasoning``, even when the session already runs that
- level by inheritance, so it becomes the session's own choice. True when the owner committed it."""
- return self._set_reasoning(config, explicit=True)
- def stage_turn_reasoning(self, config):
- """``/model B --once --reasoning X``: X for the one-turn admission only (its ``model_override``).
- Nothing is sent to the session."""
- self._reasoning_config = config
- self._turn_reasoning = _effort_word(config)
- def restore_reasoning(self, config):
- """A one-turn restore: the level goes back on this object only. The session was never written."""
- self._reasoning_config = config
- self._turn_reasoning = None
- def _set_reasoning(self, config, *, explicit):
- self._reasoning_config = config
- effort = _effort_word(config)
- if effort is None:
- return False
- info = self._state().info or {}
- if not explicit and info.get("reasoning_effort") == effort:
- return True
- try:
- snapshot = self.connection.call("session.resume", session_id=self.session_id)
- # A policy mutation is generation-fenced: the owner refuses it without the generation.
- self.connection.call("session.mutate", session_id=self.session_id, request_id=uuid.uuid4().hex,
- expected_revision=snapshot["revision"],
- expected_generation=snapshot["execution_generation"], operation="reasoning",
- payload={"effort": effort})
- info["reasoning_effort"] = effort
- return True
- except (GatewayClientError, KeyError, TypeError) as exc:
- logger.debug("session.mutate reasoning failed: %s", exc)
- return False
- def _route_off_session(self, model, provider="", alias=""):
- """``{model, provider}`` the turn sends when the session runs another route, else None.
- ``alias``, the ``model_aliases`` entry the pick resolved through, is sent instead of the bare
- model: two aliases may name one model at different endpoints, so the owner must not re-resolve
- it. An alias makes even the session's own model a one-turn override."""
- state = self._state()
- if not model or not (state.info or {}).get("model") or (state.runs_route(model, provider) and not alias):
- return None
- return {"model": alias or model, **({"provider": provider} if provider else {})}
- def switch_model(self, new_model, new_provider="", api_key="", base_url="", api_mode="", capabilities=None, *,
- once=False, restore=False, alias=""):
- """Session-scoped ``/model`` and /resume commit ``session.mutate model``.
- ``once=True`` does not write the session. The next ``chat`` builds a new agent; that
- constructor carries the pick, because this agent is retired when the route signature
- changes. ``restore=True`` only puts the previous model back on this object and clears the
- one-turn route. The admission already has its ``model_override``.
- "Already on this route" is the session row, not ``self.model`` (a one-turn pick sets
- ``self.model`` without committing). A session switch of that same target still mutates
- on the generation fence.
- A guarded target the owner refuses with ``confirmation_required`` is re-sent with its token
- only on the user's yes to ``model_confirm_callback``: a no returns False with nothing
- written; with no prompt the refusal raises. Any refusal raises: main's callers roll their
- own fields back."""
- if once or restore:
- # ``alias``: the ``model_aliases`` entry a ``--once`` pick resolved through (``_route_off_session``).
- self._turn_route = None if restore else self._route_off_session(new_model, new_provider, alias)
- if restore:
- self._turn_reasoning = None
- if new_model:
- self.model = new_model
- if new_provider:
- self.provider = new_provider
- return True
- if new_model == self.model and (not new_provider or new_provider == self.provider):
- if self._route_off_session(new_model, new_provider) is None:
- self._turn_route = None
- return True
- from hermes_cli.gateway_mutations import model_refusal_text
- payload = {"model": new_model, **({"provider": new_provider} if new_provider else {})}
- snapshot = self.connection.call("session.resume", session_id=self.session_id)
- fence = dict(session_id=self.session_id, operation="model", expected_revision=snapshot["revision"],
- expected_generation=snapshot["execution_generation"])
- result = self.connection.call("session.mutate", request_id=uuid.uuid4().hex, payload=payload, **fence) or {}
- if result.get("status") == "confirmation_required":
- if self.model_confirm_callback is None:
- raise GatewayClientError(model_refusal_text(result))
- if not self.model_confirm_callback(result):
- return False
- # The refusal wrote nothing: the same fence is re-sent with the owner's token.
- result = self.connection.call("session.mutate", request_id=uuid.uuid4().hex,
- payload={**payload, "confirm": result["confirm"]}, **fence) or {}
- if result.get("status") == "confirmation_required":
- raise GatewayClientError(model_refusal_text(result, confirmed=True))
- state = self._state()
- try:
- state.adopt_snapshot(self.connection.call("session.resume", session_id=self.session_id))
- except (GatewayClientError, KeyError, TypeError) as exc:
- # Committed: the next turn runs on the new model, so main must not roll its fields back.
- logger.warning("session.resume after the committed model switch failed: %s", exc)
- # A rebuilt stand-in reads the session's info: it must show the committed model.
- provider = result.get("provider") or new_provider
- state.info = {**(state.info or {}), "model": result.get("model") or new_model,
- **({"provider": provider} if provider else {})}
- # The session now runs this route, so a leftover one-turn override must not ride the next submit.
- self._turn_route = None
- self._apply_info(state.info)
- return True
- # -- session identity ----------------------------------------------------------------------
- @property
- def _todo_store(self):
- return self._todos
- @_todo_store.setter
- def _todo_store(self, store):
- """Main swaps in a fresh ``TodoStore`` after /new, /resume and /branch move ``session_id`` (and the
- constructor builds one): it starts with the gateway's snapshot of that session, so a resumed
- plan is there before its next ``todo.updated``."""
- self._todos = store
- snapshot = self._state().todo_state
- if snapshot:
- self._set_todos(snapshot)
- @property
- def session_id(self):
- return self._session_id
- @session_id.setter
- def session_id(self, value):
- """Main repoints ``agent.session_id`` on /new, /resume and /branch: attach this viewer to that
- gateway session (idempotent) and read its state from then on."""
- previous = getattr(self, "_session_id", None)
- self._session_id = value
- if previous is None or value == previous or not value:
- return
- # The session left behind keeps its own figures: a later frame of its must not repaint this one.
- left = self.connection.state(previous)
- with suppress(ValueError):
- left.usage_listeners.remove(self.apply_session_usage)
- with suppress(ValueError):
- left.request_listeners.remove(self._on_request_withdrawn)
- store = self._session_db
- if store is not None and hasattr(store, "attach"):
- try:
- store.attach(value)
- except GatewayClientError as exc:
- logger.debug("session.resume %s failed: %s", value, exc)
- else:
- try:
- self.connection.call("session.resume", session_id=value)
- except GatewayClientError as exc:
- logger.debug("session.resume %s failed: %s", value, exc)
- state = self._state()
- if self.apply_session_usage not in state.usage_listeners:
- state.usage_listeners.append(self.apply_session_usage)
- if self._on_request_withdrawn not in state.request_listeners:
- state.request_listeners.append(self._on_request_withdrawn)
- self._apply_info(state.info)
- if state.usage:
- self.apply_session_usage(state.usage)
- self._sync_show_reasoning()
- notice = self._lost_turn_notice()
- if notice:
- self._emit_print(notice)
- # -- reasoning display -------------------------------------------------------------------
- @property
- def reasoning_callback(self):
- return self._reasoning_callback
- @reasoning_callback.setter
- def reasoning_callback(self, callback):
- """Main installs a reasoning sink at construction and on ``/reasoning show|hide`` / verbose; the
- sink's presence is what makes the agent ask the provider for reasoning. The gateway agent
- gets the same switch: the session's ``show_reasoning`` display flag, sent on each change."""
- self._reasoning_callback = callback
- self._sync_show_reasoning()
- def _sync_show_reasoning(self):
- """Sent unless this viewer already set the value: a session it attaches (/new, /resume, /branch)
- may hold another viewer's "1". A "0" outlives a redial (a restarted gateway starts with the
- flag unset, read as off); a "1" is set again on each gateway life."""
- show = self._reasoning_callback is not None
- sent = self._show_reasoning_sent
- if sent and sent[:2] == (self.session_id, show) and (not show or sent[2] == self.connection.epoch):
- return
- try:
- self.connection.call("config.set", session_id=self.session_id, key="show_reasoning",
- value="1" if show else "0", timeout=10)
- except GatewayClientError as exc:
- logger.debug("config.set show_reasoning failed: %s", exc)
- return
- self._show_reasoning_sent = (self.session_id, show, self.connection.epoch)
- @property
- def service_tier(self):
- return self._service_tier
- @service_tier.setter
- def service_tier(self, tier):
- """Main rebuilds AIAgent(service_tier=...) after ``/fast``; the gateway agent gets the same tier
- as the session's override (``config.set service_tier``), sent when it differs from the last
- one sent for this session. The session's own default (None at first build) is left alone."""
- self._service_tier = tier
- # Remembered on the session's shared state: /fast rebuilds this stand-in, the session stays.
- state = self._state()
- wanted = tier or "normal"
- sent = getattr(state, "service_tier_sent", None)
- if wanted == sent or (sent is None and not tier):
- return
- try:
- self.connection.call("config.set", session_id=self.session_id, key="service_tier",
- value=wanted, timeout=10)
- except GatewayClientError as exc:
- logger.debug("config.set service_tier failed: %s", exc)
- return
- state.service_tier_sent = wanted
- # -- snapshot-backed reads ---------------------------------------------------------------
- def _state(self):
- return self.connection.state(self.session_id)
- def _apply_info(self, info):
- info = info or {}
- if info.get("model"):
- self.model = info["model"]
- if info.get("provider"):
- self.provider = info["provider"]
- if info.get("context_length"):
- self.context_compressor.context_length = int(info["context_length"])
- @property
- def tools(self):
- """Tool schemas the gateway session will load (``info.tools`` {toolset: [names]})."""
- groups = (self._state().info or {}).get("tools") or {}
- names = [name for members in groups.values() for name in (members or [])]
- return [{"type": "function", "function": {"name": name}} for name in names]
- @property
- def valid_tool_names(self):
- return {tool["function"]["name"] for tool in self.tools}
- def get_rate_limit_state(self):
- return self._rate_limit_state
- def apply_session_usage(self, usage):
- """Install one session-cumulative usage dict (the ``session.usage`` event / ``session.stats``
- result) on main's attributes. Plain assignments: the render thread reads them lock-free."""
- if not isinstance(usage, dict):
- return
- for attr, key in _COUNTER_FROM_USAGE.items():
- value = usage.get(key)
- if isinstance(value, int) and not isinstance(value, bool):
- setattr(self, attr, value)
- compressor = self.context_compressor
- if isinstance(usage.get("last_prompt_tokens"), int):
- compressor.last_prompt_tokens = usage["last_prompt_tokens"]
- if usage.get("context_length"):
- compressor.context_length = int(usage["context_length"])
- if "config_context_length" in usage:
- pin = usage.get("config_context_length")
- compressor._config_context_length = self._config_context_length = pin if isinstance(pin, int) else None
- if isinstance(usage.get("compression_count"), int):
- compressor.compression_count = usage["compression_count"]
- source = usage.get("context_source")
- if source is not None:
- # context_display_source(): a "local_estimate" reading is a shown value != the real one.
- compressor.last_real_prompt_tokens = (
- None if source == "provider_usage" else compressor.last_prompt_tokens + 1)
- if isinstance(usage.get("context_tokens"), int):
- self._context_tokens = usage["context_tokens"]
- self._anchor_display()
- latency, tps = usage.get("avg_latency_s"), usage.get("tokens_per_s")
- if isinstance(latency, (int, float)) and latency > 0 and isinstance(tps, (int, float)):
- # The bar averages these deques (mean latency, sum/sum velocity): one aligned sample each.
- self._api_latency_history = [float(latency)]
- self._api_output_history = [float(tps) * float(latency)]
- if "rate_limit" in usage:
- self._rate_limit_state = _rate_limit_state(usage.get("rate_limit"))
- if usage.get("model"):
- self.model = usage["model"]
- if usage.get("provider"):
- self.provider = usage["provider"]
- # -- no-ops: the gateway owns persistence, prompt cache, memory and clients --------------
- def _flush_messages_to_session_db(self, *a, **k):
- return None
- def _persist_session(self, *a, **k):
- return None
- def _ensure_db_session(self, *a, **k):
- return None
- def _invalidate_system_prompt(self, *a, **k):
- return None
- def _reset_session_figures(self):
- """Zero the per-session figures main's bar, spinner and /usage read (context length stays)."""
- for attr in _COUNTER_FROM_USAGE:
- setattr(self, attr, 0)
- compressor = self.context_compressor
- compressor.last_prompt_tokens, compressor.last_real_prompt_tokens, compressor.compression_count = 0, None, 0
- self._context_tokens = self._turn_calls_base = 0
- self._turn_base_usage_anchor = self._turn_api_calls = None
- self._api_latency_history, self._api_output_history = [], []
- def reset_session_state(self, *a, **k):
- """/new, /resume and /branch, after the ``session_id`` switch: drop the previous session's
- figures, then show the gateway's for this one (``session.stats``, else its cached
- ``session.usage``). A brand-new session (no transcript, no usage yet) reads zero until its
- first turn publishes, without a round trip."""
- self._reset_session_figures()
- state = self._state()
- if not (state.messages or state.usage):
- return
- if not self._refresh_stats() and state.usage:
- self.apply_session_usage(state.usage)
- def release_clients(self, *a, **k):
- return None
- def clear_interrupt(self, *a, **k):
- self._interrupt_requested = False
- def shutdown_memory_provider(self, *a, **k):
- return None
- def close(self, *a, **k):
- return None
- def _restore_primary_runtime(self, *a, **k):
- return None
- def _summarize_api_error(self, exc):
- return str(exc)[:300]
- # -- controls ------------------------------------------------------------------------------
- def interrupt(self, message=None):
- """``session.interrupt`` for the running generation; ``message`` stays CLI-side (main
- re-queues it as the next turn itself)."""
- self._interrupt_requested = True
- if self._interrupt_sent_at is None:
- self._interrupt_sent_at = time.monotonic()
- generation = self._generation
- if generation is None:
- generation = self._state().execution_generation
- try:
- self.connection.call("session.interrupt", session_id=self.session_id,
- execution_generation=generation, timeout=5)
- except Exception as exc: # health: allow BLE001 -- the settle wait below bounds a lost interrupt
- logger.debug("session.interrupt failed: %s", exc)
- def hard_interrupt(self, message=None, tool_reason=None):
- self.interrupt(message)
- def _correct(self, verb, text):
- """-> ``True`` (accepted), ``False`` (not taken: the caller queues the text), or
- ``"voice_stopped"`` (TUI-26: the owner took a bare stop phrase as the end of this LOCAL
- session's voice chat; the text is consumed and reaches no turn, so it is never re-queued)."""
- generation = self._generation
- if generation is None:
- return False
- try:
- result = self.connection.call(f"session.{verb}", session_id=self.session_id, text=text,
- execution_generation=generation)
- except GatewayClientError:
- return False
- if (result or {}).get("voice_stopped") is True:
- from agent.i18n import t
- self._emit_print(t("cli.voice.stop_phrase_typed"))
- return VOICE_STOPPED
- return (result or {}).get("status") in {"queued", "redirected"}
- def _compress_context(self, messages, system_message=None, *, approx_tokens=None, focus_topic=None,
- force=True, verbatim_tail=None, **_kw):
- """Main's manual ``/compress`` seam (``compress_now``) as ``session.mutate compress``: the
- gateway summarizes and commits; the returned transcript is the gateway's compacted history.
- ``verbatim_tail`` rows are stamped as stored, so ``compress_now`` does not rejoin them.
- The gateway's own report (``summary``: flags and note (with the reason)) is kept for ``compress_now``;
- a ``noop`` answer (a failed summary or nothing removable) committed nothing, so the history,
- the tail and the compression count stay as they were."""
- from agent.context_compressor import _DB_PERSISTED_MARKER
- from agent.conversation_compression import COMPACTION_STATUS
- from hermes_cli.gateway_client import COMPRESS_RPC_TIMEOUT
- payload = {}
- if focus_topic:
- payload["focus"] = focus_topic
- if verbatim_tail:
- payload["partial"] = True
- payload["keep_last"] = max(1, sum(1 for m in verbatim_tail if m.get("role") == "user"))
- self._emit_print(COMPACTION_STATUS)
- self.compression_summary = None
- snapshot = self.connection.call("session.resume", session_id=self.session_id)
- result = self.connection.call("session.mutate", timeout=COMPRESS_RPC_TIMEOUT, session_id=self.session_id,
- request_id=uuid.uuid4().hex, expected_revision=snapshot["revision"],
- expected_generation=snapshot["execution_generation"],
- operation="compress", payload=payload) or {}
- if isinstance(result.get("summary"), dict):
- self.compression_summary = result["summary"]
- if result.get("status") == "noop":
- return list(messages), system_message
- for row in verbatim_tail or ():
- row[_DB_PERSISTED_MARKER] = True
- after = self.connection.call("session.resume", session_id=self.session_id)
- self._state().adopt_snapshot(after)
- compressor = self.context_compressor
- compressor.compression_count += 1
- compressor.last_prompt_tokens = -1
- self._turn_base_usage_anchor = None
- return [{k: v for k, v in m.items() if k != "row_id"} for m in after.get("messages") or []
- if not m.get("archived")], system_message
- def steer(self, text):
- return self._correct("steer", text)
- def redirect(self, text):
- accepted = self._correct("redirect", text)
- if accepted is True:
- # Main's turn then answers the redirect row first (the interrupted call has no usage), so
- # its anchor is priced through that row: it, not the original ask, is the turn's ask.
- self._turn_ask_index = None
- return accepted
- # -- the turn ------------------------------------------------------------------------------
- def _submit_params(self, user_message, persist_user_message, turn_author):
- attachments = None
- if isinstance(user_message, list):
- # Main's native image turn: OpenAI content parts built from local files. The gateway takes
- # text plus staged attachments and routes the images itself (native or described).
- user_message, attachments = self._stage_content_parts(user_message)
- if isinstance(persist_user_message, list):
- persist_user_message = user_message
- text = persist_user_message if isinstance(persist_user_message, str) else user_message
- params = {"session_id": self.session_id, "submission_id": uuid.uuid4().hex, "text": text}
- if attachments:
- params["attachments"] = attachments
- if isinstance(user_message, str) and user_message != text:
- params["api_text"] = user_message
- if turn_author:
- params["turn_author"] = turn_author
- if self._voice_turn_pending:
- params["voice_turn"] = True
- staged = self._pending_cli_user_message
- if isinstance(staged, dict) and staged.get("display_kind"):
- params["display_kind"] = staged["display_kind"]
- if getattr(self, "_finite", False):
- params["finite"] = True
- if self.clarify_callback is not None:
- # Main's batch panel answers the clarify tool's whole question set (one ``clarify`` request).
- params["clarify_batch"] = True
- info = self._state().info or {}
- pending = self._take_turn_route()
- if pending:
- # /model --once: this admission alone runs the pick. The session row stays put.
- params["model_override"] = pending
- elif self._moa_preset and (info.get("provider"), info.get("model")) != ("moa", self._moa_preset):
- # /moa one-shot: this admission alone runs the preset (unless it is the session's own
- # route); the session's route is untouched.
- params["model_override"] = {"model": self._moa_preset, "provider": "moa"}
- return params
- def _take_turn_route(self):
- """The ``/model --once`` pick for the admission being built, consumed here: one admission carries
- it, even when a later ``run_conversation`` submits while this one's ``prompt.submit`` still blocks.
- A refusal that admitted nothing (``session_busy``) puts it back with ``_give_back_turn_route``.
- Staging already compared the pick with the session's route (``_route_off_session``), so it is not
- compared again: its ``model`` may be an alias spelled like the session's model, and the owner runs a
- plain pick of the session's own route on the session's endpoint and key (``one_turn_runtime``)."""
- pending, reasoning = self._turn_route, self._turn_reasoning
- self._turn_route = self._turn_reasoning = self._taken_turn_route = None
- if not pending:
- return None
- self._taken_turn_route = (pending, reasoning)
- return {**pending, **({"reasoning": reasoning} if reasoning else {})}
- def _give_back_turn_route(self):
- taken, self._taken_turn_route = getattr(self, "_taken_turn_route", None), None
- if taken and self._turn_route is None:
- self._turn_route, self._turn_reasoning = taken
- def _stage_content_parts(self, parts):
- """``[{type: text}, {type: image_url, image_url: {url: data:...}}]`` -> (text, attachments): each
- image is staged on the owner with ``image.attach_bytes`` (bytes read here, locally, by main's
- ``build_native_content_parts``); main's ``[Image attached at: <local path>]`` hints are dropped
- because the gateway names its own staged copies."""
- texts, attachments = [], []
- for part in parts:
- if not isinstance(part, dict):
- continue
- if part.get("type") == "text":
- lines = str(part.get("text") or "").splitlines()
- texts.append("\n".join(ln for ln in lines if not ln.startswith("[Image attached")).strip())
- elif part.get("type") == "image_url":
- url = (part.get("image_url") or {}).get("url") if isinstance(part.get("image_url"), dict) else None
- if isinstance(url, str) and url.startswith("data:image/"):
- staged = self.connection.call("image.attach_bytes", session_id=self.session_id, content_base64=url)
- attachments.append({"path": staged["path"], "mime": staged["mime"]})
- return "\n\n".join(t for t in texts if t), attachments
- def run_conversation(self, user_message, conversation_history=None, stream_callback=None,
- task_id=None, persist_user_message=None, turn_author=None, **_kw):
- turn = self._turn = _Turn(self.session_id) # first: a turn main gave up on stops consuming
- history = list(conversation_history or [])
- self._turn_ask_index = len(history) # the staged ask's row in this turn's transcript
- self._turn_api_calls = None
- self._turn_calls_base = self.session_api_calls
- self._usage_stale = True
- self._interrupt_requested = False
- self._interrupt_sent_at = None
- from hermes_cli.gateway_tools_notify import take_admitted_turn
- adopted = take_admitted_turn(self, persist_user_message if isinstance(persist_user_message, str)
- else user_message)
- if adopted is not None:
- # A turn the gateway already admitted and is running (its frames are queued). A recovered
- # ``/queue`` turn missed some frames: its reply is completed from the receipt.
- receipt = adopted
- turn.gapped = bool(adopted.get("recovered"))
- else:
- self._drain_stale()
- self._taken_turn_route = None
- try:
- # Inside the try: staging an image is a gateway call, and its failure is a failed turn.
- # Building the params consumes a ``/model --once`` pick (``_take_turn_route``).
- notice = self._prepare_submit(turn)
- if notice:
- return self._unadmitted(history, user_message, notice)
- params = self._submit_params(user_message, persist_user_message, turn_author)
- if self._stop(turn)():
- raise CallStopped("prompt.submit")
- receipt = self.connection.call("prompt.submit", **{**params, "session_id": turn.session_id})
- except CallStopped: # main moved on (a later turn, /new, Ctrl-C's bound) before the submit
- self._give_back_turn_route() # nothing was sent: the pick is still owed
- return self._failed(history, user_message, "Stopped before the prompt was sent; nothing was sent.")
- except GatewayRPCError as exc:
- # The owner answered and refused: not a lost connection. Only its own site code
- # (session_busy: send again) is a verdict; any other refusal stays unclassified.
- busy = str(exc) == "session_busy"
- if busy:
- # Nothing was admitted: the resend carries the pick (the CLI keeps its restore).
- self._give_back_turn_route()
- return self._failed(history, user_message, str(exc),
- failure_reason="session_busy" if busy else None, retryable=busy)
- except GatewayClientError as exc:
- if str(exc) == NOT_SENT:
- return self._unadmitted(history, user_message, str(exc))
- return self._failed(history, user_message, str(exc), failure_reason="gateway_connection")
- if (receipt or {}).get("voice_stopped") is True:
- return self._voice_stopped(history)
- self._epoch = getattr(self.connection, "epoch", None)
- turn.admission = self._admission = (receipt or {}).get("admission_id")
- if receipt and receipt.get("execution_generation") is not None:
- self._generation = receipt["execution_generation"]
- starts: dict = {}
- try:
- settled = (adopted or {}).get("receipt")
- outcome = {"_receipt": settled} if settled else self._pump(stream_callback, starts, turn)
- finally:
- if self._owns(turn):
- self._generation_done()
- if isinstance(outcome, Exception) and self._owns(turn):
- return self._failed(history, user_message, str(outcome) or DISCONNECTED,
- failure_reason="gateway_connection")
- result = self._result(history, user_message, outcome, turn) if self._owns(turn) else None
- if not self._owns(turn): # a later turn or a session switch took over: it reads and paints nothing
- return self._failed(history, user_message, "A later turn took over this terminal.")
- if turn.gapped:
- self._paint_owed(turn, result, outcome, stream_callback)
- return result
- def _drain_stale(self):
- """Frames left from an earlier turn of this viewer (a late settlement) are not this turn's. A
- ``/queue`` admission's start among them is remembered: that turn is painted after this one."""
- from hermes_cli.gateway_tools_notify import missed_start
- while True:
- try:
- frame = self.connection.events.get_nowait()
- except queue.Empty:
- return
- if isinstance(frame, Exception):
- if lost_before(frame, getattr(self.connection, "epoch", None)):
- continue # a connection a reconnect already replaced
- self.connection.events.put(frame)
- return
- params = frame.get("params") if isinstance(frame, dict) else None
- if isinstance(params, dict) and params.get("session_id") == self.session_id:
- missed_start(self._state(), params)
- def _generation_done(self):
- self._generation = None
- def _expired(self):
- return self._interrupt_sent_at is not None and time.monotonic() - self._interrupt_sent_at > INTERRUPT_SETTLE_SECONDS
- def _owns(self, turn):
- return self._turn is turn and self.session_id == turn.session_id
- def _stop(self, turn):
- """The ``abandon`` of a turn's blocking reads: it lost the terminal, or Ctrl-C's settle bound passed."""
- return lambda: not self._owns(turn) or self._expired()
- def _lost(self, turn):
- """The ``abandon`` of a turn's end-of-turn reads (its receipt, the cumulative stats): only losing the
- terminal stops them. Past Ctrl-C's settle bound they still run, bounded by their own timeouts."""
- return lambda: not self._owns(turn)
- def _prepare_submit(self, turn):
- """Before a prompt is sent: re-attach after a replay gap, give a redialled (restarted) owner the
- reasoning flag again, and return the notice of a turn lost in that restart: a prompt queued
- behind it would wait with no end, so it is refused until ``/discard``."""
- state = self._state()
- if state.gaps != state.attached_gaps: # a replay gap between turns retired the subscription
- self.connection.reattach(turn.session_id, abandon=self._stop(turn))
- self.connection.start()
- self._sync_show_reasoning()
- notice = self._lost_turn_notice()
- return f"Your message was not sent.\n{notice}" if notice else ""
- def _lost_turn_notice(self):
- from hermes_cli.gateway_chat_view import pending_lines
- pending = self._state().pending
- return "\n".join(pending_lines(pending)) if any(row["status"] == "unknown" for row in pending) else ""
- def _pump(self, stream_callback, starts, turn):
- """Dispatch frames until this admission's ``message.complete``; returns its payload, or the
- transport error (disconnect)."""
- events = self.connection.events
- while self._owns(turn):
- if self._expired():
- return {"status": "interrupted", "outcome": "cancelled", "_settle_timeout": True}
- try:
- frame = events.get(timeout=_POLL)
- except queue.Empty:
- continue
- if not self._owns(turn):
- with events.mutex: # the later turn's frame goes back where it was
- events.queue.appendleft(frame)
- break
- if isinstance(frame, Exception):
- if lost_before(frame, self._epoch):
- continue # the previous connection's loss, already reported; this turn is live
- return frame
- params = frame.get("params") if isinstance(frame, dict) else None
- if not isinstance(params, dict) or params.get("session_id") != self.session_id:
- continue
- if frame.get("method") in _SERVER_REQUESTS and "id" in frame:
- self._answer_request(frame)
- continue
- kind, payload = params.get("type"), params.get("payload") or {}
- admission = params.get("admission_id") or (payload.get("admission_id") if isinstance(payload, dict) else None)
- if self._admission and admission and admission != self._admission:
- from hermes_cli.gateway_tools_notify import missed_start
- missed_start(self._state(), params) # a /queue turn run ahead of this one: painted after it
- continue
- if params.get("execution_generation") is not None:
- self._generation = params["execution_generation"]
- self._state().execution_generation = params["execution_generation"]
- if kind == "message.complete":
- return payload
- if kind == "session.replay_gap":
- outcome = self._recover(turn)
- if outcome is not None:
- return outcome
- continue
- try:
- self._dispatch(kind, payload, stream_callback, starts)
- except Exception:
- logger.debug("event %s dispatch failed", kind, exc_info=True)
- return None
- def _recover(self, turn):
- """``gateway_replay_gap``: re-attach, answer the controls the hole hid, stop painting live text. A
- turn the snapshot no longer lists settles from its receipt; None waits for the live completion."""
- from hermes_cli.gateway_replay_gap import settled
- lost, stop = GatewayClientError("session_replay_gap: " + DISCONNECTED), self._stop(turn)
- try:
- snapshot = self.connection.reattach(turn.session_id, abandon=stop)
- row = next((r for r in snapshot.get("pending") or [] if r.get("admission_id") == turn.admission), {})
- if row.get("status") == "unknown":
- return lost # its completion was the one the hole lost: no other is owed
- turn.gapped |= row.get("status") != "queued" # one still queued lost nothing
- self._restore_connection_card(snapshot.get("pending_connection"))
- for prompt in snapshot.get("prompts") or []:
- if row.get("status") == "started" and prompt.get("execution_generation") == row.get("execution_generation") \
- and prompt.get("prompt_id") not in turn.answered and not stop():
- turn.answered.add(prompt.get("prompt_id"))
- try:
- self._dispatch(f"{prompt.get('kind')}.request", prompt, None, {})
- except Exception: # a broken modal is a skipped answer, never a failed turn
- logger.debug("control %s dispatch failed", prompt.get("prompt_id"), exc_info=True)
- if row or not turn.admission or stop():
- return None
- receipt = self.connection.call("prompt.receipt", session_id=turn.session_id, admission_id=turn.admission,
- include_result=True, abandon=stop)
- except CallStopped:
- return None
- except GatewayClientError:
- return lost
- verdict = settled(receipt or {})
- return {"_receipt": receipt} if verdict else lost if verdict is None else None
- def _dispatch(self, kind, payload, stream_callback, starts):
- handler = _HANDLERS.get(kind)
- if handler is not None:
- handler(self, payload, stream_callback, starts)
- # event handlers (agent thread) ------------------------------------------------------------
- def _on_delta(self, payload, stream_callback, starts):
- text, turn = payload.get("text"), self._turn
- if not isinstance(text, str):
- return self._close_segment(starts, separator=True)
- if turn.gapped:
- return # live text stopped at the replay gap; the settlement shows the reply once
- if self.stream_delta_callback is not None:
- self.stream_delta_callback(text)
- turn._shown.append(text)
- if stream_callback is not None:
- stream_callback(text)
- turn._spoken.append(text)
- def _close_segment(self, starts, separator=False):
- """A segment boundary: the ``text: None`` separator, or a later boundary when it fell in a gap."""
- turn = self._turn
- if self.stream_delta_callback is not None and (separator or any(turn._shown)):
- self.stream_delta_callback(None)
- turn.close_segment()
- def _on_interim(self, payload, stream_callback, starts):
- text = payload.get("text")
- self._close_segment(starts)
- self._turn.seen.add(str(text or "").strip())
- if self.interim_assistant_callback is not None:
- self.interim_assistant_callback(text, already_streamed=bool(payload.get("already_streamed")))
- elif text and str(text).strip():
- self._emit_print(text)
- def _on_tool_generating(self, payload, stream_callback, starts):
- if self.tool_gen_callback is not None:
- self.tool_gen_callback(payload.get("name"))
- def _on_tool_progress(self, payload, stream_callback, starts):
- if self.tool_progress_callback is not None:
- self.tool_progress_callback("tool.progress", payload.get("name"), payload.get("message"), None,
- tool_call_id=payload.get("tool_id"), progress=payload.get("progress"),
- total=payload.get("total"), percent=payload.get("percent"))
- def _on_tool_start(self, payload, stream_callback, starts):
- self._close_segment(starts)
- name = payload.get("name") or payload.get("tool_name") or "tool"
- args = payload.get("args") if isinstance(payload.get("args"), dict) else {}
- call_id = payload.get("tool_id") or payload.get("tool_call_id") or ""
- starts[call_id] = time.monotonic()
- if self._usage_stale:
- # Main's counters move right after each API call, before its tools run (the spinner's
- # `↓ N tok` beside a tool or approval); the gateway's next session.usage frame comes only
- # at the next step, so the first tool of each batch reads session.stats once.
- self._usage_stale = False
- self._refresh_stats()
- if self.tool_progress_callback is not None:
- from agent.display import build_tool_preview
- self.tool_progress_callback("tool.started", name, build_tool_preview(name, args), args)
- # No tool_start_callback: main's snapshots the local FS for inline diffs; the gateway
- # snapshots before its tool writes and ships ``tool.complete.inline_diff`` instead.
- def _on_tool_complete(self, payload, stream_callback, starts):
- name = payload.get("name") or payload.get("tool_name") or "tool"
- args = payload.get("args") if isinstance(payload.get("args"), dict) else {}
- call_id = payload.get("tool_id") or payload.get("tool_call_id") or ""
- result = payload.get("result")
- duration = payload.get("duration_s")
- if duration is None:
- started = starts.pop(call_id, None)
- duration = (time.monotonic() - started) if started is not None else 0.0
- if self.tool_progress_callback is not None:
- self.tool_progress_callback("tool.completed", name, None, None, duration=duration,
- is_error=bool(payload.get("is_error")), result=result)
- self._usage_stale = True
- from hermes_cli.gateway_tools import mark_dirty
- mark_dirty() # a terminal/process call may have started or stopped a background process
- if name == "todo":
- self._todo_from_result(result)
- diff = payload.get("inline_diff")
- if isinstance(diff, str) and diff:
- from cli import _cprint
- from hermes_cli.cli_modern_layout import diff_printer
- emit = diff_printer(_cprint)
- for line in diff.rstrip("\n").splitlines():
- emit(line)
- if name == "delegate_task" and self.tool_complete_callback is not None:
- self.tool_complete_callback(call_id, name, args, result)
- elif self.tool_complete_callback is not None:
- self.tool_complete_callback(call_id, name, args, result)
- def _todo_from_result(self, result):
- try:
- data = json.loads(result) if isinstance(result, str) else result
- except ValueError:
- return
- if isinstance(data, dict):
- self._set_todos(data)
- def _on_todo(self, payload, stream_callback, starts):
- self._set_todos(payload)
- def _set_todos(self, snapshot):
- """The gateway's ``{todos, revision}`` into the CLI's ``TodoStore`` (``restore``: no new revision)."""
- if isinstance(snapshot.get("todos"), list):
- try:
- self._todo_store.restore(snapshot["todos"], revision=snapshot.get("revision"))
- except (ValueError, TypeError) as exc:
- logger.debug("todo snapshot not mirrored: %s", exc)
- def _on_control_update(self, payload, stream_callback, starts):
- if self.control_update_callback is not None:
- self.control_update_callback()
- def _on_thinking(self, payload, stream_callback, starts):
- if self.thinking_callback is not None:
- self.thinking_callback(payload.get("text") or "")
- def _on_reasoning(self, payload, stream_callback, starts):
- if self.reasoning_callback is not None:
- self.reasoning_callback(payload.get("text") or "")
- def _on_reasoning_available(self, payload, stream_callback, starts):
- if self.tool_progress_callback is not None:
- self.tool_progress_callback("reasoning.available", "_thinking", (payload.get("text") or "")[:500], None)
- def _on_notice(self, payload, stream_callback, starts):
- if self.notice_callback is None:
- return
- from agent.credits_tracker import AgentNotice
- self.notice_callback(AgentNotice(text=str(payload.get("text") or ""), level=payload.get("level") or "info",
- kind=payload.get("kind") or "sticky", ttl_ms=payload.get("ttl_ms"),
- key=payload.get("key"), id=payload.get("id")))
- def _on_notice_clear(self, payload, stream_callback, starts):
- if self.notice_clear_callback is not None:
- self.notice_clear_callback(payload.get("key"))
- def _on_reaction(self, payload, stream_callback, starts):
- if self.reaction_callback is not None:
- self.reaction_callback(payload.get("kind"))
- def _on_print(self, payload, stream_callback, starts):
- self._emit_print(payload.get("text") or "")
- def _on_review_summary(self, payload, stream_callback, starts):
- line = review_summary_line(payload)
- if line:
- self._emit_print(line)
- def _emit_print(self, text):
- if self.suppress_status_output:
- return
- (self._print_fn or print)(text)
- def _on_approval(self, payload, stream_callback, starts):
- from tools.terminal_tool import _get_approval_callback
- callback = _get_approval_callback()
- choices = list(payload.get("choices") or [])
- choice = "deny"
- if callback is not None:
- try:
- choice = callback(payload.get("command") or "", payload.get("description") or "",
- allow_permanent="always" in choices, allow_session="session" in choices,
- smart_denied=False)
- except TypeError:
- choice = callback(payload.get("command") or "", payload.get("description") or "")
- if choice not in choices:
- choice = "deny"
- self.connection.call("approval.respond", session_id=self.session_id,
- execution_generation=payload.get("execution_generation", self._generation),
- prompt_id=payload.get("prompt_id"), choice=choice)
- def _on_clarify(self, payload, stream_callback, starts):
- answer = ""
- if self.clarify_callback is not None:
- qid = payload.get("prompt_id") or "q0"
- reply = self.clarify_callback([{"qid": qid, "question": payload.get("question") or "",
- "choices": list(payload.get("choices") or []),
- "multi_select": bool(payload.get("multi_select"))}])
- if isinstance(reply, dict):
- value = (reply.get("answers") or {}).get(qid)
- answer = ", ".join(map(str, value)) if isinstance(value, (list, tuple)) else (value or "")
- elif isinstance(reply, str):
- answer = reply
- self.connection.call("clarify.respond", session_id=self.session_id,
- execution_generation=payload.get("execution_generation", self._generation),
- prompt_id=payload.get("prompt_id"), answer=str(answer))
- def _on_connection_request(self, payload, stream_callback, starts):
- if self.connection_callback is not None:
- self.connection_callback(payload)
- def _on_connection_update(self, payload, stream_callback, starts):
- if self.connection_update_callback is not None:
- self.connection_update_callback(payload)
- def _restore_connection_card(self, pending):
- """After a replay gap, the resume snapshot's open operation: (re)open the card from it, or
- close a stale card when none remains (the gap may have eaten the request or the settle)."""
- if pending:
- if self.connection_callback is not None:
- self.connection_callback(pending)
- elif self.connection_update_callback is not None:
- self.connection_update_callback({"settled": True})
- def connection_respond(self, op_id, result):
- """The card's answer to the gateway's open operation (``connection.respond``); returns its result."""
- return self.connection.call("connection.respond", op_id=op_id, result=result,
- owner={"type": "session", "session_id": self.session_id})
- def connection_retry(self, name):
- """The card's Try again on a failed or expired row: the gateway re-mints it on the open operation."""
- return self.connection.call("connectors.connect", connectors=[name], reconnect=True,
- owner={"type": "session", "session_id": self.session_id})
- def _answer_request(self, frame):
- """A gateway server→client request (``sudo``, ``secret``, the ``vault.*`` prompts, ``clarify``): main's own modal
- answers it on this (agent) thread, through the callback HermesCLI registered for the turn; the
- answer travels only in the JSON-RPC response frame."""
- method = frame["method"]
- self._open_request = (frame["id"], method)
- try:
- answer = _SERVER_REQUESTS[method](self, frame.get("params") or {})
- except Exception: # health: allow BLE001 -- a broken modal is a skip, never a hung tool
- logger.debug("server request %s failed", method, exc_info=True)
- answer = {"outcome": "cancelled"} if method == "clarify" else ""
- finally:
- self._open_request = None
- if method == "clarify":
- self.connection.reply(frame["id"], answer)
- else:
- self.connection.reply(frame["id"], {"value": answer if isinstance(answer, str) else ""})
- def _on_request_withdrawn(self, payload):
- """``request.cancel`` (connection loop thread): the gateway settled or withdrew a request. When
- this agent thread is parked in the modal answering it (another viewer completed the form, the
- turn timed out or was interrupted), release that modal so the pump reads the turn's remaining
- frames; its late reply to the already-settled request is dropped by the gateway."""
- current = self._open_request
- if current is None or payload.get("id") != current[0] or self.modal_withdraw_callback is None:
- return
- try:
- self.modal_withdraw_callback(current[1])
- except Exception: # health: allow BLE001 -- a broken teardown must not stop the connection pump
- logger.debug("modal withdraw for %s failed", current[1], exc_info=True)
- def _ask_clarify(self, params):
- return clarify_reply(self.clarify_callback, params)
- def _ask_sudo(self, params):
- from tools.terminal_tool import _get_sudo_password_callback
- callback = _get_sudo_password_callback()
- return (callback() or "") if callback is not None else ""
- def _ask_secret(self, params):
- """Main's masked "Skill Setup Required" panel (the CLI's registered secret-capture callback,
- ``hermes_cli.callbacks.prompt_for_secret``) collects the value and prints main's lines; the
- gateway, not this process, saves it in the profile ``.env``, so the panel's save is captured."""
- from tools import skills_tool
- callback = skills_tool._secret_capture_callback
- if callback is None:
- return ""
- from hermes_cli import callbacks
- captured = []
- def capture(key, value):
- captured.append(value)
- return {"success": True, "stored_as": key, "validated": False}
- with _SECRET_LOCK:
- saver, callbacks.save_env_value_secure = callbacks.save_env_value_secure, capture
- try:
- callback(params.get("env_var") or "", params.get("prompt") or "", params.get("metadata"))
- finally:
- callbacks.save_env_value_secure = saver
- return captured[0] if captured else ""
- def _ask_vault_unlock(self, params):
- """Main's masked password-manager unlock panel, through the callback HermesCLI registered."""
- from agent.vault_backends.unlock import get_unlock_prompt_callback
- callback = get_unlock_prompt_callback()
- if callback is None:
- return ""
- return callback(str(params.get("backend") or ""), str(params.get("display_name") or "")) or ""
- def _ask_vault_save_login(self, params):
- """Main's two-step "save this login" panel. The gateway stores the login in the vault, so the
- identifier and password go back as one JSON string in the response frame, as the cards send it."""
- from agent.vault_backends.unlock import get_save_login_prompt_callback
- callback = get_save_login_prompt_callback()
- if callback is None:
- return ""
- answer = callback(str(params.get("origin") or ""), str(params.get("site") or ""))
- if not isinstance(answer, dict) or not answer.get("password"):
- return ""
- try:
- return json.dumps({"identifier": str(answer.get("identifier") or ""), "password": str(answer["password"])})
- finally:
- answer.clear()
- def _ask_vault_code(self, params):
- """Main's one-time-code panel, through the callback HermesCLI registered."""
- from agent.vault_backends.unlock import get_code_prompt_callback
- callback = get_code_prompt_callback()
- if callback is None:
- return ""
- return callback(str(params.get("site") or ""), str(params.get("hint") or "")) or ""
- # -- result --------------------------------------------------------------------------------
- def _user_row(self, user_message):
- staged = self._pending_cli_user_message
- if isinstance(staged, dict):
- return staged
- return {"role": "user", "content": user_message}
- def _voice_stopped(self, history):
- """TUI-26: the owner took a bare stop phrase typed into this LOCAL session's voice chat (turned
- on by another viewer) as the end of that chat and admitted nothing, so no ``message.complete``
- will come. The turn ends at once with main's typed-stop notice; the history is unchanged."""
- from agent.i18n import t
- self._give_back_turn_route() # nothing was admitted: a ``/model --once`` pick is still owed
- self._emit_print(t("cli.voice.stop_phrase_typed"))
- return {**_RESULT_DEFAULTS, "messages": list(history), "voice_stopped": True, "session_id": self.session_id}
- def _unadmitted(self, history, user_message, error):
- """A turn the owner never saw (a pre-submit notice, or a submit that was never sent): the CLI
- keeps its local state (no history row, the ``/model --once`` pick and notes) for the resend."""
- self._give_back_turn_route()
- return {**self._failed(history, user_message, error, failure_reason="gateway_connection"),
- "messages": history, "admitted": False}
- def _failed(self, history, user_message, error, *, failure_reason=None, retryable=False):
- """``failure_reason="gateway_connection"``: the CLI shows ``error`` as written instead of
- classifying a lost gateway as a model failure ("Run /model to switch...")."""
- out = {**_RESULT_DEFAULTS, "final_response": "", "messages": history + [self._user_row(user_message)],
- "failed": True, "completed": False, "error": error, "session_id": self.session_id}
- if failure_reason:
- out.update(failure_reason=failure_reason, failure_retryable=retryable)
- return out
- def _result(self, history, user_message, complete, turn):
- receipt = (complete or {}).get("_receipt") or {}
- if receipt: # settled from it after a replay gap
- complete = {"outcome": receipt.get("outcome")}
- elif turn.admission:
- try:
- receipt = self.connection.call("prompt.receipt", session_id=turn.session_id, abandon=self._lost(turn),
- admission_id=turn.admission, include_result=True) or {}
- except GatewayClientError as exc:
- logger.debug("prompt.receipt failed: %s", exc)
- stored = dict(receipt.get("result") or {})
- usage = dict(receipt.get("usage") or {})
- status = (complete or {}).get("status") or (complete or {}).get("outcome")
- out = {**_RESULT_DEFAULTS, **stored}
- if "final_response" not in stored:
- out["final_response"] = (complete or {}).get("text") or (complete or {}).get("content") or ""
- if status in {"interrupted", "cancelled"} or (complete or {}).get("outcome") == "cancelled":
- out["interrupted"] = True
- out["completed"] = False
- elif status in {"error", "failed"} and not stored:
- out.update(failed=True, completed=False)
- suffix = stored.get("messages") if isinstance(stored.get("messages"), list) else None
- if suffix is not None and stored.get("_compressed"):
- out["messages"] = list(suffix)
- else:
- out["messages"] = history + [self._user_row(user_message)] + list(suffix or [])
- if not suffix and out.get("final_response") and not out.get("failed"):
- out["messages"].append({"role": "assistant", "content": out["final_response"]})
- out["session_id"] = self.session_id
- if not self._owns(turn): # taken over during that read: the newer turn's state stays untouched
- return out
- self._session_messages = out["messages"]
- calls = stored.get("api_calls")
- # An interrupted turn's own count includes the attempt Ctrl-C cut off (the agent counts a call
- # before the request goes out). Only a response prices the ask: fall back to the gateway's
- # cumulative count, which moves per response, so an unanswered ask stays main's ``~`` estimate.
- counted = isinstance(calls, int) and not isinstance(calls, bool) and not out.get("interrupted")
- self._turn_api_calls = calls if counted else None
- self._apply_usage(stored, usage, turn)
- return out
- def _paint_owed(self, turn, out, complete, stream_callback):
- """After a replay gap, the reply once (``owed_reply``): a reuse this terminal showed whole stays
- the only copy; otherwise main's panel shows what streaming did not."""
- from hermes_cli.gateway_replay_gap import owed_reply
- reply = out.get("pre_transform_response") if out.get("response_transformed") else None
- reply = reply if isinstance(reply, str) else out.get("final_response")
- if out.get("failed") or not isinstance(reply, str) or not reply.strip():
- return
- reused = out.get("response_previewed") or out.get("response_reused") or complete.get("response_reused")
- out["response_previewed"] = bool(reused) and reply.strip() in turn.seen | {turn.shown.strip(), turn.spoken.strip()}
- for consumer, got in ((self.stream_delta_callback, turn.shown), (stream_callback, turn.spoken)):
- owed = owed_reply(got, reply) if consumer is not None and not out["response_previewed"] else ""
- if owed: # each consumer completes what it got itself, never twice
- consumer(owed)
- def _anchor_display(self):
- """Main's bar shows the anchored ``context_tokens`` by re-deriving it from
- ``_turn_base_usage_anchor`` over ``_session_messages`` (``anchored_context_tokens``), and marks
- it ``~`` when the turn appended rows after its first response. Rebuild an anchor over this
- viewer's transcript that yields the gateway's figure: rows after the first API call of a
- multi-call turn are the estimated delta (main's ``~``); a single reply is covered by the anchor."""
- from agent.model_metadata import estimate_messages_tokens_rough
- from agent.usage_anchor import capture_usage_anchor
- messages = self._session_messages if isinstance(self._session_messages, list) else []
- tokens = getattr(self, "_context_tokens", 0) or 0
- if tokens <= 0 or not messages or self._generation is not None:
- self._turn_base_usage_anchor = None # mid-turn: the bar falls back to last_prompt_tokens
- return
- # Main anchors on the turn's FIRST response, priced over the transcript through the turn's ask.
- # A turn with no completed call (interrupted before a response) keeps the previous anchor, so
- # its ask is estimated delta too.
- # The turn's own ask, never a later user-role row of the same turn (a mid-turn /steer row).
- ask = getattr(self, "_turn_ask_index", None)
- last_user = ask if isinstance(ask, int) and 0 <= ask < len(messages) and messages[ask].get("role") == "user" \
- else next((i for i in range(len(messages) - 1, -1, -1) if messages[i].get("role") == "user"),
- len(messages) - 1)
- # Did this turn complete an API call? The turn result's own count when the gateway sent one: a
- # rebuilt gateway agent (/personality, /model, and /undo, /retry bumping the runtime generation)
- # restarts its session counters, so the cumulative delta can read "no call" for a turn that
- # answered; without that count a LOWER cumulative is a new agent that made calls, never "no call".
- turn_calls = self._turn_api_calls
- calls, turn_base = self.session_api_calls, self._turn_calls_base
- made_call = turn_calls > 0 if isinstance(turn_calls, int) else (calls > turn_base or 0 < calls < turn_base)
- base = last_user + 1 if made_call else last_user
- if base <= 0:
- self._turn_base_usage_anchor = None
- return
- delta = messages[base:]
- if delta and delta[0].get("role") == "assistant":
- delta = delta[1:]
- estimate = estimate_messages_tokens_rough(delta, charge_stale_thinking=False) if delta else 0
- self._turn_base_usage_anchor = capture_usage_anchor(max(1, tokens - estimate), 0, messages[:base])
- def _refresh_stats(self, turn=None):
- """``session.stats`` → the same attributes ``session.usage`` sets; False when unavailable."""
- try:
- stats = self.connection.call("session.stats", session_id=self.session_id, timeout=10,
- abandon=turn and self._lost(turn))
- except GatewayClientError as exc:
- logger.debug("session.stats unavailable: %s", exc)
- return False
- stats = stats.get("usage") if isinstance(stats, dict) and isinstance(stats.get("usage"), dict) else stats
- if not (isinstance(stats, dict) and isinstance(stats.get("api_calls"), int)):
- return False
- if turn is None or self._owns(turn):
- self._state().apply_usage(stats)
- return True
- def _apply_usage(self, stored, receipt_usage, turn):
- """Turn end: the session-cumulative ``session.stats`` (the same dict ``session.usage`` carries);
- a gateway without the verb leaves the per-turn receipt figures as before."""
- if self._refresh_stats(turn) or not self._owns(turn):
- return
- # Fallback: the classic-CLI result carries the gateway agent's session_* counters
- # (turn_finalizer _SESSION_TOKEN_KEYS); per-turn receipt usage only accumulates what is missing.
- usage = {key: stored[key] for key in _COUNTER_FROM_USAGE.values() if isinstance(stored.get(key), int)}
- for key in ("input_tokens", "output_tokens"):
- if key not in usage and isinstance(receipt_usage.get(key), int):
- attr = "session_" + key
- usage[key] = getattr(self, attr) + receipt_usage[key]
- usage.setdefault("prompt_tokens", usage.get("input_tokens"))
- usage.setdefault("completion_tokens", usage.get("output_tokens"))
- if isinstance(usage.get("prompt_tokens"), int) and isinstance(usage.get("completion_tokens"), int):
- usage.setdefault("total_tokens", usage["prompt_tokens"] + usage["completion_tokens"])
- if isinstance(stored.get("api_calls"), int):
- usage["api_calls"] = self.session_api_calls + stored["api_calls"]
- for key in ("last_prompt_tokens", "context_length", "model"):
- if receipt_usage.get(key) or stored.get(key):
- usage[key] = receipt_usage.get(key) or stored.get(key)
- self.apply_session_usage(usage)
- def _effort_word(config):
- """The ``session.mutate reasoning`` effort for main's ``reasoning_config`` dict (None: no override)."""
- if not isinstance(config, dict):
- return None
- if config.get("enabled") is False:
- return "none"
- effort = config.get("effort")
- return effort if isinstance(effort, str) and effort else None
- def _rate_limit_state(data):
- """``get_rate_limit_state()`` rebuilt from its serialized dict (None stays None)."""
- if not isinstance(data, dict):
- return None
- from agent.rate_limit_tracker import RateLimitBucket, RateLimitState
- buckets = {name: RateLimitBucket(**{k: v for k, v in (data.get(name) or {}).items()
- if k in {"limit", "remaining", "reset_seconds", "captured_at"}})
- for name in ("requests_min", "requests_hour", "tokens_min", "tokens_hour")}
- return RateLimitState(**buckets, captured_at=float(data.get("captured_at") or 0.0),
- provider=str(data.get("provider") or ""))
- def review_summary_line(payload):
- """Main's ``display.review.summary_cli`` line for the gateway's ``review.summary`` frame: the background
- review's "💾 Self-improvement review: ..." (``/refine``, the post-turn review), which the gateway
- publishes to a local viewer once the turn settled. None for an empty one."""
- text = str(payload.get("text") or "").strip() if isinstance(payload, dict) else ""
- return f" {text}" if text else None
- def _moa_handler(kind):
- def handler(agent, payload, stream_callback, starts):
- if agent.tool_progress_callback is None:
- return
- extra = {k: v for k, v in payload.items() if k not in {"label", "text", "name", "preview", "index", "count"}}
- # Main's _on_tool_progress reads moa_index / moa_count (the gateway frame uses the TUI keys).
- if payload.get("index") is not None:
- extra["moa_index"] = payload["index"]
- if payload.get("count") is not None:
- extra["moa_count"] = payload["count"]
- agent.tool_progress_callback(kind, payload.get("label") or payload.get("name"),
- payload.get("text") or payload.get("preview"), None, **extra)
- return handler
- def clarify_reply(callback, params) -> dict:
- """Main's batch clarify panel (``callback(questions)``, ``HermesCLI._clarify_callback``) answering a
- ``clarify`` server request's whole question set: its ``ClarifyResult``."""
- questions = [{"qid": q.get("qid"), "question": q.get("question") or "",
- "choices": list(q.get("choices") or []), "multi_select": bool(q.get("multi_select"))}
- for q in params.get("questions") or [] if isinstance(q, dict) and q.get("qid")]
- if callback is None or not questions:
- return {"outcome": "cancelled"}
- reply = callback(questions)
- if not isinstance(reply, dict):
- return {"outcome": "cancelled"}
- answers = {qid: (value if isinstance(value, str) or value is None else json.dumps(value))
- for qid, value in (reply.get("answers") or {}).items()}
- out = {"answers": answers}
- if reply.get("outcome") in ("submitted", "timed_out", "cancelled"):
- out["outcome"] = reply["outcome"]
- return out
- _SECRET_LOCK = threading.Lock()
- _SERVER_REQUESTS = {
- "sudo": GatewayAgent._ask_sudo,
- "secret": GatewayAgent._ask_secret,
- "vault.unlock_prompt": GatewayAgent._ask_vault_unlock,
- "vault.save_login": GatewayAgent._ask_vault_save_login,
- "vault.code": GatewayAgent._ask_vault_code,
- "clarify": GatewayAgent._ask_clarify,
- }
- _HANDLERS = {
- "message.delta": GatewayAgent._on_delta,
- "message.interim": GatewayAgent._on_interim,
- "tool.generating": GatewayAgent._on_tool_generating,
- "tool.progress": GatewayAgent._on_tool_progress,
- "tool.start": GatewayAgent._on_tool_start,
- "tool.complete": GatewayAgent._on_tool_complete,
- "todo.updated": GatewayAgent._on_todo,
- "session.control.update": GatewayAgent._on_control_update,
- "thinking.delta": GatewayAgent._on_thinking,
- "reasoning.delta": GatewayAgent._on_reasoning,
- "reasoning.available": GatewayAgent._on_reasoning_available,
- "moa.reference": _moa_handler("moa.reference"),
- "moa.aggregating": _moa_handler("moa.aggregating"),
- "notification.show": GatewayAgent._on_notice,
- "notification.clear": GatewayAgent._on_notice_clear,
- "reaction": GatewayAgent._on_reaction,
- "agent.print": GatewayAgent._on_print,
- "review.summary": GatewayAgent._on_review_summary,
- "approval.request": GatewayAgent._on_approval,
- "clarify.request": GatewayAgent._on_clarify,
- "connection.request": GatewayAgent._on_connection_request,
- "connection.update": GatewayAgent._on_connection_update,
- }
|