refactor(tui): extract the prompt turn into prompt_turn.py; compact methods_*/session_*/agent_callbacks; split _start_agent_build into scope/wiring helpers

- server.py 7663 -> 5319: _run_prompt_submit and its goal/loop/voice/scope
  phases move to tui_gateway/prompt_turn.py (bound via method_ctx.bind_module);
  _start_agent_build split into _bind/_release_build_profile_scopes,
  _deferred_build_agent_kwargs, _wire_session_agent, _start_session_services;
  _load_enabled_toolsets split (_enabled_mcp_server_names, _resolve_explicit_toolsets).
- methods_slash: _LIVE_SLASH_OUTPUT dispatch table; methods_tools: _SLASH_BUILTINS,
  _guarded; tool_progress: _PROGRESS_HANDLERS; methods_config_set:
  _REASONING_DISPLAY_WORDS; methods_voice: _VOICE_TOGGLE_ACTIONS.
- Unified: _denied_source (methods_session) replaces _WORKER_SOURCES in
  methods_profiles; _compress_live_with_feedback / _compute_host_slash shared by
  the slash mirror and /compress; _end_voice_chat shared by stop-phrase paths;
  _watcher_mtime_ns; _reaper_session_is_detached_idle; _notif_* helpers.
- Dead: _profile_dir_or_err, _resume_info, _slash_builtin_table (refs.py: 0 hits).
- acp_adapter/server.py: docstring compaction only (AST-identical).
- Every file semantically reviewed hunk-by-hunk for wire/log/lock/order parity.
This commit is contained in:
Teknium
2026-09-02 13:22:50 -07:00
parent 2eed968c87
commit 99433742dc
28 changed files with 6856 additions and 11921 deletions
+106 -230
View File
@@ -18,48 +18,15 @@ from urllib.parse import unquote, urlparse
import acp
from acp.schema import (
AgentCapabilities,
AgentMessageChunk,
AuthenticateResponse,
AvailableCommand,
AvailableCommandsUpdate,
BlobResourceContents,
ClientCapabilities,
EmbeddedResourceContentBlock,
ForkSessionResponse,
ImageContentBlock,
AudioContentBlock,
Implementation,
InitializeResponse,
ListSessionsResponse,
LoadSessionResponse,
McpServerHttp,
McpServerSse,
McpServerStdio,
ModelInfo,
NewSessionResponse,
PromptCapabilities,
PromptResponse,
ResumeSessionResponse,
SetSessionConfigOptionResponse,
SetSessionModelResponse,
SetSessionModeResponse,
ResourceContentBlock,
SessionCapabilities,
SessionForkCapabilities,
SessionInfoUpdate,
SessionListCapabilities,
SessionMode,
SessionModeState,
SessionModelState,
SessionResumeCapabilities,
SessionInfo,
TextContentBlock,
TextResourceContents,
UnstructuredCommandInput,
Usage,
UsageUpdate,
UserMessageChunk,
AgentCapabilities, AgentMessageChunk, AudioContentBlock, AuthenticateResponse, AvailableCommand,
AvailableCommandsUpdate, BlobResourceContents, ClientCapabilities, EmbeddedResourceContentBlock,
ForkSessionResponse, ImageContentBlock, Implementation, InitializeResponse, ListSessionsResponse,
LoadSessionResponse, McpServerHttp, McpServerSse, McpServerStdio, ModelInfo, NewSessionResponse,
PromptCapabilities, PromptResponse, ResourceContentBlock, ResumeSessionResponse, SessionCapabilities,
SessionForkCapabilities, SessionInfo, SessionInfoUpdate, SessionListCapabilities, SessionMode,
SessionModeState, SessionModelState, SessionResumeCapabilities, SetSessionConfigOptionResponse,
SetSessionModeResponse, SetSessionModelResponse, TextContentBlock, TextResourceContents,
UnstructuredCommandInput, Usage, UsageUpdate, UserMessageChunk,
)
from acp_adapter.auth import TERMINAL_SETUP_AUTH_METHOD_ID, build_auth_methods, detect_provider
@@ -96,22 +63,13 @@ PromptBlock = (
def _named_custom_provider_catalogs() -> list[tuple[str, str, list[tuple[str, str]]]]:
"""Return ``(slug, label, [(model_id, description), ...])`` for named endpoints.
"""``(slug, label, [(model_id, description), ...])`` for named endpoints (v12 ``providers:``
and legacy ``custom_providers:``), which canonical provider enumeration never lists.
Covers both the v12 ``providers:`` mapping and the legacy ``custom_providers:``
list. These endpoints never appear in canonical provider enumeration, so
without this the ACP model selector hides every named endpoint the TUI
``/model`` picker renders.
Model lists come from the entry's declared models (``default_model`` +
``models``), refreshed from the endpoint's live ``/models`` listing when a
credential is available and ``discover_models`` is not disabled. Declared
models survive a failed live discovery — some OpenAI-compatible endpoints
expose no ``/models`` route yet serve the declared models fine.
Slugs use the ``custom:<name>`` shape that ``parse_model_input`` and
``resolve_runtime_provider`` already resolve, so encoded choice ids
(``custom:<name>:<model>``) round-trip through ``set_session_model``.
Models = the entry's declared models, refreshed from the live ``/models`` listing when a
credential exists and ``discover_models`` isn't disabled; declared models survive a failed
discovery (some endpoints have no ``/models`` route). Slugs use the ``custom:<name>`` shape
``parse_model_input``/``resolve_runtime_provider`` resolve, so choice ids round-trip.
"""
try:
from hermes_cli.config import (
@@ -138,8 +96,7 @@ def _named_custom_provider_catalogs() -> list[tuple[str, str, list[tuple[str, st
logger.debug("Could not load named custom providers", exc_info=True)
return []
# ``get_compatible_custom_providers`` drops the ``enabled`` flag during
# normalization; collect disabled keys from the raw config instead.
# ``get_compatible_custom_providers`` drops ``enabled``; read disabled keys from raw config.
raw_providers = cfg.get("providers") if isinstance(cfg, dict) else None
disabled_keys = {
str(key).strip().lower()
@@ -209,16 +166,13 @@ try:
except Exception:
HERMES_VERSION = "0.0.0"
# Thread pool for running AIAgent (synchronous) in parallel.
# Runs the synchronous AIAgent off the event loop.
_executor = ThreadPoolExecutor(max_workers=4, thread_name_prefix="acp-agent")
# ACP ListSessionsRequest has no client-side limit; clients paginate this fixed
# page via `cursor` / `next_cursor`.
# ListSessionsRequest has no client-side limit; clients paginate via `cursor`/`next_cursor`.
_LIST_SESSIONS_PAGE_SIZE = 50
# Per-provider cap for the ACP model selector: clients (Zed, Buzz) render the
# whole `availableModels` array in one dropdown. Mirrors the MoA picker cap
# (`hermes_cli/moa_cmd.py`). Bounds each provider's row, not the total; the
# current model is always kept via the fallback insert in `_build_model_state`.
# Per-provider row cap (clients render all `availableModels` in one dropdown; mirrors the
# MoA picker cap). Not a total cap; the current model is always kept via the fallback insert.
ACP_MAX_MODELS_PER_PROVIDER = 200
_MAX_ACP_RESOURCE_BYTES = 512 * 1024
_TEXT_RESOURCE_MIME_PREFIXES = ("text/",)
@@ -280,11 +234,8 @@ def _image_data_url(data: bytes, mime_type: str) -> str:
def _path_from_file_uri(uri: str) -> Path | None:
"""Convert local file URIs/paths from ACP clients into a readable Path.
Zed may send POSIX file URIs from Linux/WSL workspaces or Windows-ish paths
when launched through wsl.exe; the Windows drive form becomes /mnt/<drive>/...
"""
"""Local file URI/path from an ACP client -> readable Path (None for non-file URIs).
Windows drive forms (Zed via wsl.exe) become ``/mnt/<drive>/...``."""
raw = (uri or "").strip()
if not raw:
return None
@@ -343,12 +294,8 @@ def _image_parts(uri: str, display: str, data: bytes, mime: str) -> list[dict[st
def _resource_link_to_parts(block: ResourceContentBlock) -> list[dict[str, Any]]:
"""Convert an ACP resource_link block to OpenAI content parts.
Image resources produce an image_url part with a small text header so the
model knows which attachment it is; other resources return a single text
part with the inlined file body (or a binary-omit note).
"""
"""ACP resource_link -> OpenAI content parts: images become a text header + image_url,
everything else a single text part with the inlined body (or a binary-omit note)."""
uri = str(getattr(block, "uri", "") or "").strip()
if not uri:
return []
@@ -485,8 +432,7 @@ def _content_blocks_to_openai_user_content(prompt: list[PromptBlock]) -> str | l
if not parts:
return _extract_text(prompt)
# Pure text prompts stay strings so slash-command handling and text-only
# providers keep the legacy path; structured content only for real media.
# Pure text stays a string (slash commands, text-only providers); structured only for media.
if all(part.get("type") == "text" for part in parts):
return "\n".join(text_parts)
@@ -554,12 +500,8 @@ def _estimate_tokens(history: list, agent: Any, system_prompt: str | None = None
def _flatten_history_text(value: Any) -> str:
"""Normalize a persisted text-or-text-parts value into one stripped string.
Content (and provider reasoning fields) may be a scalar string or a list of
``{"text": ...}`` / ``{"type": "text", "content": ...}`` parts. Whitespace-only
input collapses to ``""`` so callers can treat that as "nothing to emit".
"""
"""Persisted content/reasoning (str, or list of ``{"text"}`` / ``{"type": "text", "content"}``
parts) -> one stripped string; whitespace-only collapses to ``""`` ("nothing to emit")."""
if isinstance(value, str):
return value.strip()
if isinstance(value, list):
@@ -578,9 +520,8 @@ def _flatten_history_text(value: Any) -> str:
def _history_reasoning_text(message: dict[str, Any]) -> str:
"""First non-empty of ``reasoning_content`` (DeepSeek/Moonshot, chat-completions
normalizer) and ``reasoning`` (codex projector and other transports). Both are
live keys for different transports, not old-vs-new."""
"""First non-empty of ``reasoning_content`` and ``reasoning`` — both live keys, for
different transports (not old-vs-new)."""
for key in ("reasoning_content", "reasoning"):
text = _flatten_history_text(message.get(key))
if text:
@@ -591,19 +532,14 @@ def _history_reasoning_text(message: dict[str, Any]) -> str:
def _history_summary_meta(message: dict[str, Any], text: str) -> dict[str, Any] | None:
"""``_meta`` for a replayed compaction summary, else None.
Summaries are persisted as ordinary history messages — standalone handoffs
under either role (whichever keeps alternation valid) or merged into the
first preserved tail message. Two distinct ``_meta.hermes`` keys so clients
cannot accidentally hide real content: ``compactionSummary`` (whole chunk is
the summary; safe to collapse) vs ``containsCompactionSummary`` (real turn
content followed by the summary; collapsing would hide preserved content).
Honors the in-process ``_compressed_summary`` flag and falls back to content
classification so DB-reloaded sessions still tag correctly.
Summaries persist as ordinary messages, standalone (either role) or merged into the first
preserved tail message. Two keys so clients can't hide real content: ``compactionSummary``
(whole chunk; safe to collapse) vs ``containsCompactionSummary`` (real content + summary).
Uses the in-process flag, falling back to content classification for DB-reloaded sessions.
"""
kind = ContextCompressor.classify_summary_content(text)
if kind is None and message.get(COMPRESSED_SUMMARY_METADATA_KEY):
# Flagged but unclassified (prefix drift): the flag is only ever set on
# summary-bearing messages, so treat as standalone.
# Flagged but unclassified (prefix drift): the flag only marks summaries -> standalone.
kind = "standalone"
if kind == "standalone":
return {"hermes": {"compactionSummary": True}}
@@ -660,12 +596,11 @@ def _attach_interrupted_prompt(interrupted_prompt: str, guidance: str) -> str:
@dataclass
class _ModelCatalog:
"""Deduplicated ACP model rows collected from the inventory + named endpoints.
"""Deduplicated ACP model rows from the inventory + named endpoints.
Dedupes on both the encoded choice id and a semantic ``provider:model`` id
(``ollama``/``custom:ollama`` are one provider). Also resolves the current
provider identity: a bare/``custom`` current provider whose base_url matches
an ollama inventory row is really ``custom:ollama``.
Dedupes on the encoded choice id AND a semantic ``provider:model`` id (``ollama`` ==
``custom:ollama``). A bare/``custom`` current provider whose base_url matches an ollama
inventory row is resolved to ``custom:ollama``.
"""
normalize_provider: Callable[[str], str]
@@ -843,12 +778,8 @@ class HermesACPAgent(acp.Agent):
loop.call_soon(asyncio.create_task, make_coro())
def _session_modes(self, state: SessionState) -> SessionModeState:
"""ACP session modes carrying the edit-approval policy.
Zed renders ``config_options`` in the prominent selector slot where the
model picker lives; Claude/Codex expose policy controls as ACP modes,
which coexist with the picker, so Hermes maps edit approval onto modes.
"""
"""Edit-approval policy as ACP modes. Zed renders ``config_options`` in the model
picker's slot; modes (as Claude/Codex use) coexist with the picker."""
current = str(getattr(state, "mode", "") or self._MODE_DEFAULT)
if current not in self._MODES:
current = self._MODE_DEFAULT
@@ -872,12 +803,8 @@ class HermesACPAgent(acp.Agent):
return f"{raw_provider}:{raw_model}" if raw_provider else raw_model
def _build_model_state(self, state: SessionState) -> SessionModelState | None:
"""Authenticated providers and their models for ACP clients.
Uses the shared Hermes inventory (also behind ``hermes model``, the TUI
and the dashboard) so the selector doesn't collapse to the current
provider's curated list.
"""
"""Authenticated providers + models, from the shared Hermes inventory (same substrate
as ``hermes model``/TUI/dashboard) so the selector isn't just the current curated list."""
model = str(state.model or getattr(state.agent, "model", "") or "").strip()
provider = getattr(state.agent, "provider", None) or detect_provider() or "openrouter"
@@ -973,11 +900,8 @@ class HermesACPAgent(acp.Agent):
def _switch_model(
self, state: SessionState, raw_model: str, *, keep_endpoint: bool = False
) -> tuple[str | None, str, str]:
"""Rebuild the session agent on a new model; returns (old provider, new provider, model).
``keep_endpoint`` carries the current base_url/api_mode over when the
provider is unchanged (ACP ``set_session_model``).
"""
"""Rebuild the session agent on a new model -> (old provider, new provider, model).
``keep_endpoint`` carries base_url/api_mode over when the provider is unchanged."""
current_provider = getattr(state.agent, "provider", None)
target_provider, new_model = self._resolve_model_selection(raw_model, current_provider or "openrouter")
state.model = new_model
@@ -996,9 +920,8 @@ class HermesACPAgent(acp.Agent):
@staticmethod
def _build_usage_update(state: SessionState) -> UsageUpdate | None:
"""ACP ``usage_update`` driving Zed's context indicator: ``size`` is the
model context window, ``used`` the estimated request pressure (system
prompt + history + tool schemas — the same buckets sent to providers)."""
"""``usage_update`` for Zed's context indicator: ``size`` = context window, ``used`` =
estimated request pressure (system prompt + history + tool schemas)."""
agent = state.agent
compressor = getattr(agent, "context_compressor", None)
size = int(getattr(compressor, "context_length", 0) or 0)
@@ -1038,9 +961,8 @@ class HermesACPAgent(acp.Agent):
self, session_id: str, *,
current_hermes_session_id: Optional[str] = None, previous_hermes_session_id: Optional[str] = None,
) -> None:
"""Send ACP session metadata after Hermes changes it. Pass
``previous_hermes_session_id`` when the internal head rotated
(compression split) so the provenance meta flags the reason."""
"""Session metadata update; pass ``previous_hermes_session_id`` when the internal head
rotated (compression split) so provenance flags the reason."""
if not self._conn:
return
try:
@@ -1052,8 +974,7 @@ class HermesACPAgent(acp.Agent):
return
title = row.get("title")
# `sessions` has no `updated_at` column (only started_at/ended_at); "now"
# is right because this fires precisely when the title was refreshed.
# `sessions` has no `updated_at`; "now" is right since this fires when the title changed.
update = SessionInfoUpdate(
session_update="session_info_update",
title=title if isinstance(title, str) and title.strip() else None,
@@ -1114,19 +1035,14 @@ class HermesACPAgent(acp.Agent):
)
def _schedule_mcp_late_refresh(self, state: SessionState) -> None:
"""Refresh the agent's tool snapshot when background MCP discovery lands late.
"""Refresh the tool snapshot when background MCP discovery lands after agent build
(``_make_agent`` only joins ~1.5s). Waits up to 30s off the critical path, then rebuilds
via ``refresh_agent_mcp_tools`` (same as ``/reload-mcp``).
entry.py runs MCP discovery in a daemon thread; ``_make_agent`` joins it
only briefly (~1.5s), so a slower server lands after the agent is built
and its tools would be absent for the whole session. This waits for
discovery (bounded 30s) off the critical path, then rebuilds via the same
``refresh_agent_mcp_tools`` that ``/reload-mcp`` uses.
Cache safety: rebuild only while the session is pre-first-turn (nothing
cached yet). After the first message the snapshot stays frozen; later
servers are picked up cache-safely by the between-turns prologue refresh
(``agent/turn_context.py``). No-op when discovery already finished, the
join times out, the registry was unchanged, or the session was closed.
Cache safety: only pre-first-turn (nothing cached yet); afterwards the snapshot stays
frozen and late servers land via the between-turns prologue refresh
(``agent/turn_context.py``). No-op if discovery finished, join timed out, registry
unchanged, or session closed.
"""
try:
from hermes_cli.mcp_startup import mcp_discovery_in_flight
@@ -1147,17 +1063,14 @@ class HermesACPAgent(acp.Agent):
if not join_mcp_discovery(timeout=30.0):
return
# In-memory-only lookup on purpose: ``get_session()`` would
# restore from DB and build a whole new AIAgent just to say no-op.
# In-memory only: ``get_session()`` would restore from DB and build a new AIAgent.
with self.session_manager._lock:
current = self.session_manager._sessions.get(session_id)
if current is None or current.agent is not agent:
return
# Serialized with turn start: ``prompt()`` flips ``is_running``
# under ``runtime_lock`` before dispatching, so holding it here
# (and bailing when a turn is running) closes the window where
# the refresh would swap ``tools=`` mid-turn and break the cache.
# ``prompt()`` flips ``is_running`` under ``runtime_lock`` before dispatching, so
# holding it here closes the window where a refresh would swap ``tools=`` mid-turn.
with current.runtime_lock:
if current.is_running:
return
@@ -1212,16 +1125,14 @@ class HermesACPAgent(acp.Agent):
)
async def authenticate(self, method_id: str, **kwargs: Any) -> AuthenticateResponse | None:
# Only acknowledge the method_id advertised in initialize(); accepting
# any id would be poor hygiene if ACP ever grows multi-method auth.
# Only acknowledge the method_id advertised in initialize().
if not isinstance(method_id, str):
return None
normalized_method = method_id.strip().lower()
provider = detect_provider()
if normalized_method == TERMINAL_SETUP_AUTH_METHOD_ID:
# Terminal auth runs Hermes setup out-of-band; succeed only once it
# has produced usable runtime credentials.
# Terminal auth runs setup out-of-band; succeed only once credentials exist.
return AuthenticateResponse() if provider else None
if not provider or normalized_method != provider:
@@ -1231,10 +1142,8 @@ class HermesACPAgent(acp.Agent):
# ---- Session management -------------------------------------------------
async def _replay_session_history(self, state: SessionState) -> None:
"""Replay persisted history as user/assistant chunks, thought chunks and
reconstructed tool-call start/completion notifications, so the editor
shows the transcript instead of a clean thread. Awaited inline from
``load_session``/``resume_session`` (see there for why)."""
"""Replay history as user/assistant/thought chunks plus reconstructed tool-call
start/complete events so the editor shows the transcript, not a clean thread."""
if not self._conn or not state.history:
return
@@ -1299,12 +1208,9 @@ class HermesACPAgent(acp.Agent):
return
async def _replay_history_guarded(self, state: SessionState, verb: str) -> None:
"""Per ACP spec, ``session/load`` and ``session/resume`` must stream the
prior conversation via ``session/update`` BEFORE responding, so clients
get the transcript within the request's lifetime (Codex, Claude Code,
OpenCode, Zed all rely on this; deferring via ``call_soon`` broke them).
Replay is best-effort: a corrupt message shape must not turn a
successful load into a JSON-RPC error."""
"""Per ACP spec, load/resume must stream history via ``session/update`` BEFORE
responding (Codex/Claude Code/OpenCode/Zed rely on this; deferring via ``call_soon``
broke them). Best-effort: a corrupt message must not turn the load into an error."""
try:
await self._replay_session_history(state)
except Exception:
@@ -1316,8 +1222,8 @@ class HermesACPAgent(acp.Agent):
)
def _session_response_fields(self, state: SessionState) -> dict[str, Any]:
"""Common ``models``/``modes``/``field_meta`` for session responses; also
schedules the command advertisement and usage refresh."""
"""``models``/``modes``/``field_meta`` for session responses; schedules command
advertisement + usage refresh."""
self._schedule_available_commands_update(state.session_id)
self._schedule_usage_update(state)
return {
@@ -1367,8 +1273,7 @@ class HermesACPAgent(acp.Agent):
with state.runtime_lock:
if state.is_running and state.current_prompt_text:
state.interrupted_prompt_text = state.current_prompt_text
# Publish cancellation and hard-stop the agent before another
# prompt can acquire this lock and mistake the turn for
# Cancel + hard-stop under the lock so no other prompt mistakes this turn for
# redirectable work.
state.cancel_event.set()
try:
@@ -1397,10 +1302,8 @@ class HermesACPAgent(acp.Agent):
async def list_sessions(
self, cursor: str | None = None, cwd: str | None = None, **kwargs: Any
) -> ListSessionsResponse:
"""``cwd`` filtering is done by ``SessionManager.list_sessions``. ``cursor``
is a ``session_id`` previously returned as ``next_cursor``; results
resume after it (unknown cursor -> empty page, never the full list).
Pages are capped at ``_LIST_SESSIONS_PAGE_SIZE``."""
"""``cursor`` is a ``session_id`` returned as ``next_cursor``; results resume after it
(unknown cursor -> empty page, never the full list). Pages cap at the fixed size."""
infos = self.session_manager.list_sessions(cwd=cwd)
if cursor:
@@ -1431,17 +1334,11 @@ class HermesACPAgent(acp.Agent):
def _rewrite_prompt_for_interrupt(
self, state: SessionState, user_text: str, user_content: Any, text_only: bool
) -> tuple[str, Any]:
"""Attach a client-cancelled prompt to the follow-up text, and run idle
``/steer`` as a normal prompt.
``/steer`` on an idle session has no in-flight tool call to inject into
(matching the gateway): if a prior prompt was just cancelled, replay it
with the steer text as explicit correction so the in-flight work isn't
lost; otherwise run the steer payload as a plain prompt instead of
silently queueing it ("No active turn — queued") as if the user typed
``/queue``. Plain text after a cancel likewise keeps the cancelled request
attached ("stop and send" clients) so deictic follow-ups have a target.
"""
"""Idle ``/steer`` has nothing to inject into (gateway parity): if a prompt was just
cancelled, replay it with the steer text as explicit correction; otherwise run the steer
payload as a plain prompt rather than silently queueing it as if ``/queue`` was typed.
Plain text after a cancel likewise keeps the cancelled request attached ("stop and
send" clients) so deictic follow-ups have a target."""
if not (text_only and isinstance(user_content, str)):
return user_text, user_content
@@ -1477,9 +1374,8 @@ class HermesACPAgent(acp.Agent):
def _claim_turn_or_queue(
self, state: SessionState, session_id: str, user_text: str, user_content: Any, text_only: bool
) -> str | None:
"""Mark the session running, or — if a turn is active — redirect it
(text-only, runtime supports it) or queue for the next turn. Returns the
message to send the client when the prompt was absorbed, else None."""
"""Mark the session running; if a turn is active, redirect it (text-only, supported
runtime) or queue it. Returns the client message when absorbed, else None."""
redirected = False
queued_depth: int | None = None
with state.runtime_lock:
@@ -1511,22 +1407,19 @@ class HermesACPAgent(acp.Agent):
self, *, state: SessionState, session_id: str, user_text: str, user_content: Any, conn: Any,
loop: asyncio.AbstractEventLoop, approval_cb: Any, edit_approval_requester: Any,
) -> dict:
"""Executor-thread body of one turn. Runs inside ``contextvars.copy_context()``
so every ContextVar write below is isolated from concurrent sessions.
"""Executor-thread body of one turn, run inside ``contextvars.copy_context()`` so
ContextVar writes are isolated from concurrent sessions.
Approval routing is thread-local, so it MUST be bound here (executor
thread), not on the event-loop thread. Interactive routing uses the
``tools.approval`` contextvar rather than ``os.environ["HERMES_INTERACTIVE"]``
so concurrent workers can't race a process-global flag and drop another
session onto the non-interactive auto-approve path (GHSA-96vc-wcxf-jjff).
Approval routing is thread-local, so it MUST be bound here, not on the loop thread.
Interactive routing is a ``tools.approval`` contextvar, not ``HERMES_INTERACTIVE`` in
os.environ, so concurrent workers can't race a global flag onto the non-interactive
auto-approve path (GHSA-96vc-wcxf-jjff).
"""
agent = state.agent
# Bind HERMES_SESSION_KEY so per-session caches (e.g. the interactive
# sudo password cache) scope to this ACP session, not the reused thread.
# ``cwd`` pins the logical working directory the system prompt reports
# (resolve_agent_cwd); without it the prompt advertises the global
# Hermes workspace while tools are rooted at the client's project, and
# edits land outside the editor's workspace. ``cron_session=""`` masks
# HERMES_SESSION_KEY scopes per-session caches (interactive sudo password) to this
# session, not the reused thread. ``cwd`` pins what the system prompt reports as the
# working directory — otherwise it advertises the Hermes workspace while tools are
# rooted at the client's project and edits land outside it. ``cron_session=""`` masks
# any leaked process-global HERMES_CRON_SESSION.
try:
from gateway.session_context import clear_session_vars, set_session_vars
@@ -1555,13 +1448,11 @@ class HermesACPAgent(acp.Agent):
except Exception:
logger.debug("Could not set ACP edit approval requester", exc_info=True)
interactive_token = set_hermes_interactive_context(True)
# Tools tag side-effects with the originating ACP session (e.g.
# ``kanban_create``); save/restore so a reused thread never leaks it.
# Tools tag side-effects with the ACP session (``kanban_create``); save/restore it.
previous_session_id = os.environ.get("HERMES_SESSION_ID")
os.environ["HERMES_SESSION_ID"] = session_id
# Auto-titling fires in the turn prologue; deliver the new title now
# as a session-info update instead of waiting for the next one.
# Auto-titling fires in the turn prologue; push the title now as a session-info update.
def _notify_title_update(_title: str, _source: str) -> None:
if conn:
loop.call_soon_threadsafe(asyncio.create_task, self._send_session_info_update(session_id))
@@ -1619,8 +1510,7 @@ class HermesACPAgent(acp.Agent):
state, user_text, user_content, text_only_prompt
)
# Slash commands are text-only and handled locally without the LLM; a
# prompt with images/resources goes to the agent even if it starts with "/".
# Slash commands are text-only; a prompt with media goes to the agent even if it starts with "/".
if text_only_prompt and isinstance(user_content, str) and user_text.startswith("/"):
response_text = self._handle_slash_command(user_text, state)
if response_text is not None:
@@ -1652,12 +1542,10 @@ class HermesACPAgent(acp.Agent):
)
try:
# The ACP `session_id` is the stable client handle; agent.session_id
# is the live internal head that compression may rotate. Snapshot it
# to detect a rotation after the turn.
# ACP `session_id` is the stable handle; agent.session_id is the internal head that
# compression may rotate — snapshot it to detect rotation after the turn.
pre_turn_hermes_id = getattr(state.agent, "session_id", None)
# Fresh context copy so concurrent sessions on the shared executor
# don't stomp on each other's ContextVar writes.
# Fresh context copy: concurrent sessions on the shared executor must not share ContextVars.
ctx = contextvars.copy_context()
result = await loop.run_in_executor(_executor, ctx.run, _run_agent)
except Exception:
@@ -1703,9 +1591,7 @@ class HermesACPAgent(acp.Agent):
agent = state.agent
agent.tool_progress_callback = cbs.tool_progress_cb
# ACP thought panes get provider reasoning deltas only — never Hermes'
# local status updates, and no fake "thinking" accordion when the
# provider emits no reasoning.
# Thought panes get provider reasoning only — no local status updates, no fake accordion.
agent.thinking_callback = None
agent.reasoning_callback = cbs.reasoning_cb
agent.step_callback = cbs.step_cb
@@ -1721,8 +1607,7 @@ class HermesACPAgent(acp.Agent):
state.history = result["messages"]
self.session_manager.save_session(session_id)
# Internal head rotated (compression split): emit provenance so clients
# can render the boundary; the ACP session_id is unchanged.
# Head rotated (compression split): emit provenance so clients can render the boundary.
post_turn_hermes_id = getattr(state.agent, "session_id", None)
if (
conn
@@ -1741,13 +1626,11 @@ class HermesACPAgent(acp.Agent):
final_response = result.get("final_response", "")
cancelled = bool(state.cancel_event and state.cancel_event.is_set())
interrupted = bool(result.get("interrupted")) or cancelled
# The local "waiting for model response" interrupt status is metadata,
# not assistant prose — clients learn cancellation from stop_reason.
# The local "waiting for model" interrupt status is metadata, not prose; stop_reason carries it.
from agent.conversation_loop import INTERRUPT_WAITING_FOR_MODEL_PREFIX
suppress_interrupt_response = interrupted and final_response.startswith(INTERRUPT_WAITING_FOR_MODEL_PREFIX)
# Deliver the final response when streaming didn't already, or when a
# plugin hook transformed it after streaming (transform_llm_output).
# Send the final text unless already streamed — or if a plugin hook transformed it after.
if (
final_response
and conn
@@ -1756,8 +1639,7 @@ class HermesACPAgent(acp.Agent):
):
await conn.session_update(session_id, acp.update_agent_message_text(final_response))
# Go idle before draining queued work so recursive prompt() calls can
# acquire the session; queued turns run as normal follow-up prompts.
# Go idle before draining so recursive prompt() calls can acquire the session.
with state.runtime_lock:
state.is_running = False
state.current_prompt_text = ""
@@ -1805,8 +1687,7 @@ class HermesACPAgent(acp.Agent):
self._schedule_soon(lambda: self._send_available_commands_update(session_id))
def _handle_slash_command(self, text: str, state: SessionState) -> str | None:
"""Dispatch a slash command; ``None`` for unknown commands so they fall
through to the LLM (the user may have typed ``/something`` as prose)."""
"""Dispatch a slash command; ``None`` for unknown ones so they fall through to the LLM."""
parts = text.split(maxsplit=1)
cmd = parts[0].lstrip("/").lower()
args = parts[1].strip() if len(parts) > 1 else ""
@@ -1815,11 +1696,9 @@ class HermesACPAgent(acp.Agent):
return None
handler = getattr(self, f"_cmd_{cmd}")
# Handlers run on the event-loop thread, OUTSIDE the per-turn context
# that pins the session cwd. ``/compress`` and ``/model`` REBUILD the
# system prompt (resolve_agent_cwd), so an unpinned handler would bake
# the Hermes install tree into the persisted cached prompt and poison
# every later turn. Pin inside a fresh context: no leak, no teardown.
# Handlers run on the loop thread, outside the per-turn cwd-pinning context. ``/compress``
# and ``/model`` REBUILD the system prompt, so unpinned they'd bake the Hermes install tree
# into the persisted cached prompt. Pin inside a fresh context: no leak, no teardown.
def _dispatch() -> str | None:
try:
from agent.runtime_cwd import set_session_cwd
@@ -1968,22 +1847,19 @@ class HermesACPAgent(acp.Agent):
return "Nothing to compress — conversation is empty."
try:
agent = state.agent
# No compression_enabled gate: that flag only disables *automatic*
# compaction; manual /compress must keep working (CLI/gateway parity).
# No compression_enabled gate: it only disables *automatic* compaction (CLI/gateway parity).
if not hasattr(agent, "_compress_context"):
return "Context compression not available for this agent."
original_count = len(state.history)
# System prompt + tool schemas included so the figure reflects real
# request pressure, not a transcript-only underestimate.
# Include system prompt + tool schemas so the figure reflects real request pressure.
_sys_prompt = getattr(agent, "_cached_system_prompt", "") or ""
_tools = getattr(agent, "tools", None) or None
approx_tokens = _estimate_tokens(state.history, agent, _sys_prompt, _tools)
original_session_db = getattr(agent, "_session_db", None)
try:
# ACP sessions keep a stable session id: suppress the SQLite
# session-splitting side effect inside _compress_context.
# Stable ACP session id: suppress _compress_context's SQLite session split.
agent._session_db = None
compressed, _ = agent._compress_context(
state.history, getattr(agent, "_cached_system_prompt", "") or "",
@@ -133,7 +133,8 @@ def test_clearing_threshold_tokens_restores_ratio_trigger(monkeypatch):
def test_prompt_submit_calls_compression_sync_after_model_sync():
source = open(server.__file__, encoding="utf-8").read()
# Read the module that actually defines the turn (it moved out of server.py).
source = open(server._run_prompt_submit.__code__.co_filename, encoding="utf-8").read()
model_idx = source.find("_sync_agent_model_with_config(sid, session)")
compression_idx = source.find("_sync_agent_compression_with_config(sid, session)")
assert model_idx != -1
+134 -318
View File
@@ -13,25 +13,17 @@ from .method_ctx import HandlerRegistry, bind_module
_registry = HandlerRegistry()
# ── Child-session live mirror ────────────────────────────────────────
# A delegated child is not a live gateway session — it runs synchronously
# inside the parent's turn, and its activity reaches the gateway only as
# relayed ``subagent.*`` events on the PARENT sid. When a UI opens the child's
# own session (session.resume on ``child_session_id``, e.g. the desktop's
# open-in-new-window), that window would otherwise sit silent until the run
# persists. Translate the relayed events into the native stream events the
# window already renders — emitted on the CHILD sid, routed to its transport
# by write_json — so the window shows a real midstream turn.
# Child-session live mirror: a delegated child's activity reaches the gateway only
# as relayed ``subagent.*`` events on the PARENT sid, so a window opened on the
# child's own session would sit silent until the run persists. Translate them into
# the native stream events emitted on the CHILD sid (write_json routes by sid).
_child_mirrors: dict[str, dict] = {}
_child_mirrors_lock = threading.Lock()
# Stored child session ids with a delegation run currently in flight (refreshed
# on every relayed subagent.* event, popped on subagent.complete). Lets a lazy
# watch resume report running=true so the window shows a busy indicator even
# while the child is silent inside a long tool call (no events for 25s+).
# Child session ids with a run in flight (refreshed per relayed event, popped on
# complete) so a lazy watch resume reports running=true during a silent long tool.
_active_child_runs: dict[str, float] = {}
# Staleness bound for the registry: entries refresh on every relayed event, so
# anything this quiet means the completion event was lost (callback raised,
# parent crashed) — don't let a leaked entry pin "running" forever.
# Anything quiet this long lost its completion event (callback raised, parent
# crashed) — don't pin "running".
_CHILD_RUN_STALE_S = 3600.0
@@ -44,41 +36,36 @@ def _mirror_subagent_to_child(event_type: str, payload: dict) -> None:
child_key = str(payload.get("child_session_id") or "")
if not child_key:
return
# Liveness registry first — it must be accurate even when no window is
# open, so a window opened mid-run can immediately know the child is busy.
# Liveness registry first: accurate with no window open, so one opened mid-run
# immediately knows the child is busy.
if event_type == "subagent.complete":
_active_child_runs.pop(child_key, None)
else:
_active_child_runs[child_key] = time.time()
# Mirror only into a live watch session (keyed by session_key; its live sid
# differs from the stored id) that has NOT been upgraded to a full agent.
# No window / closed → nothing to mirror; an upgraded session owns a real
# native stream and mirroring on top would interleave two turns on one sid.
# Either way drop state so a reopened window starts a fresh synthetic turn.
# Mirror only into a live watch session NOT upgraded to a full agent: an
# upgraded one owns a real native stream and mirroring would interleave two
# turns on one sid. Either way drop state so a reopened window starts fresh.
live = _find_live_session_by_key(child_key)
if live is None or live[1].get("agent") is not None:
with _child_mirrors_lock:
_child_mirrors.pop(child_key, None)
return
csid = live[0]
text = str(payload.get("text") or "")
with _child_mirrors_lock:
st = _child_mirrors.setdefault(child_key, {"seq": 0, "open_tool": None, "started": False})
if not st["started"]:
st["started"] = True
_emit("message.start", csid)
if event_type == "subagent.thinking":
if text := str(payload.get("text") or ""):
if text:
_emit("reasoning.delta", csid, {"text": text})
elif event_type == "subagent.text":
# The child's streamed reply text — the actual "agent talking".
# Relayed token-by-token from the child's run_conversation
# stream_callback, so the watch window streams the reply live.
if text := str(payload.get("text") or ""):
if text:
_emit("message.delta", csid, {"text": text})
elif event_type == "subagent.start":
# One-time header line (the child's goal) so a freshly opened window
# shows immediate context before the first reply token streams.
if text := str(payload.get("text") or ""):
# One-time header (the child's goal) so a fresh window has context first.
if text:
_emit("message.delta", csid, {"text": f"{text}\n"})
elif event_type == "subagent.tool":
if st["open_tool"]:
@@ -102,124 +89,59 @@ def _mirror_subagent_to_child(event_type: str, payload: dict) -> None:
def _agent_cbs(sid: str) -> dict:
def _read_block(event: str, timeout: int):
# read_terminal / read_preview (desktop GUI): blocking bridge like clarify; the
# preview read gets longer since a URL tab extracts text from a live page.
return lambda start=None, count=None: _block(
event, sid, {k: v for k, v in (("start", start), ("count", count)) if v is not None}, timeout=timeout
)
callbacks = {
"tool_start_callback": lambda tc_id, name, args: _on_tool_start(
sid, tc_id, name, args
),
"tool_complete_callback": lambda tc_id, name, args, result: _on_tool_complete(
sid, tc_id, name, args, result
),
"tool_start_callback": lambda tc_id, name, args: _on_tool_start(sid, tc_id, name, args),
"tool_complete_callback": lambda tc_id, name, args, result: _on_tool_complete(sid, tc_id, name, args, result),
"tool_progress_callback": lambda event_type, name=None, preview=None, args=None, **kwargs: _on_tool_progress(
sid, event_type, name, preview, args, **kwargs
),
"tool_gen_callback": lambda name: _tool_progress_enabled(sid)
and _emit("tool.generating", sid, {"name": name}),
"tool_gen_callback": lambda name: _tool_progress_enabled(sid) and _emit("tool.generating", sid, {"name": name}),
"thinking_callback": lambda text: _emit("thinking.delta", sid, {"text": text}),
# Affection reaction (ily / <3 / good bot) → hearts. Core-detected, so
# the TUI heart and desktop floating hearts share one signal.
# Affection reaction (ily / <3 / good bot) → hearts; core-detected so TUI and desktop share it.
"reaction_callback": lambda kind: _emit("reaction", sid, {"kind": kind}),
"reasoning_callback": lambda text: _emit(
"reasoning.delta",
sid,
{"text": text, **({"verbose": True} if _session_verbose(sid) else {})},
"reasoning.delta", sid, {"text": text, **({"verbose": True} if _session_verbose(sid) else {})}
),
"status_callback": lambda kind, text=None: _status_update(
sid, str(kind), None if text is None else str(text)
),
# Credits/notice spine (L1): an AgentNotice fired by the agent becomes a
# notification.show WS event; a recovery clear becomes notification.clear.
# Snake_case payload to match the existing gateway-event convention.
"status_callback": lambda kind, text=None: _status_update(sid, str(kind), None if text is None else str(text)),
# Credits/notice spine: AgentNotice → notification.show; recovery clear → notification.clear.
"notice_callback": lambda n: _emit(
"notification.show",
sid,
{
"text": n.text,
"level": n.level,
"kind": n.kind,
"ttl_ms": n.ttl_ms,
"key": n.key,
"id": n.id,
},
),
"notice_clear_callback": lambda key: _emit(
"notification.clear", sid, {"key": key}
{"text": n.text, "level": n.level, "kind": n.kind, "ttl_ms": n.ttl_ms, "key": n.key, "id": n.id},
),
"notice_clear_callback": lambda key: _emit("notification.clear", sid, {"key": key}),
"clarify_callback": lambda q, c, multi_select=False, questions=None: (
_clarify_block(sid, q, c, multi_select=multi_select, questions=questions)
),
# read_terminal tool (desktop GUI): same blocking bridge as clarify — the
# renderer answers terminal.read.respond with the serialized buffer.
"read_terminal_callback": lambda start=None, count=None: _block(
"terminal.read.request",
sid,
{k: v for k, v in (("start", start), ("count", count)) if v is not None},
timeout=30,
),
# read_preview tool (desktop GUI): the renderer serializes the active
# preview tab (a Browser webview's readable text, a file's identity)
# and answers preview.read.respond. Longer timeout than the terminal
# read — a URL tab extracts text from a live page.
"read_preview_callback": lambda start=None, count=None: _block(
"preview.read.request",
sid,
{k: v for k, v in (("start", start), ("count", count)) if v is not None},
timeout=45,
),
# drive_preview tool (desktop GUI): the renderer injects the interaction
# engine into the preview pane's webview (or drives the pane's history)
# and answers preview.act.respond with the outcome plus a refreshed
# element inventory. Same budget as the preview read, which it ends
# with — a click on a slow page pays for the settle and the re-scan.
# annotate_preview rides this same callback: it resolves a target
# through the same engine and differs only in the verb it sends, so it
# needs a tool of its own but not a channel of its own.
"drive_preview_callback": lambda payload: _block(
"preview.act.request",
sid,
dict(payload),
timeout=45,
),
# read_window_below tool (desktop GUI): the renderer asks its main
# process (which owns native window enumeration) which OS window sits
# directly underneath the Hermes window, and answers
# window.read.respond with the serialized metadata.
"read_window_below_callback": lambda: _block(
"window.read.request",
sid,
{},
timeout=30,
),
# setup_mcp tool (desktop GUI): the renderer shows an inline consent
# card and walks the user through install/enable/OAuth via the REST
# endpoints, then answers mcp.setup.respond with the JSON outcome.
# Long timeout on purpose — the flow can include typing an API key or
# a browser OAuth round-trip. Same lifecycle as clarify: on timeout
# the tool returns "unanswered" and a late answer is tolerated.
"read_terminal_callback": _read_block("terminal.read.request", 30),
"read_preview_callback": _read_block("preview.read.request", 45),
# drive_preview / annotate_preview (desktop GUI): renderer drives the preview webview and
# answers with outcome + refreshed element inventory; same budget as the preview read it ends with.
"drive_preview_callback": lambda payload: _block("preview.act.request", sid, dict(payload), timeout=45),
# read_window_below (desktop GUI): main process enumerates native windows.
"read_window_below_callback": lambda: _block("window.read.request", sid, {}, timeout=30),
# setup_mcp (desktop GUI): consent card + install/enable/OAuth. Long timeout on purpose (typing
# an API key, browser OAuth); like clarify, timeout returns "unanswered" and a late answer is tolerated.
"setup_mcp_callback": lambda server, action, reason: _block(
"mcp.setup.request",
sid,
{"server": server, "action": action, "reason": reason},
timeout=600,
"mcp.setup.request", sid, {"server": server, "action": action, "reason": reason}, timeout=600
),
# tour tool (desktop GUI): the renderer drives driver.js — highlighting
# elements in the app's own DOM or injecting the engine into the
# preview pane's webview — and answers tour.respond with the outcome
# (did the selector match, which step is active).
# tour (desktop GUI): renderer drives driver.js and answers tour.respond.
"tour_callback": lambda payload: _tour_request(sid, payload),
}
# Interim assistant commentary (text alongside tool calls, or the attempted
# final answer before a verify-on-stop nudge). Gated on
# display.interim_assistant_messages (default true). Also set per-turn in
# _run_prompt_submit as defense-in-depth — the per-turn set overwrites
# this, and the finally block clears it so a stale closure can't fire.
# Interim assistant commentary (text alongside tool calls). Gated on
# display.interim_assistant_messages (default true); _run_prompt_submit overwrites
# it per turn and clears it in its finally so a stale closure can't fire.
if _load_interim_assistant_messages():
callbacks["interim_assistant_callback"] = (
lambda text, *, already_streamed=False: _emit(
"message.interim",
sid,
{"text": str(text), "already_streamed": bool(already_streamed)},
)
callbacks["interim_assistant_callback"] = lambda text, *, already_streamed=False: _emit(
"message.interim", sid, {"text": str(text), "already_streamed": bool(already_streamed)}
)
return callbacks
@@ -227,17 +149,13 @@ def _agent_cbs(sid: str) -> dict:
def _apply_project_workspace(task_id: str, path: str, _name: str = "") -> None:
"""Intentional workspace move from the project_* tools: re-anchor the live
session's cwd to the chosen project's folder and push session.info so the
desktop follows (refresh tree + scope into the project). This is the ONLY
session's cwd and push session.info so the desktop follows. This is the ONLY
auto-cwd path — driven by an explicit tool call, never a terminal `cd`."""
if not path:
return
# The tool's task_id is the durable session_key, but _sessions is keyed by a
# short sid uuid (and the desktop routes events by that sid). Resolve it.
# task_id is the durable session_key; _sessions (and desktop event routing) key by sid.
key = str(task_id or "")
sid = ""
session = None
sid, session = "", None
with _sessions_lock:
if key in _sessions:
sid, session = key, _sessions[key]
@@ -246,34 +164,25 @@ def _apply_project_workspace(task_id: str, path: str, _name: str = "") -> None:
if cand.get("session_key") == key or getattr(cand.get("agent"), "session_id", None) == key:
sid, session = cand_sid, cand
break
if session is None:
return
resolved = os.path.abspath(os.path.expanduser(str(path)))
if not os.path.isdir(resolved):
return
session["cwd"] = resolved
session["explicit_cwd"] = True
# An explicit project switch supersedes any earlier settle-adopted cwd.
session["cwd_from_settle"] = False
session["cwd_from_settle"] = False # explicit switch supersedes a settle-adopted cwd
_register_session_cwd(session)
_persist_session_cwd_and_schedule_git_meta(session, resolved)
try:
agent = session.get("agent")
info = (
_session_info(agent, session)
if agent is not None
else {
"cwd": resolved,
"branch": _git_branch_for_cwd(resolved),
"project": _project_info_for_cwd(resolved),
"lazy": True,
if agent is not None:
info = _session_info(agent, session)
else:
info = {
"cwd": resolved, "branch": _git_branch_for_cwd(resolved),
"project": _project_info_for_cwd(resolved), "lazy": True,
}
)
_emit("session.info", sid, info)
except Exception:
logger.debug("failed to emit session.info after project workspace move", exc_info=True)
@@ -293,20 +202,10 @@ def _wire_callbacks(sid: str):
pl["metadata"] = metadata
val = _block("secret.request", sid, pl)
if not val:
return {
"success": True,
"stored_as": env_var,
"validated": False,
"skipped": True,
"message": "skipped",
}
return {"success": True, "stored_as": env_var, "validated": False, "skipped": True, "message": "skipped"}
from hermes_cli.config import save_env_value_secure
return {
**save_env_value_secure(env_var, val),
"skipped": False,
"message": "ok",
}
return {**save_env_value_secure(env_var, val), "skipped": False, "message": "ok"}
set_secret_capture_callback(secret_cb)
@@ -322,18 +221,14 @@ def _available_personalities(cfg: dict | None = None) -> dict:
"""Built-ins + user overrides, via hermes_cli.personality (single owner)."""
from hermes_cli.personality import available_personalities
if cfg is None:
cfg = _load_cfg()
return available_personalities(cfg)
return available_personalities(_load_cfg() if cfg is None else cfg)
def _validate_personality(value: str, cfg: dict | None = None) -> tuple[str, str]:
"""Resolve a requested personality against _available_personalities.
"""Resolve a requested personality to (name, prompt) or raise ValueError.
Same contract as hermes_cli.personality.resolve_personality — (name,
prompt) or ValueError — but resolves through the module-level
_available_personalities so tests (and future gateway-side overrides)
keep a single patch point.
Same contract as hermes_cli.personality.resolve_personality, but goes through
the module-level _available_personalities so tests keep a single patch point.
"""
from hermes_cli.personality import normalize_personality_name
@@ -343,17 +238,12 @@ def _validate_personality(value: str, cfg: dict | None = None) -> tuple[str, str
personalities = _available_personalities(cfg)
if name not in personalities:
names = ", ".join(f"`{n}`" for n in sorted(personalities))
raise ValueError(
f"Unknown personality: `{str(value).strip()}`.\n\nAvailable: `none`, {names}"
)
raise ValueError(f"Unknown personality: `{str(value).strip()}`.\n\nAvailable: `none`, {names}")
return name, _render_personality_prompt(personalities[name])
def _prompt_text(value) -> str:
"""Normalize config prompt values from YAML before handing them to AIAgent.
Delegates to hermes_cli.personality (single owner).
"""
"""Normalize config prompt values from YAML for AIAgent (hermes_cli.personality owns this)."""
from hermes_cli.personality import prompt_text
return prompt_text(value)
@@ -362,68 +252,50 @@ def _prompt_text(value) -> str:
def _apply_personality_to_session(
sid: str, session: dict, new_prompt: str, personality: str = ""
) -> tuple[bool, dict | None]:
"""Apply a personality change to an existing session without resetting history.
"""Apply a personality change to a live session without resetting history.
Updates the agent's ephemeral system prompt in-place so the new personality
takes effect on the next turn. The cached base system prompt is left intact
(ephemeral_system_prompt is appended at API-call time, not baked into the
cache), which preserves prompt-cache hits.
Also injects a system-role marker into the conversation history so the model
knows to pivot its style from this point forward (without this, LLMs tend to
continue the tone established by earlier messages in the transcript).
Returns (history_reset, info) — history_reset is always False since we
preserve the conversation.
Updates the ephemeral system prompt in place (appended at API-call time, so
prompt-cache hits survive) and injects a pivot marker so the model stops
pattern-matching its earlier tone. Returns (history_reset=False, info).
"""
if not session:
return False, None
session["personality"] = personality
agent = session.get("agent")
if agent:
agent.ephemeral_system_prompt = new_prompt or None
# Inject a pivot marker into history so the model sees the change point.
# This prevents it from pattern-matching its prior style.
if new_prompt:
marker = (
"[System: The user has changed the assistant's personality. "
"From this point forward, adopt the following persona and respond "
f"accordingly: {new_prompt}]"
)
else:
marker = (
"[System: The user has cleared the personality overlay. "
"From this point forward, respond in your normal default style.]"
)
# Tagged like the model-switch marker (`_append_model_switch_marker`):
# the marker rides as role=user so strict OpenAI-compatible providers
# accept it mid-conversation, but `display_kind` keeps it out of the
# `truncate_before_user_ordinal` addressing space. Untagged, it counts
# as a real user turn on the gateway side while no client counts it, so
# every later rewind resolves one turn too early and `replace_messages`
# hard-deletes the difference (#82756).
with session["history_lock"]:
session["history"].append(
{"role": "user", "content": marker, "display_kind": "personality_switch"}
)
session["history_version"] = int(session.get("history_version", 0)) + 1
info = _session_info(agent)
_emit("session.info", sid, info)
return False, info
return False, None
if not agent:
return False, None
agent.ephemeral_system_prompt = new_prompt or None
if new_prompt:
marker = (
"[System: The user has changed the assistant's personality. "
"From this point forward, adopt the following persona and respond "
f"accordingly: {new_prompt}]"
)
else:
marker = (
"[System: The user has cleared the personality overlay. "
"From this point forward, respond in your normal default style.]"
)
# Like the model-switch marker: role=user so strict providers accept it
# mid-conversation, but `display_kind` keeps it out of the
# `truncate_before_user_ordinal` addressing space (untagged, every rewind would
# land one turn early and `replace_messages` hard-delete the difference).
with session["history_lock"]:
session["history"].append({"role": "user", "content": marker, "display_kind": "personality_switch"})
session["history_version"] = int(session.get("history_version", 0)) + 1
info = _session_info(agent)
_emit("session.info", sid, info)
return False, info
def _cfg_max_turns(cfg: dict, default: int) -> int:
from hermes_cli.config import resolve_turn_limit as _resolve_turn_limit
# Env var override (highest priority)
# Env override wins; resolve_turn_limit makes "none"/"unlimited"/0 first-class spellings.
env_val = os.environ.get("HERMES_TUI_MAX_TURNS")
if env_val:
return _resolve_turn_limit(env_val, default=default)
# Config file value — route through resolve_turn_limit so that
# "none"/"unlimited"/0 are first-class spellings, not int() crashes.
agent_cfg = cfg.get("agent") or {}
raw = agent_cfg.get("max_turns")
raw = (cfg.get("agent") or {}).get("max_turns")
if raw is None:
raw = cfg.get("max_turns")
if raw is not None:
@@ -434,24 +306,17 @@ def _cfg_max_turns(cfg: dict, default: int) -> int:
def _parse_tui_skills_env() -> list[str]:
raw = os.environ.get("HERMES_TUI_SKILLS", "")
skills: list[str] = []
seen: set[str] = set()
for part in raw.replace("\n", ",").split(","):
item = part.strip()
if item and item not in seen:
seen.add(item)
if item and item not in skills:
skills.append(item)
return skills
def _load_fallback_model():
"""Return the configured fallback chain for TUI-created agents.
Delegates to the shared ``get_fallback_chain`` helper so the TUI path
stays in parity with ``HermesCLI.__init__`` and ``gateway/run.py``:
``fallback_providers`` is the primary source of truth and keeps its
order, with legacy ``fallback_model`` entries merged in afterwards
(deduped on provider/model/base_url).
"""
"""Configured fallback chain for TUI-created agents, via the shared
``get_fallback_chain`` (parity with HermesCLI/gateway: ``fallback_providers``
first in order, legacy ``fallback_model`` merged after, deduped)."""
from hermes_cli.fallback_config import get_fallback_chain
return get_fallback_chain(_load_cfg())
@@ -460,9 +325,9 @@ def _load_fallback_model():
def _agent_fallback_model(agent):
"""Return an agent's fallback chain without rehydrating deliberately empty chains."""
if hasattr(agent, "_fallback_chain"):
return getattr(agent, "_fallback_chain") or []
return agent._fallback_chain or []
if hasattr(agent, "_fallback_model"):
return getattr(agent, "_fallback_model", None)
return agent._fallback_model
return _load_fallback_model()
@@ -478,23 +343,17 @@ def _background_agent_kwargs(agent, task_id: str) -> dict:
"acp_args": getattr(agent, "acp_args", None) or None,
"model": getattr(agent, "model", None) or _resolve_model(),
"max_iterations": _cfg_max_turns(cfg, 25),
"enabled_toolsets": getattr(agent, "enabled_toolsets", None)
# Detached background tasks declare platform="tui" below: they have no
# UI session id, so a renderer-routed event has nowhere to land. Resolve
# their toolsets against that same platform rather than the gateway
# process's, so they never carry GUI schema they cannot use.
or _load_enabled_toolsets("tui"),
# Detached tasks declare platform="tui" (no UI sid for renderer-routed
# events), so resolve toolsets against it — never GUI schema they can't use.
"enabled_toolsets": getattr(agent, "enabled_toolsets", None) or _load_enabled_toolsets("tui"),
"quiet_mode": True,
"verbose_logging": False,
"ephemeral_system_prompt": getattr(agent, "ephemeral_system_prompt", None)
or None,
"ephemeral_system_prompt": getattr(agent, "ephemeral_system_prompt", None) or None,
"providers_allowed": getattr(agent, "providers_allowed", None),
"providers_ignored": getattr(agent, "providers_ignored", None),
"providers_order": getattr(agent, "providers_order", None),
"provider_sort": getattr(agent, "provider_sort", None),
"provider_require_parameters": getattr(
agent, "provider_require_parameters", False
),
"provider_require_parameters": getattr(agent, "provider_require_parameters", False),
"provider_data_collection": getattr(agent, "provider_data_collection", None),
"openrouter_min_coding_score": getattr(agent, "openrouter_min_coding_score", None),
"session_id": task_id,
@@ -510,30 +369,15 @@ def _background_agent_kwargs(agent, task_id: str) -> dict:
def _ephemeral_preview_agent_kwargs(agent, task_id: str) -> dict:
kwargs = _background_agent_kwargs(agent, task_id)
kwargs.update(
{
"enabled_toolsets": ["terminal", "file"],
"session_db": None,
"skip_memory": True,
}
)
kwargs.update({"enabled_toolsets": ["terminal", "file"], "session_db": None, "skip_memory": True})
return kwargs
def _preview_restart_history(session: dict, max_messages: int = 24, max_tool_chars: int = 1200) -> list[dict]:
"""Distill the parent session's recent history into a context the
ephemeral preview-restart agent can actually use.
The restart agent has no idea what app the user was building, what
server they ran, what cwd was active, or which port belongs to which
project. Without this, it would take the bare URL + console logs and
guess — usually starting the wrong thing.
We keep the last ``max_messages`` messages from the parent session so
the restart agent sees recent user prompts, assistant replies, and
most importantly any terminal/tool calls. Tool result payloads are
truncated so we don't blow the context window with file dumps.
"""
"""Distill recent parent history for the ephemeral preview-restart agent, which
otherwise would guess app/server/cwd/port from the bare URL + console logs.
Keeps the last ``max_messages`` (always back to the last user turn); tool
results are truncated so file dumps don't blow the context window."""
try:
with session["history_lock"]:
history = list(session.get("history", []) or [])
@@ -542,20 +386,12 @@ def _preview_restart_history(session: dict, max_messages: int = 24, max_tool_cha
if not history:
return []
# Anchor on the last user turn so we always include at least the most
# recent request and the assistant/tool work that followed it. Then
# extend backwards up to max_messages so we capture the prior context.
last_user_idx = None
start = max(0, len(history) - max_messages)
for idx in range(len(history) - 1, -1, -1):
if history[idx].get("role") == "user":
last_user_idx = idx
start = min(start, idx)
break
start = max(0, len(history) - max_messages)
if last_user_idx is not None:
start = min(start, last_user_idx)
trimmed: list[dict] = []
for msg in history[start:]:
if not isinstance(msg, dict):
@@ -563,19 +399,12 @@ def _preview_restart_history(session: dict, max_messages: int = 24, max_tool_cha
role = msg.get("role")
if role not in ("user", "assistant", "tool", "system"):
continue
copy = {k: v for k, v in msg.items() if k != "reasoning"}
# Truncate heavy tool outputs so a single 50KB file read doesn't
# crowd out the rest of the context.
if role == "tool":
content = copy.get("content")
if isinstance(content, str) and len(content) > max_tool_chars:
copy["content"] = (
content[:max_tool_chars]
+ f"\n... (truncated, original {len(content)} chars)"
)
copy["content"] = content[:max_tool_chars] + f"\n... (truncated, original {len(content)} chars)"
trimmed.append(copy)
return trimmed
@@ -584,20 +413,16 @@ def _preview_tool_result_preview(name: str, result: str) -> str:
data = json.loads(result)
except Exception:
return ""
if not isinstance(data, dict):
return ""
if name == "terminal":
output = str(data.get("output") or "").strip()
exit_code = data.get("exit_code")
if output:
return output[-1200:]
if data.get("session_id"):
return f"Background process started: {data.get('session_id')}"
if exit_code is not None:
return f"terminal exited with code {exit_code}"
if data.get("exit_code") is not None:
return f"terminal exited with code {data.get('exit_code')}"
return str(data.get("error") or "").strip()[:1200]
@@ -638,40 +463,31 @@ def _preview_restart_callbacks(parent: str, task_id: str) -> dict:
def _reset_session_agent(sid: str, session: dict) -> dict:
tokens = _set_session_context(session["session_key"])
try:
# /new is a full conversation boundary: session-scoped runtime
# overrides (/model, /reasoning, /fast) do NOT carry forward — the
# fresh agent re-derives model/provider, reasoning, and service tier
# from config.yaml (#48055, #23131). Session pins are cleared below so
# a rebuild can't resurrect them. (Global process state is still never
# touched — see the cross-session-contamination note in
# _apply_model_switch.)
session.pop("model_override", None)
session.pop("create_reasoning_override", None)
session.pop("create_service_tier_override", None)
session.pop("one_turn_model_restore", None)
# /new is a full conversation boundary: session-scoped runtime overrides
# (/model, /reasoning, /fast) do NOT carry forward — the fresh agent
# re-derives them from config.yaml, and the pins are cleared so a rebuild
# can't resurrect them. Global process state is never touched (see the
# cross-session-contamination note in _apply_model_switch).
for k in ("model_override", "create_reasoning_override", "create_service_tier_override", "one_turn_model_restore"):
session.pop(k, None)
new_agent = _make_agent(
sid,
session["session_key"],
session_id=session["session_key"],
platform_override=_session_source(session),
context_cwd_is_launch_artifact=(
_context_cwd_is_launch_artifact(session)
),
context_cwd_is_launch_artifact=_context_cwd_is_launch_artifact(session),
)
finally:
_clear_session_context(tokens)
session["agent"] = new_agent
session["config_model_seen"] = _config_model_target()
session["attached_images"] = []
session["queued_prompt"] = None
session.update(
agent=new_agent, config_model_seen=_config_model_target(), attached_images=[], queued_prompt=None
)
session.pop("queued_prompts", None)
session["_queued_prompt_generation"] = int(session.get("_queued_prompt_generation", 0)) + 1
session["edit_snapshots"] = {}
session["image_counter"] = 0
session["running"] = False
session["show_reasoning"] = _load_show_reasoning()
session["tool_progress_mode"] = _load_tool_progress_mode()
session["tool_started_at"] = {}
session.update(
edit_snapshots={}, image_counter=0, running=False, show_reasoning=_load_show_reasoning(),
tool_progress_mode=_load_tool_progress_mode(), tool_started_at={},
)
with session["history_lock"]:
session["history"] = []
session["history_version"] = int(session.get("history_version", 0)) + 1
+65 -119
View File
@@ -21,8 +21,7 @@ def resolve_skin() -> dict:
return {
"name": skin.name,
"colors": skin.colors,
# Paired palettes: the TUI detects the terminal's polarity and
# prefers the matching hand-tuned block over adapting `colors`.
# Paired palettes: the TUI prefers the block matching terminal polarity.
"light_colors": skin.light_colors,
"dark_colors": skin.dark_colors,
"branding": skin.branding,
@@ -35,28 +34,39 @@ def resolve_skin() -> dict:
return {}
# Signature of the last skin broadcast: (name, active user-file mtime). Lets the
# per-tool reconcile fire ``skin.changed`` on any real move — a name switch OR a
# live color edit to the active skin — and nothing else.
# (name, user-file mtime) of the last skin broadcast: ``skin.changed`` fires on a
# name switch OR a live color edit of the active skin, and nothing else.
_last_skin_sig: tuple[str, float | None] | None = None
def _watcher_home() -> Path:
"""Active profile home for the change watcher's signature probes."""
override = get_hermes_home_override()
return Path(override if isinstance(override, str) and override else _hermes_home)
def _watcher_mtime_ns(path: Path):
"""``st_mtime_ns`` of ``path``, or None when it cannot be stat'ed."""
try:
return path.stat().st_mtime_ns
except OSError:
return None
def _skin_sig() -> tuple[str, float | None]:
"""(active skin name, its user-file mtime). Built-ins have no file, so only
their name moves; a user skin's mtime lets an in-place color edit repaint too."""
name = str((_load_cfg().get("display") or {}).get("skin") or "default")
override = get_hermes_home_override()
home = override if isinstance(override, str) and override else _hermes_home
home = _watcher_home()
try:
mtime: float | None = (Path(home) / "skins" / f"{name}.yaml").stat().st_mtime
mtime: float | None = (home / "skins" / f"{name}.yaml").stat().st_mtime
except OSError:
mtime = None
return name, mtime
def _note_skin_broadcast() -> None:
"""Sync the reconcile baseline after the /skin RPC emits, so the per-tool
check doesn't re-broadcast the skin /skin just applied."""
"""Sync the baseline after the /skin RPC emits so the watcher doesn't re-broadcast it."""
global _last_skin_sig
try:
_last_skin_sig = _skin_sig()
@@ -65,14 +75,8 @@ def _note_skin_broadcast() -> None:
def _broadcast_skin_if_changed() -> None:
"""Emit ``skin.changed`` when the active skin moved — the agent switched it
(``hermes config set display.skin``) OR edited the active skin's colors in
place ("I don't like that coral" → tweak the YAML).
Routes through the SAME live path as ``/skin`` so every surface (TUI + desktop)
repaints, no slash command. The signature check is a dict lookup + one stat,
so polling it is ~free.
"""
"""Emit ``skin.changed`` when the active skin moved, via the SAME live path as
``/skin`` so every surface repaints. The check is a dict lookup + one stat."""
global _last_skin_sig
try:
sig = _skin_sig()
@@ -87,18 +91,8 @@ def _broadcast_skin_if_changed() -> None:
pass
def _watcher_home() -> Path:
"""Active profile home for the change watcher's signature probes."""
override = get_hermes_home_override()
return Path(override if isinstance(override, str) and override else _hermes_home)
def _pet_sig() -> tuple:
"""(slug, spritesheet revision, scale) of the active pet — ("off",) when none.
Cheap by construction: config comes from the mtime-cached ``_load_cfg`` and
the sheet revision is one stat. Moves when ``/pet`` (de)activates a pet, the
hatch flow rebuilds a sheet, or the scale changes."""
"""(slug, spritesheet revision, scale) of the active pet — ("off",) when none."""
display = _load_cfg().get("display") or {}
pet_cfg = display.get("pet") if isinstance(display.get("pet"), dict) else {}
if not pet_cfg or not is_truthy_value(pet_cfg.get("enabled"), default=False):
@@ -113,8 +107,7 @@ def _pet_sig() -> tuple:
def _pet_changed_payload() -> dict:
"""``pet.info.meta``-shaped payload for ``pet.changed`` — enough for the
renderer to decide whether the heavy sprite payload needs a refetch."""
"""``pet.info.meta``-shaped payload so the renderer can decide whether to refetch sprites."""
try:
enabled, pet, scale = _pet_active_selection()
if not enabled or pet is None or not pet.exists:
@@ -131,56 +124,33 @@ def _pet_changed_payload() -> dict:
def _cron_sig():
"""mtime of the profile's cron/jobs.json — moves on create/edit/pause/
remove AND on scheduler tick bookkeeping (last_run/next_run)."""
try:
return (_watcher_home() / "cron" / "jobs.json").stat().st_mtime_ns
except OSError:
return None
"""mtime of cron/jobs.json — moves on edits AND scheduler tick bookkeeping."""
return _watcher_mtime_ns(_watcher_home() / "cron" / "jobs.json")
def _sessions_sig():
"""Newest mtime across state.db and its WAL — the cross-process change
signal. Messaging-gateway turns and cron runs are written by OTHER
processes that never touch this gateway's transports; the shared SQLite
file is the one thing they all move (#58671). A backend serving several
profiles owns one store per profile, so every served sibling home is
probed too — otherwise a routed profile's Bot Chat never refreshes."""
sig = None
for root in (_watcher_home(), *_served_profile_homes):
for name in ("state.db", "state.db-wal"):
try:
mtime = (root / name).stat().st_mtime_ns
except OSError:
continue
sig = mtime if sig is None else max(sig, mtime)
return sig
"""Newest mtime across state.db + WAL: the one thing messaging-gateway turns and
cron runs (which never touch this gateway's transports) all move. Served sibling
profile homes are probed too, else a routed profile's Bot Chat never refreshes."""
mtimes = [
_watcher_mtime_ns(root / name)
for root in (_watcher_home(), *_served_profile_homes)
for name in ("state.db", "state.db-wal")
]
return max((m for m in mtimes if m is not None), default=None)
def _platforms_sig():
"""mtime of gateway_state.json — the messaging gateway process persists
platform connect/disconnect/health there, so its movement is the
"connection status changed" signal for the Messaging page."""
try:
return (_watcher_home() / "gateway_state.json").stat().st_mtime_ns
except OSError:
return None
"""mtime of gateway_state.json — where the messaging gateway persists platform
connect/disconnect/health, i.e. the Messaging page's status-changed signal."""
return _watcher_mtime_ns(_watcher_home() / "gateway_state.json")
def _pairing_sig():
"""Newest mtime across every profile's pairing store.
An unknown DMer's pending code is written by the messaging gateway — a
DIFFERENT process that never touches this gateway's transports — so the
files are the only shared signal. ``platforms.changed`` cannot stand in
for this: it tracks connect/disconnect/health, and a pairing request
moves nothing in gateway_state.json.
"""
"""Newest mtime across every profile's pairing store (legacy ``pairing/`` and
``platforms/pairing/``). Pending codes are written by the gateway process, so the
files are the only shared signal; a pairing request moves nothing in gateway_state.json."""
home = _watcher_home()
sig = None
# Global store (legacy `pairing/` and consolidated `platforms/pairing/`)
# plus every named profile's own — the Messaging page can be scoped to any
# of them, and a request landing in a profile store must still tick.
roots = [home / "pairing", home / "platforms" / "pairing"]
try:
for profile_dir in (home / "profiles").iterdir():
@@ -189,53 +159,39 @@ def _pairing_sig():
except OSError:
pass
sig = None
for root in roots:
try:
entries = list(root.iterdir())
except OSError:
continue
for entry in entries:
# Only the pending/approved ledgers — _rate_limits.json moves on
# every unauthorized DM, including ones that produce no new row.
# Only the ledgers: _rate_limits.json moves on every unauthorized DM.
if not entry.name.endswith(("-pending.json", "-approved.json")):
continue
try:
mtime = entry.stat().st_mtime_ns
except OSError:
continue
sig = mtime if sig is None else max(sig, mtime)
mtime = _watcher_mtime_ns(entry)
if mtime is not None:
sig = mtime if sig is None else max(sig, mtime)
return sig
# Newest outbox-envelope mtime the watcher has EVER seen (monotone). A drain
# empties the outbox (rename → claimed/), and letting the signature fall back
# to None on empty would fire a spurious pending event right after every
# drain — so the signature only moves forward, on genuinely new envelopes.
# Newest outbox-envelope mtime EVER seen (monotone): a drain empties the outbox,
# and falling back to None would fire a spurious pending event after every drain.
_bot_relay_outbox_seen = 0
def _bot_relay_outbox_sig():
"""Newest mtime across pending bot-relay outbox envelopes (monotone).
Envelopes are written by the AGENT process (``message_agent`` →
``tools.bot_relay.enqueue_envelope``) — a different process that never
touches this gateway's transports — so the files are the only shared
signal, exactly like the pairing store. The Desktop reacts to
``bot_relay.outbox.pending`` with an immediate (debounced) drain instead
of waiting out its poll interval (#93091, motivated by #92760).
"""
"""Newest mtime across pending bot-relay outbox envelopes (monotone). Written by
the AGENT process, so the files are the only shared signal; the Desktop reacts
to ``bot_relay.outbox.pending`` with an immediate debounced drain."""
global _bot_relay_outbox_seen
home = _watcher_home()
root = home.parent.parent if home.parent.name == "profiles" else home
newest = 0
try:
for entry in (root / "bot_relay" / "outbox").iterdir():
if not entry.name.endswith(".json"):
continue
try:
newest = max(newest, entry.stat().st_mtime_ns)
except OSError:
continue
if entry.name.endswith(".json"):
newest = max(newest, _watcher_mtime_ns(entry) or 0)
except OSError:
pass
if newest > _bot_relay_outbox_seen:
@@ -243,25 +199,21 @@ def _bot_relay_outbox_sig():
return _bot_relay_outbox_seen or None
# Watched change signals: event → (check interval, signature fn, payload fn).
# Signatures are stat/dict-lookup cheap, same bar as the skin watcher; the
# check interval keeps the pricier probes (pet resolves the active sheet off
# disk) off the 0.5s tick.
# event → (check interval, signature fn, payload fn). Signatures are stat-cheap;
# the interval keeps pricier probes (pet resolves the sheet off disk) off the 0.5s tick.
_CHANGE_WATCHES: dict[str, tuple[float, Any, Any]] = {
"pet.changed": (2.0, _pet_sig, _pet_changed_payload),
"cron.changed": (1.0, _cron_sig, lambda: {}),
"sessions.changed": (0.5, _sessions_sig, lambda: {}),
"platforms.changed": (2.0, _platforms_sig, lambda: {}),
"pairing.changed": (2.0, _pairing_sig, lambda: {}),
# Cross-connection DM latency: 1s check so a queued envelope reaches the
# Desktop's push-triggered drain fast; the Desktop's poll stays backstop.
# 1s so a queued DM envelope reaches the Desktop's push-triggered drain fast.
"bot_relay.outbox.pending": (1.0, _bot_relay_outbox_sig, lambda: {}),
}
# state.db moves on every message append during a streaming turn, and the
# gateway rewrites gateway_state.json for in-flight-count bookkeeping; the
# floor coalesces those bursts to one broadcast per window (trailing edge
# included — a floored change keeps its old signature and re-fires next tick).
# state.db moves on every append of a streaming turn and gateway_state.json on
# in-flight bookkeeping; the floor coalesces bursts to one broadcast per window,
# trailing edge included (a floored change keeps its old signature, re-fires later).
_CHANGE_BROADCAST_FLOOR_S = {"sessions.changed": 2.0, "platforms.changed": 5.0}
_change_sigs: dict[str, Any] = {}
@@ -270,9 +222,8 @@ _change_broadcast_at: dict[str, float] = {}
def _broadcast_watched_changes(now: float | None = None) -> None:
"""One pass over ``_CHANGE_WATCHES``: recompute due signatures, broadcast
the events whose signature moved. First sighting seeds silently so a
gateway boot never fires a spurious refresh storm."""
"""One pass: recompute due signatures, broadcast events whose signature moved.
First sighting seeds silently so a gateway boot never fires a refresh storm."""
now = time.monotonic() if now is None else now
for event, (interval, sig_fn, payload_fn) in _CHANGE_WATCHES.items():
if now - _change_checked_at.get(event, -interval) < interval:
@@ -289,9 +240,7 @@ def _broadcast_watched_changes(now: float | None = None) -> None:
continue
floor = _CHANGE_BROADCAST_FLOOR_S.get(event, 0.0)
if floor and now - _change_broadcast_at.get(event, -floor) < floor:
# Floored: leave the old signature in place so the change re-fires
# once the window opens (the trailing edge of the burst).
continue
continue # floored: old signature stays so it re-fires when the window opens
_change_sigs[event] = sig
_change_broadcast_at[event] = now
try:
@@ -304,12 +253,9 @@ _skin_watcher_started = False
def _ensure_skin_watcher() -> None:
"""Watch cheap on-disk signatures and broadcast change events — so a skin
Hermes activates, a pet ``/pet`` adopts, a cron the scheduler fires, or a
messaging turn another process writes goes live on every surface within a
couple seconds, on its own, with no client-side poll in the loop.
Idempotent; started at gateway.ready. (Named for its original skin-only
duty; it is the process's one change watcher.)"""
"""Start the process's one change watcher (named for its original skin-only
duty): cheap on-disk signatures → broadcast events, so skin/pet/cron/cross-process
changes go live everywhere within seconds without client polling. Idempotent."""
global _skin_watcher_started
if _skin_watcher_started:
return
+68 -126
View File
@@ -15,10 +15,9 @@ _registry = HandlerRegistry()
_compute_host_supervisor = None
_compute_host_supervisor_lock = threading.Lock()
# Hard cap on how long session.compress blocks its RPC waiting for the compute
# host (#97948). Must stay below the desktop's SESSION_COMPRESS_TIMEOUT_MS
# (660s) so the client receives the `pending` answer instead of its own
# timeout error; the late-ack path covers anything slower.
# Cap on how long session.compress blocks its RPC on the compute host. Must stay
# below the desktop's SESSION_COMPRESS_TIMEOUT_MS (660s) so the client gets the
# `pending` answer, not its own timeout; the late-ack path covers anything slower.
_COMPUTE_HOST_COMPRESS_WAIT_CAP_SECS = 630.0
@@ -36,9 +35,8 @@ def _turn_isolation_enabled(cfg: dict | None = None) -> bool:
def _session_uses_compute_host(session: dict, cfg: dict | None = None) -> bool:
if not _turn_isolation_enabled(cfg):
return False
# Phase 1 routes lazy/dashboard sessions whose live AIAgent has not been
# built inside the serving process. Already-built in-process sessions keep
# the historical path unless a prior isolated turn marked host ownership.
# Routes lazy sessions whose AIAgent was never built in-process; already-built
# sessions keep the in-process path unless a prior isolated turn marked host ownership.
return bool(session.get("_compute_host_active")) or (
session.get("agent") is None and session.get("agent_ready") is not None
)
@@ -60,22 +58,13 @@ def _get_compute_host_supervisor(cfg: dict | None = None):
def _compute_host_turn_frame(
rid: str,
sid: str,
session: dict,
text: Any,
image_paths: list[str] | None = None,
queued_prompt_generation: int | None = None,
display_kind: str | None = None,
rid: str, sid: str, session: dict, text: Any, image_paths: list[str] | None = None,
queued_prompt_generation: int | None = None, display_kind: str | None = None,
) -> dict:
with session["history_lock"]:
history = list(session.get("history", []))
history_version = int(session.get("history_version", 0))
attached_images = (
list(image_paths)
if image_paths is not None
else list(session.get("attached_images", []))
)
attached_images = list(image_paths if image_paths is not None else session.get("attached_images", []))
return {
"type": "turn.start",
"sid": sid,
@@ -103,26 +92,44 @@ def _metadata_mirror(session: dict | None) -> dict:
return mirror if isinstance(mirror, dict) else {}
def _compute_host_session_info(session: dict) -> dict:
# Tolerate a legacy one-arg _session_info (tests patch it that way).
try:
return _session_info(session.get("agent"), session)
except TypeError:
return _session_info(session.get("agent"))
def _compute_host_adopt_frame_meta(session: dict, frame: dict) -> None:
"""Adopt a host frame's session_key / history_version. Caller holds history_lock."""
if frame.get("session_key"):
session["session_key"] = str(frame.get("session_key"))
if frame.get("history_version") is not None:
try:
session["history_version"] = max(
int(session.get("history_version", 0)),
int(frame.get("history_version") or 0),
)
except Exception:
pass
def _relay_compute_host_rpc(message: dict) -> bool:
"""Relay host events while retaining the clarify snapshot needed on resume."""
params = message.get("params") if isinstance(message, dict) else None
if isinstance(params, dict) and params.get("type") == "clarify.request":
sid = str(params.get("session_id") or "")
kind = params.get("type") if isinstance(params, dict) else None
if kind in {"clarify.request", "clarify.expire"}:
session = _sessions.get(str(params.get("session_id") or ""))
payload = params.get("payload")
session = _sessions.get(sid)
if session is not None and isinstance(payload, dict) and payload.get("request_id"):
with session.get("history_lock", threading.Lock()):
session["_compute_host_pending_clarify"] = dict(payload)
elif isinstance(params, dict) and params.get("type") == "clarify.expire":
sid = str(params.get("session_id") or "")
payload = params.get("payload")
session = _sessions.get(sid)
request_id = payload.get("request_id") if isinstance(payload, dict) else None
if session is not None and request_id:
with session.get("history_lock", threading.Lock()):
pending = session.get("_compute_host_pending_clarify")
if isinstance(pending, dict) and pending.get("request_id") == request_id:
session.pop("_compute_host_pending_clarify", None)
if kind == "clarify.request":
session["_compute_host_pending_clarify"] = dict(payload)
else:
pending = session.get("_compute_host_pending_clarify")
if isinstance(pending, dict) and pending.get("request_id") == request_id:
session.pop("_compute_host_pending_clarify", None)
return write_json(message)
@@ -185,25 +192,13 @@ def _respond_compute_host_clarify(rid: str, params: dict) -> dict | None:
def _apply_compute_host_metadata_mirror(session: dict, frame: dict | None) -> None:
"""Mirror host-owned session metadata in the serving process.
The compute host is the only writer of live agent/history state while turn
isolation is active. The serving process keeps read metadata from the last
host frame so UI reads do not construct a second in-process agent.
"""
"""Mirror host-owned session metadata: while turn isolation is active the host is
the only writer of live agent/history state, and UI reads must not build a
second in-process agent."""
if not isinstance(frame, dict):
return
with session.get("history_lock", threading.Lock()):
if frame.get("session_key"):
session["session_key"] = str(frame.get("session_key"))
if frame.get("history_version") is not None:
try:
session["history_version"] = max(
int(session.get("history_version", 0)),
int(frame.get("history_version") or 0),
)
except Exception:
pass
_compute_host_adopt_frame_meta(session, frame)
if frame.get("message_count") is not None:
try:
session["_metadata_message_count"] = int(frame.get("message_count") or 0)
@@ -218,60 +213,36 @@ def _apply_compute_host_metadata_mirror(session: dict, frame: dict | None) -> No
def _on_compute_host_turn_done(rid: str, sid: str, session: dict, frame: dict) -> None:
is_error = frame.get("type") == "turn.error"
with session["history_lock"]:
if frame.get("session_key"):
session["session_key"] = str(frame.get("session_key"))
if frame.get("history_version") is not None:
try:
session["history_version"] = max(
int(session.get("history_version", 0)),
int(frame.get("history_version") or 0),
)
except Exception:
pass
_compute_host_adopt_frame_meta(session, frame)
session["running"] = False
session["last_active"] = time.time()
_clear_inflight_turn(session)
session.pop("_compute_host_pending_clarify", None)
if is_error:
if frame.get("type") == "turn.error":
message = str(frame.get("message") or "compute host turn failed")
_emit("message.complete", sid, {"text": f"Error: {message}", "status": "error"})
_apply_compute_host_metadata_mirror(session, frame)
try:
info = _session_info(session.get("agent"), session)
except TypeError:
info = _session_info(session.get("agent"))
info = _compute_host_session_info(session)
if not frame.get("session_info_emitted"):
_emit("session.info", sid, info)
_drain_queued_prompt(rid, sid, session)
def _submit_prompt_to_compute_host(
rid: str,
sid: str,
session: dict,
text: Any,
image_paths: list[str] | None = None,
queued_prompt_generation: int | None = None,
display_kind: str | None = None,
rid: str, sid: str, session: dict, text: Any, image_paths: list[str] | None = None,
queued_prompt_generation: int | None = None, display_kind: str | None = None,
) -> dict:
cfg = _load_dashboard_process_isolation_config()
frame = _compute_host_turn_frame(
rid,
sid,
session,
text,
image_paths=image_paths,
queued_prompt_generation=queued_prompt_generation,
display_kind=display_kind,
rid, sid, session, text, image_paths=image_paths,
queued_prompt_generation=queued_prompt_generation, display_kind=display_kind,
)
def _complete(done: dict) -> None:
# submit_turn reports a synchronous pipe failure through the callback
# before re-raising. Leave the parent session untouched so prompt.submit
# can fail open to the historical in-process path without emitting a
# duplicate terminal error.
# submit_turn reports a synchronous pipe failure via the callback before
# re-raising; leave the session untouched so prompt.submit can fail open
# to the in-process path without a duplicate terminal error.
if done.get("reason") == "send_failed":
return
_on_compute_host_turn_done(rid, sid, session, done)
@@ -288,74 +259,45 @@ def _submit_prompt_to_compute_host(
def _send_compute_host_control(
sid: str,
*,
route_name: str,
command: str = "",
payload: dict | None = None,
wait: bool = True,
timeout: float = 30.0,
on_late_ack=None,
sid: str, *, route_name: str, command: str = "", payload: dict | None = None,
wait: bool = True, timeout: float = 30.0, on_late_ack=None,
) -> dict:
frame = dict(payload or {})
frame.setdefault("type", "control")
frame.setdefault("command", command)
return _get_compute_host_supervisor().control(
sid,
route_name=route_name,
payload=frame,
wait=wait,
timeout=timeout,
on_late_ack=on_late_ack,
sid, route_name=route_name, payload=frame, wait=wait, timeout=timeout, on_late_ack=on_late_ack
)
def _compute_host_compress_wait_seconds(cfg: dict | None = None) -> float:
"""RPC wait budget for a compute-host compress control (#97948).
Manual compression legitimately runs up to the configured
``compression.context_total_ceiling_seconds`` (default 600s), so a fixed
120s waiter reported a false timeout while the host kept working. Follow
the ceiling with a little slack, but cap the blocking wait so it stays
below the desktop's own RPC timeout; anything longer is adopted through
the late-ack path instead of failing.
"""
"""RPC wait budget for a compute-host compress control: the configured
``compression.context_total_ceiling_seconds`` plus slack, capped below the
desktop's RPC timeout (a fixed waiter reported false timeouts while the host
kept working); anything slower lands via the late-ack path."""
from agent.conversation_compression import resolve_context_compression_timeouts
try:
compression_cfg = (cfg if cfg is not None else _load_cfg()).get("compression", {})
except Exception:
compression_cfg = {}
_idle, ceiling = resolve_context_compression_timeouts(
compression_cfg if isinstance(compression_cfg, dict) else {}
)
_idle, ceiling = resolve_context_compression_timeouts(compression_cfg if isinstance(compression_cfg, dict) else {})
return float(min(max(ceiling + 30.0, 120.0), _COMPUTE_HOST_COMPRESS_WAIT_CAP_SECS))
def _announce_compute_host_compress_done(sid: str, session: dict, ack: dict) -> None:
"""Mirror a compute-host compress ack and push the client-visible edges.
Emits the same ``session.info`` the in-process /compress path does plus
the ``compacted`` status edge, so a client whose own RPC wait already
expired still learns the transcript changed.
"""
"""Mirror a compress ack and push the same ``session.info`` + ``compacted`` edges
the in-process /compress path emits, so a client whose RPC wait expired still
learns the transcript changed."""
_apply_compute_host_metadata_mirror(session, ack)
try:
info = _session_info(session.get("agent"), session)
except TypeError:
info = _session_info(session.get("agent"))
_emit("session.info", sid, info)
_emit("session.info", sid, _compute_host_session_info(session))
_status_update(sid, "compacted", "✓ Context compression complete")
def _adopt_late_compute_host_compress_ack(sid: str, session: dict, ack: dict, *, route_name: str) -> None:
"""Adopt a compute-host compress ack that arrived after its RPC waiter gave up.
The RPC already answered ``status: pending``; this is the only place the
rotated session_key / history_version / session_info mirror can land, and
the only signal the client gets that the transcript changed. A late
``control.error`` surfaces through the existing ``error`` event path.
"""
"""Adopt a compress ack that arrived after its RPC waiter answered ``pending``:
the only place the rotated session_key / history_version / mirror can land and
the client's only signal. A late ``control.error`` goes out via ``error``."""
with _sessions_lock:
live = _sessions.get(sid)
if live is not session:
+34 -79
View File
@@ -12,26 +12,14 @@ from .method_ctx import HandlerRegistry, bind_module
_registry = HandlerRegistry()
# ── Methods: browser / plugins / cron / skills ───────────────────────
def _resolve_browser_cdp_url() -> str:
"""Return the configured browser CDP override without network I/O.
"""Configured browser CDP override without network I/O.
``/browser status`` must be fast — calling
``tools.browser_tool._get_cdp_override`` would invoke
``_resolve_cdp_override``, which performs an HTTP probe to
``.../json/version`` for discovery-style URLs. That probe has
a multi-second timeout and would block the TUI on a slow or
unreachable host even though status only needs to report whether
an override is set.
Mirrors the env/config precedence of ``_get_cdp_override`` (env
var first, then ``browser.cdp_url`` from config.yaml) without the
websocket-resolution step, so the answer reflects user intent
even when the configured host is not currently reachable. The
actual WS normalization happens in ``browser_navigate`` on the
next tool call.
``/browser status`` must be fast: ``tools.browser_tool._get_cdp_override`` runs an
HTTP probe with a multi-second timeout for discovery-style URLs. Mirrors its
precedence (env var, then ``browser.cdp_url``) minus the WS-resolution step, so the
answer reflects user intent even when the host is unreachable; ``browser_navigate``
normalizes on the next tool call.
"""
env_url = os.environ.get("BROWSER_CDP_URL", "").strip()
if env_url:
@@ -49,23 +37,18 @@ def _resolve_browser_cdp_url() -> str:
def _is_default_local_cdp(parsed) -> bool:
"""Match the discovery-style local default; never the concrete WS form.
A user-supplied ``ws://127.0.0.1:9222/devtools/browser/<id>`` is a
real, connectable endpoint — collapsing it to bare ``http://...:9222``
would strip the path and break the connect.
"""
"""Match the discovery-style local default; never the concrete WS form — a
``ws://127.0.0.1:9222/devtools/browser/<id>`` is connectable as-is and collapsing
it to bare ``http://...:9222`` would break the connect."""
try:
port = parsed.port or 80
except ValueError:
return False
discovery_path = parsed.path in {"", "/", "/json", "/json/version"}
return (
parsed.scheme in {"http", "ws"}
and parsed.hostname in {"127.0.0.1", "localhost"}
and port == 9222
and discovery_path
and parsed.path in {"", "/", "/json", "/json/version"}
)
@@ -86,10 +69,8 @@ def _probe_urls(parsed) -> list[str]:
def _normalize_cdp_url(parsed) -> str:
# Concrete ``/devtools/browser/<id>`` endpoints (Browserbase et al.)
# are connectable as-is. Discovery-style inputs collapse to bare
# ``scheme://host:port`` so ``_resolve_cdp_override`` can append
# ``/json/version`` later without doubling the path.
# Concrete ``/devtools/browser/<id>`` endpoints stay as-is; discovery-style inputs
# collapse to ``scheme://host:port`` so ``_resolve_cdp_override`` can append ``/json/version``.
if parsed.path.startswith("/devtools/browser/"):
return parsed.geturl()
return parsed._replace(path="", params="", query="", fragment="").geturl()
@@ -123,9 +104,7 @@ def _browser_connect(rid, params: dict) -> dict:
raw_url = params.get("url")
if raw_url is not None and not isinstance(raw_url, str):
return _err(
rid, 4015, f"browser url must be a string, got {type(raw_url).__name__}"
)
return _err(rid, 4015, f"browser url must be a string, got {type(raw_url).__name__}")
url = (raw_url or "").strip() or DEFAULT_BROWSER_CDP_URL
sid = params.get("session_id") or ""
@@ -134,9 +113,7 @@ def _browser_connect(rid, params: dict) -> dict:
def announce(message: str, *, level: str = "info") -> None:
messages.append(message)
# Without a session id the TUI prints `messages` from the
# response; emitting an event would double-render. Only stream
# progress when there's a real session to scope it to.
# Without a session id the TUI prints `messages` from the response; an event would double-render.
if sid:
_emit("browser.progress", sid, {"message": message, "level": level})
@@ -150,20 +127,16 @@ def _browser_connect(rid, params: dict) -> dict:
except ValueError:
return _err(rid, 4015, f"invalid port in browser url: {url}")
# Always normalize default-local to 127.0.0.1:9222 so downstream
# comparisons + messaging match what we'll actually persist.
# Normalize default-local to 127.0.0.1:9222 so comparisons + messaging match what we persist.
if _is_default_local_cdp(parsed):
url = DEFAULT_BROWSER_CDP_URL
parsed = urlparse(url)
port = parsed.port or 9222
try:
# ws[s]://.../devtools/browser/<id> endpoints (hosted CDP
# providers) don't serve the HTTP discovery path; just check
# TCP-level reachability and let browser_navigate handshake.
if parsed.scheme in {"ws", "wss"} and parsed.path.startswith(
"/devtools/browser/"
):
# Hosted ws[s]://.../devtools/browser/<id> endpoints don't serve the HTTP discovery
# path: check TCP reachability only and let browser_navigate handshake.
if parsed.scheme in {"ws", "wss"} and parsed.path.startswith("/devtools/browser/"):
import socket
try:
@@ -179,12 +152,9 @@ def _browser_connect(rid, params: dict) -> dict:
local_port_in_use,
)
# Dual-stack discovery: when another app (an IDE debugger,
# a dev server) squats the IPv4 loopback on the debug port,
# a browser asked to bind that port comes up on [::1] only.
# An IPv4-only probe misses it AND hangs against squatters
# that accept TCP but never answer HTTP — the historic
# cause of `browser.manage` RPC timeouts.
# Dual-stack discovery: when another app squats the IPv4 loopback on the debug
# port, a browser bound there comes up on [::1] only. An IPv4-only probe misses
# it AND hangs against squatters that accept TCP but never answer HTTP.
discovered = discover_local_cdp_url(port, timeout=2.0)
launch_port = port
@@ -192,20 +162,16 @@ def _browser_connect(rid, params: dict) -> dict:
if local_port_in_use(port):
launch_port = find_free_debug_port(port)
announce(
f"Port {port} is occupied by another application that "
"isn't a CDP browser (an IDE debugger or dev server may "
f"be using it) — launching a debug browser on port "
f"{launch_port} instead..."
f"Port {port} is occupied by another application that isn't a CDP browser "
"(an IDE debugger or dev server may be using it) — launching a debug browser "
f"on port {launch_port} instead..."
)
else:
announce(
"Chromium-family browser isn't running with remote debugging — attempting to launch..."
)
announce("Chromium-family browser isn't running with remote debugging — attempting to launch...")
launch = launch_chrome_debug(launch_port, system)
if launch.launched:
# Bounded wait: the whole connect must finish well
# inside the client RPC timeout.
# Bounded wait: the whole connect must finish inside the client RPC timeout.
deadline = time.monotonic() + 10.0
while time.monotonic() < deadline:
discovered = discover_local_cdp_url(launch_port, timeout=1.0)
@@ -214,37 +180,27 @@ def _browser_connect(rid, params: dict) -> dict:
time.sleep(0.5)
if discovered:
announce(
f"Chromium-family browser launched and listening on port {launch_port}"
)
announce(f"Chromium-family browser launched and listening on port {launch_port}")
else:
hint = launch.hint
if hint:
announce(hint, level="error")
for line in _failure_messages(url, launch_port, system)[1:]:
announce(line, level="error")
return _ok(
rid, {"connected": False, "url": url, "messages": messages}
)
return _ok(rid, {"connected": False, "url": url, "messages": messages})
else:
announce(f"Chromium-family browser is already listening at {discovered}")
# Adopt whatever loopback/port actually answered (may be
# [::1] and/or an alternate port when 9222 was squatted).
# Adopt whatever loopback/port answered ([::1] and/or an alternate port when 9222 was squatted).
url = discovered
parsed = urlparse(url)
else:
probes = _probe_urls(parsed)
ok = any(_http_ok(p, timeout=2.0) for p in probes)
if not ok:
return _err(rid, 5031, f"could not reach browser CDP at {url}")
elif not any(_http_ok(p, timeout=2.0) for p in _probe_urls(parsed)):
return _err(rid, 5031, f"could not reach browser CDP at {url}")
normalized = _normalize_cdp_url(parsed)
# Order matters: reap sessions BEFORE publishing the new env
# so an in-flight tool call sees the old supervisor closed,
# then again AFTER so the default task's cached supervisor
# is drained against the new URL.
# Reap BEFORE publishing the new env (an in-flight tool call sees the old supervisor
# closed) and AFTER (the default task's cached supervisor drains against the new URL).
cleanup_all_browsers()
os.environ["BROWSER_CDP_URL"] = normalized
cleanup_all_browsers()
@@ -258,8 +214,7 @@ def _browser_connect(rid, params: dict) -> dict:
def _browser_disconnect(rid) -> dict:
# Reap, drop the env override, reap again — closes the same swap
# window covered by ``_browser_connect``.
# Reap, drop the override, reap again — same swap window as ``_browser_connect``.
def reap() -> None:
try:
from tools.browser_tool import cleanup_all_browsers
+49 -90
View File
@@ -1,8 +1,7 @@
"""Completion / model-key / paste JSON-RPC handlers.
Everything defined here is rebound onto server.py's globals at install time
(``method_ctx.bind_module``), so handlers and module-level helpers may
reference server globals bare (``_ok``, ``_err``, ``_sessions``, ...).
Rebound onto server.py's globals at install time (``method_ctx.bind_module``), so
bodies reference server globals bare (``_ok``, ``_err``, ``_sessions``, ...).
"""
@@ -55,10 +54,9 @@ def _(rid, params: dict) -> dict:
def _profile_mention_items(prefix: str) -> list[dict]:
"""`@<profile>` completions: agent profiles as mentionable names (multi-agent
UIs and the Bot Mode plugin route `@<profile>` text to another profile).
Bare-word matches only, never for `@kind:` directives. The primary profile is
also offered as 'hermes' when no real profile claims that name."""
"""`@<profile>` completions (multi-agent UIs route `@<profile>` text to another
profile). Bare-word matches only, never `@kind:` directives; the primary profile
is also offered as 'hermes' when no real profile claims that name."""
out: list[dict] = []
try:
from hermes_cli.profiles import list_profiles
@@ -83,33 +81,32 @@ def _plugin_reference_items(pfx: str, qval: str) -> list[dict] | None:
"""`@<prefix>:<query>` autocomplete for a plugin ContextReferenceProvider; None when
no provider owns ``pfx`` or it fails."""
try:
from agent.context_references import get_context_reference_providers as _gcr
from agent.context_references import get_context_reference_providers
_prov = _gcr().get(pfx)
if _prov is None:
prov = get_context_reference_providers().get(pfx)
if prov is None:
return None
import asyncio as _asyncio
import asyncio
_coro = _prov.autocomplete(qval, limit=20)
coro = prov.autocomplete(qval, limit=20)
try:
_loop = _asyncio.get_running_loop()
loop = asyncio.get_running_loop()
except RuntimeError:
_loop = None
if _loop and _loop.is_running():
import concurrent.futures as _cf
loop = None
if loop and loop.is_running():
import concurrent.futures
with _cf.ThreadPoolExecutor(max_workers=1) as _pool:
_ac = _pool.submit(_asyncio.run, _coro).result()
with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
ac = pool.submit(asyncio.run, coro).result()
else:
_ac = _asyncio.run(_coro)
return [{"text": f"@{pfx}:{it.text}", "display": it.display, "meta": it.meta} for it in _ac]
ac = asyncio.run(coro)
return [{"text": f"@{pfx}:{it.text}", "display": it.display, "meta": it.meta} for it in ac]
except Exception:
return None
def _fuzzy_basename_items(root: str, path_part: str, prefix_tag: str) -> list[dict]:
"""Fuzzy basename search across the repo for a bare `@name` (what Cursor /
VS Code do for Cmd-P); path-ish queries take the directory-listing path."""
"""Cmd-P style fuzzy basename search for a bare `@name`; path-ish queries take the listing path."""
ranked: list[tuple[tuple[int, int], str, str, bool]] = []
walked_dirs: set[str] = set()
seen: set[str] = set()
@@ -123,9 +120,8 @@ def _fuzzy_basename_items(root: str, path_part: str, prefix_tag: str) -> list[di
seen.add(rel)
ranked.append((rank, rel, name, is_dir))
# Seed with root's immediate children: `_list_repo_files` is capped at
# _FUZZY_CACHE_MAX_FILES and outside a git repo the fallback walk can burn
# the whole budget on one deep subtree before reaching a sibling.
# Seed with root's immediate children: `_list_repo_files` is capped at _FUZZY_CACHE_MAX_FILES
# and the non-git fallback walk can burn the whole budget on one deep subtree.
try:
for entry in os.listdir(root):
if entry not in _FUZZY_FALLBACK_EXCLUDES:
@@ -135,8 +131,7 @@ def _fuzzy_basename_items(root: str, path_part: str, prefix_tag: str) -> list[di
for rel in _list_repo_files(root):
_consider(rel, os.path.basename(rel), False)
# Directories are only implied by the file listing, so rank each ancestor
# too — otherwise a folder with no name-matching file inside is invisible.
# Rank each ancestor dir too — a folder with no name-matching file inside is otherwise invisible.
parent = os.path.dirname(rel)
while parent and parent not in walked_dirs:
walked_dirs.add(parent)
@@ -170,8 +165,7 @@ def _(rid, params: dict) -> dict:
if is_context and not query:
items = [_item(t, m) for t, m in _AT_DIRECTIVE_HINTS]
# Agent profiles are mentionable — `@` alone reveals them too.
items.extend(_profile_mention_items(""))
items.extend(_profile_mention_items("")) # `@` alone reveals agent profiles too
try:
from agent.context_references import get_context_reference_providers
@@ -189,8 +183,7 @@ def _(rid, params: dict) -> dict:
if plugin_items is not None:
return _ok(rid, {"items": plugin_items})
# Accept both `@folder:path` and bare `@folder` so listings appear as soon
# as the keyword is typed, without accepting the static `@folder:` hint.
# Bare `@folder` lists as soon as the keyword is typed (the static `@folder:` hint is not accepted).
if is_context and query in {"file", "folder"}:
prefix_tag, path_part = query, ""
elif is_context and query.startswith(("file:", "folder:")):
@@ -198,21 +191,15 @@ def _(rid, params: dict) -> dict:
else:
prefix_tag, path_part = "", query
# `@/foo` almost always means "foo, from here": take the absolute reading
# only when that prefix exists, else drop the slash and resolve relative
# to cwd — otherwise `@/Desktop` dead-ends. `@/usr/local` still resolves.
if (
is_context
and path_part.startswith("/")
and not path_part.startswith("//")
and not _abs_completion_prefix_exists(path_part)
):
path_part = path_part.lstrip("/")
# `@/foo` usually means "foo, from here": absolute only when that prefix exists,
# else resolve relative to cwd (`@/Desktop` must not dead-end; `@/usr/local` still resolves).
if is_context and path_part.startswith("/") and not path_part.startswith("//"):
if not _abs_completion_prefix_exists(path_part):
path_part = path_part.lstrip("/")
if is_context and path_part and len(path_part.strip()) >= 2 and "/" not in path_part and prefix_tag != "folder":
items = _fuzzy_basename_items(root, path_part, prefix_tag)
# Bare `@name` may equally be an agent mention: profiles rank ABOVE file hits.
if not prefix_tag:
if not prefix_tag: # bare `@name` may be an agent mention: profiles rank ABOVE file hits
items = _profile_mention_items(path_part) + items
return _ok(rid, {"items": items})
@@ -240,8 +227,7 @@ def _(rid, params: dict) -> dict:
continue
full = os.path.join(search_dir, entry)
is_dir = os.path.isdir(full)
# Explicit `@folder:` / `@file:` filters: skip the opposite kind rather
# than rewriting the tag (which let `@folder:` list files).
# Explicit `@folder:` / `@file:` skip the opposite kind (never rewrite the tag).
if prefix_tag and want_dir != is_dir:
continue
rel = os.path.relpath(full, root).replace(os.sep, "/")
@@ -264,8 +250,7 @@ def _(rid, params: dict) -> dict:
except Exception as e:
return _err(rid, 5021, str(e))
# Bare-word `@name` (incl. single chars, which skip the fuzzy branch) may be
# an agent mention — profiles rank above path entries.
# Bare-word `@name` (incl. single chars, which skip the fuzzy branch): profiles rank above paths.
try:
if is_context and not prefix_tag and path_part and "/" not in path_part:
items = _profile_mention_items(path_part) + items
@@ -292,15 +277,13 @@ def _(rid, params: dict) -> dict:
completer = SlashCommandCompleter(
skill_commands_provider=lambda: get_skill_commands(), skill_bundles_provider=lambda: get_skill_bundles()
)
# Skills/bundles are the only completions for an inline `/skill` typed
# mid-message, so the class reaches the TUI as data — derived from the
# completer's own providers, not sniffed from the ⚡/▣ display glyphs.
# `kind` reaches the TUI as data (from the providers, not sniffed from ⚡/▣ glyphs):
# skills/bundles are the only completions for an inline `/skill` typed mid-message.
skill_names = {key.lstrip("/").lower() for key in (*get_skill_commands(), *get_skill_bundles())}
def to_items(doc: Document) -> list[dict]:
# prompt_toolkit's display/display_meta are FormattedText; the TUI's
# CompletionItem.display contract is a plain string (the raw list
# trips Ink's row layout into 1-char truncation of the next column).
# display/display_meta are FormattedText; the TUI contract is a plain string
# (the raw list trips Ink's row layout into 1-char truncation).
return [
{
"text": c.text,
@@ -313,16 +296,12 @@ def _(rid, params: dict) -> dict:
items = to_items(Document(text, len(text)))
# Rank and bound (see _rank_slash_completions) while a `/token` is under
# the cursor — the one stage skills are offered at. An argument stage
# (`/personality `, `/details c`) keeps the order its command chose.
# Rank + bound while a `/token` is under the cursor (the one stage skills are
# offered at); an argument stage (`/personality `) keeps its command's order.
if text.rsplit(" ", 1)[-1].startswith("/"):
score_of = None
# Description-aware fuzzy scoring at the command-token stage: the
# completer only emits name-prefix matches, so merge in catalog entries
# whose name SUBSTRING or DESCRIPTION words match (`/summary` surfaces a
# command whose description mentions summaries). Name matches outrank
# description matches.
# Command-token stage: the completer only emits name-prefix matches, so merge in
# catalog entries whose name SUBSTRING or DESCRIPTION words match (name outranks description).
if " " not in text and len(text) > 1:
from tui_gateway.slash_fuzzy import fuzzy_rank_slash_items, normalize_slash_search_query
@@ -357,8 +336,8 @@ def _(rid, params: dict) -> dict:
session = _sessions.get(params.get("session_id", ""))
agent = session.get("agent") if session else None
# Once an agent is spawned IT owns the live provider/model/base_url; empty
# agent attributes must NOT clobber disk config (with_overrides is truthy-only).
# A spawned agent owns the live provider/model/base_url; empty attributes must
# NOT clobber disk config (with_overrides is truthy-only).
ctx = _model_picker_context(agent)
payload = build_model_options_payload(
ctx,
@@ -373,8 +352,7 @@ def _(rid, params: dict) -> dict:
@method("model.save_key")
def _(rid, params: dict) -> dict:
"""Save an API key for provider ``slug`` and return its refreshed provider row
(same shape as model.options entries, with ``authenticated``)."""
"""Save an API key for ``slug``; return its refreshed provider row (model.options shape + ``authenticated``)."""
try:
from hermes_cli.auth import PROVIDER_REGISTRY
from hermes_cli.config import is_managed
@@ -384,10 +362,8 @@ def _(rid, params: dict) -> dict:
api_key = (params.get("api_key") or "").strip()
if not slug or not api_key:
return _err(rid, 4001, "slug and api_key are required")
if is_managed():
return _err(rid, 4006, "managed install — credentials are read-only")
pconfig = PROVIDER_REGISTRY.get(slug)
if not pconfig:
return _err(rid, 4002, f"unknown provider: {slug}")
@@ -396,32 +372,20 @@ def _(rid, params: dict) -> dict:
if not pconfig.api_key_env_vars:
return _err(rid, 4004, f"no env var defined for {pconfig.name}")
# Unified credential lifecycle so any stale config.yaml mirror of the old
# key (model.api_key, custom_providers[*].api_key) rotates in the same action.
# Unified lifecycle rotates stale config.yaml mirrors of the old key too.
env_var = pconfig.api_key_env_vars[0]
from hermes_cli.credential_lifecycle import save_provider_env_credential
save_provider_env_credential(env_var, api_key)
import os
os.environ[env_var] = api_key # so the refreshed inventory sees it
# Shared inventory builder keeps this in lock-step with model.options and
# the dashboard; picker_hints=True carries `authenticated` for the TUI.
# Shared inventory builder (lock-step with model.options / dashboard); picker_hints carries `authenticated`.
session = _sessions.get(params.get("session_id", ""))
agent = session.get("agent") if session else None
payload = build_models_payload(_model_picker_context(agent), picker_hints=True, max_models=50)
provider_data = next((p for p in payload["providers"] if p["slug"] == slug), None)
if provider_data is None:
# Key saved but provider didn't appear — still success.
provider_data = {
"slug": slug,
"name": pconfig.name,
"is_current": False,
"models": [],
"total_models": 0,
"authenticated": True,
}
if provider_data is None: # key saved but provider didn't appear — still success
provider_data = {"slug": slug, "name": pconfig.name, "is_current": False, "models": [], "total_models": 0}
provider_data["authenticated"] = True # synthetic fallback bypasses picker_hints
return _ok(rid, {"provider": provider_data})
except Exception as e:
@@ -438,13 +402,10 @@ def _(rid, params: dict) -> dict:
slug = (params.get("slug") or "").strip()
if not slug:
return _err(rid, 4001, "slug is required")
pconfig = PROVIDER_REGISTRY.get(slug)
cleared_env = False
# Remove env vars from .env/process plus every mirror (env-seeded pool
# entries, model cache rows, value-matched config.yaml copies) — otherwise
# the provider resurrects in the picker after restart.
# Remove env vars plus every mirror (env-seeded pool entries, model cache rows,
# value-matched config.yaml copies) or the provider resurrects in the picker after restart.
if pconfig and pconfig.api_key_env_vars:
for ev in pconfig.api_key_env_vars:
if remove_provider_env_credential(ev).get("found"):
@@ -452,10 +413,8 @@ def _(rid, params: dict) -> dict:
# Full disconnect: removing OAuth grants is intended here, unlike key-only deletes.
cleared_auth = clear_provider_auth(slug)
if not cleared_env and not cleared_auth:
return _err(rid, 4005, f"no credentials found for {slug}")
return _ok(rid, {"slug": slug, "name": pconfig.name if pconfig else slug, "disconnected": True})
except Exception as e:
return _err(rid, 5035, str(e))
+54 -154
View File
@@ -18,40 +18,18 @@ _registry = HandlerRegistry()
_FUZZY_CACHE_TTL_S = 5.0
_FUZZY_CACHE_MAX_FILES = 20000
_FUZZY_FALLBACK_EXCLUDES = frozenset(
{
".git",
".hg",
".svn",
".next",
".cache",
".venv",
"venv",
"node_modules",
"__pycache__",
"dist",
"build",
"target",
".mypy_cache",
".pytest_cache",
".ruff_cache",
}
{".git", ".hg", ".svn", ".next", ".cache", ".venv", "venv", "node_modules", "__pycache__",
"dist", "build", "target", ".mypy_cache", ".pytest_cache", ".ruff_cache"}
)
_fuzzy_cache_lock = threading.Lock()
_fuzzy_cache: dict[str, tuple[float, list[str]]] = {}
def _list_repo_files(root: str) -> list[str]:
"""Return file paths relative to ``root``.
Uses ``git ls-files`` from the repo top (resolved via
``rev-parse --show-toplevel``) so the listing covers tracked + untracked
files anywhere in the repo, then converts each path back to be relative
to ``root``. Files outside ``root`` (parent directories of cwd, sibling
subtrees) are excluded so the picker stays scoped to what's reachable
from the gateway's cwd. Falls back to a bounded ``os.walk(root)`` when
``root`` isn't inside a git repo. Result cached per-root for
``_FUZZY_CACHE_TTL_S`` so rapid keystrokes don't respawn git processes.
"""
"""File paths relative to ``root`` (tracked + untracked via ``git ls-files`` from the
repo top; files outside ``root`` excluded so the picker stays Cmd-P scoped). Falls
back to a bounded ``os.walk(root)`` outside a git repo. Cached per-root for
``_FUZZY_CACHE_TTL_S`` so rapid keystrokes don't respawn git."""
now = time.monotonic()
with _fuzzy_cache_lock:
cached = _fuzzy_cache.get(root)
@@ -61,45 +39,20 @@ def _list_repo_files(root: str) -> list[str]:
files: list[str] = []
from hermes_cli._subprocess_compat import windows_hide_flags
_creationflags = windows_hide_flags()
run_kw = dict(capture_output=True, timeout=2.0, check=False, stdin=subprocess.DEVNULL, creationflags=windows_hide_flags())
try:
top_result = subprocess.run(
["git", "-C", root, "rev-parse", "--show-toplevel"],
capture_output=True,
timeout=2.0,
check=False,
stdin=subprocess.DEVNULL,
creationflags=_creationflags,
)
top_result = subprocess.run(["git", "-C", root, "rev-parse", "--show-toplevel"], **run_kw)
if top_result.returncode == 0:
top = top_result.stdout.decode("utf-8", "replace").strip()
list_result = subprocess.run(
[
"git",
"-C",
top,
"ls-files",
"-z",
"--cached",
"--others",
"--exclude-standard",
],
capture_output=True,
timeout=2.0,
check=False,
stdin=subprocess.DEVNULL,
creationflags=_creationflags,
["git", "-C", top, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], **run_kw
)
if list_result.returncode == 0:
for p in list_result.stdout.decode("utf-8", "replace").split("\0"):
if not p:
continue
rel = os.path.relpath(os.path.join(top, p), root).replace(
os.sep, "/"
)
# Skip parents/siblings of cwd — keep the picker scoped
# to root-and-below, matching Cmd-P workspace semantics.
if rel.startswith("../"):
rel = os.path.relpath(os.path.join(top, p), root).replace(os.sep, "/")
if rel.startswith("../"): # parents/siblings of cwd: keep Cmd-P workspace scope
continue
files.append(rel)
if len(files) >= _FUZZY_CACHE_MAX_FILES:
@@ -108,16 +61,11 @@ def _list_repo_files(root: str) -> list[str]:
pass
if not files:
# Fallback walk: skip vendor/build dirs + dot-dirs so the walk stays
# tractable. Dotfiles themselves survive — the ranker decides based
# on whether the query starts with `.`.
# Fallback walk skips vendor/build dirs + dot-dirs; dotfiles survive (the ranker
# decides based on whether the query starts with `.`).
try:
for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
dirnames[:] = [
d
for d in dirnames
if d not in _FUZZY_FALLBACK_EXCLUDES and not d.startswith(".")
]
dirnames[:] = [d for d in dirnames if d not in _FUZZY_FALLBACK_EXCLUDES and not d.startswith(".")]
rel_dir = os.path.relpath(dirpath, root)
for f in filenames:
rel = f if rel_dir == "." else f"{rel_dir}/{f}"
@@ -136,17 +84,9 @@ def _list_repo_files(root: str) -> list[str]:
def _fuzzy_basename_rank(name: str, query: str) -> tuple[int, int] | None:
"""Rank ``name`` against ``query``; lower is better. Returns None to reject.
Tiers (kind):
0 — exact basename
1 — basename prefix (e.g. `app` → `appChrome.tsx`)
2 — word-boundary / camelCase hit (e.g. `chrome` → `appChrome.tsx`)
3 — substring anywhere in basename
4 — subsequence match (every query char appears in order)
Secondary key is `len(name)` so shorter names win ties.
"""
"""Rank ``name`` against ``query`` as (tier, len(name)); lower wins, None rejects.
Tiers: 0 exact · 1 prefix · 2 word-boundary/camelCase hit (`chrome` → `appChrome.tsx`)
· 3 substring · 4 subsequence (query chars appear in order)."""
if not query:
return (3, len(name))
@@ -159,8 +99,7 @@ def _fuzzy_basename_rank(name: str, query: str) -> tuple[int, int] | None:
if nl.startswith(ql):
return (1, len(name))
# Word-boundary split: `foo-bar_baz.qux` → ["foo","bar","baz","qux"].
# camelCase split: `appChrome` → ["app","Chrome"]. Cheap approximation;
# Split on -_. and camelCase (`appChrome` → ["app","Chrome"]); cheap approximation,
# falls through to substring/subsequence if it misses.
parts: list[str] = []
buf = ""
@@ -191,13 +130,9 @@ def _fuzzy_basename_rank(name: str, query: str) -> tuple[int, int] | None:
def _abs_completion_prefix_exists(path_part: str) -> bool:
"""True when ``path_part`` reads sensibly as an absolute path.
A leading `/` is only meant literally if something is actually there:
the parent directory has to exist, and a partially-typed final segment
has to match at least one of its entries. Used to decide whether
`@/foo` is the absolute `/foo` or shorthand for `foo` under the cwd.
"""
"""True when ``path_part`` reads sensibly as an absolute path: the parent dir exists
and a partially-typed final segment matches at least one entry. Decides whether
`@/foo` is the absolute `/foo` or shorthand for `foo` under the cwd."""
expanded = _normalize_completion_path(path_part)
parent = os.path.dirname(expanded.rstrip("/")) or "/"
tail = os.path.basename(expanded.rstrip("/"))
@@ -219,13 +154,18 @@ def _details_completion_item(value: str, meta: str = "") -> dict:
return {"text": value, "display": value, "meta": meta}
def _details_root_completion_item(
value: str, meta: str, needs_leading_space: bool
) -> dict:
return _details_completion_item(
f" {value}" if needs_leading_space else value,
meta,
)
def _details_root_completion_item(value: str, meta: str, needs_leading_space: bool) -> dict:
return _details_completion_item(f" {value}" if needs_leading_space else value, meta)
_DETAILS_SECTIONS = ("thinking", "tools", "subagents", "activity")
_DETAILS_MODES = ("hidden", "collapsed", "expanded")
def _details_root_meta(candidate: str) -> str:
if candidate in _DETAILS_SECTIONS:
return "section override"
return "cycle global mode" if candidate == "cycle" else "global mode"
def _details_completions(text: str) -> list[dict] | None:
@@ -241,66 +181,34 @@ def _details_completions(text: str) -> list[dict] | None:
body = body[1:]
parts = body.split()
has_trailing_space = text.endswith(" ")
sections = ("thinking", "tools", "subagents", "activity")
modes = ("hidden", "collapsed", "expanded")
sections, modes = _DETAILS_SECTIONS, _DETAILS_MODES
root_candidates = (*modes, "cycle", *sections)
if not body or (len(parts) == 0 and has_trailing_space):
return [
*[
_details_root_completion_item(
mode, "global mode", not has_trailing_space
)
for mode in modes
],
_details_root_completion_item(
"cycle", "cycle global mode", not has_trailing_space
),
*[
_details_root_completion_item(
section, "section override", not has_trailing_space
)
for section in sections
],
]
return [_details_root_completion_item(c, _details_root_meta(c), not has_trailing_space) for c in root_candidates]
if len(parts) == 1 and not has_trailing_space:
prefix = parts[0].lower()
candidates = [*modes, "cycle", *sections]
return [
_details_completion_item(
candidate,
(
"section override"
if candidate in sections
else "cycle global mode" if candidate == "cycle" else "global mode"
),
)
for candidate in candidates
if candidate.startswith(prefix) and candidate != prefix
_details_completion_item(c, _details_root_meta(c))
for c in root_candidates
if c.startswith(prefix) and c != prefix
]
if len(parts) == 1 and has_trailing_space and parts[0].lower() in sections:
return [
*[
_details_completion_item(mode, f"set {parts[0].lower()}")
for mode in modes
],
_details_completion_item("reset", f"clear {parts[0].lower()} override"),
]
section = parts[0].lower() if parts else ""
if section not in sections:
return []
if len(parts) == 2 and not has_trailing_space and parts[0].lower() in sections:
def section_meta(candidate: str) -> str:
return f"clear {section} override" if candidate == "reset" else f"set {section}"
if len(parts) == 1 and has_trailing_space:
return [_details_completion_item(c, section_meta(c)) for c in (*modes, "reset")]
if len(parts) == 2 and not has_trailing_space:
prefix = parts[1].lower()
return [
_details_completion_item(
candidate,
(
f"clear {parts[0].lower()} override"
if candidate == "reset"
else f"set {parts[0].lower()}"
),
)
for candidate in (*modes, "reset")
if candidate.startswith(prefix) and candidate != prefix
_details_completion_item(c, section_meta(c)) for c in (*modes, "reset") if c.startswith(prefix) and c != prefix
]
return []
@@ -313,30 +221,22 @@ def _model_picker_context(agent):
ctx = load_picker_context()
provider = getattr(agent, "provider", "") if agent else ""
base_url = getattr(agent, "base_url", "") if agent else ""
model = getattr(agent, "model", "") if agent else ""
if str(provider or "").strip().lower() == "custom":
try:
from hermes_cli.runtime_provider import canonical_custom_identity
provider = (
canonical_custom_identity(
base_url=base_url or None,
config_provider=ctx.current_provider,
model=(getattr(agent, "model", "") if agent else "")
or None,
base_url=base_url or None, config_provider=ctx.current_provider, model=model or None
)
or provider
)
except Exception:
logger.debug(
"custom provider identity recovery failed (model picker)",
exc_info=True,
)
logger.debug("custom provider identity recovery failed (model picker)", exc_info=True)
return ctx.with_overrides(
current_provider=provider,
current_model=(getattr(agent, "model", "") if agent else "")
or _resolve_model(),
current_base_url=base_url,
current_provider=provider, current_model=model or _resolve_model(), current_base_url=base_url
)
+148 -396
View File
@@ -1,13 +1,8 @@
"""``config.set`` — one JSON-RPC method, dispatched on ``key`` through a table.
Handlers are rebound onto server.py's globals at install time (see
method_ctx.bind_module), so bodies reference server.py globals bare
(``_ok``, ``_err``, ``_load_cfg``, ``_sessions``, ``_write_config_key``, ...).
Each ``_set_*`` handler takes ``(rid, params, key, value, session)`` and returns
the JSON-RPC envelope. Table order does not matter: keys are exact matches
except ``details_mode.<section>`` (prefix) and ``_DISPLAY_TOGGLE_KEYS`` (set),
which are tried after the exact table, in that order.
Bodies are rebound onto server.py's globals (method_ctx.bind_module) and reference them bare.
Each ``_set_*`` handler takes ``(rid, params, key, value, session)`` and returns the JSON-RPC
envelope. Keys match exactly except ``details_mode.<section>`` (prefix) and ``_DISPLAY_TOGGLE_KEYS``.
"""
import os
@@ -29,18 +24,17 @@ def _display_section(cfg: dict) -> dict:
return display if isinstance(display, dict) else {}
def _write_display_sections(*, thinking=None, **display_fields) -> None:
"""Persist ``display.<field>`` values and optionally ``display.sections.thinking``.
Write-back round-trip through the raw (uncached) config so other keys survive.
"""
def _write_display_sections(*, sections=None, drop_sections=(), **display_fields) -> None:
"""Persist ``display.<field>`` + ``display.sections`` edits via the raw (uncached) config write-back."""
cfg = _load_cfg_raw()
display = _display_section(cfg)
sections = display.get("sections") if isinstance(display.get("sections"), dict) else {}
cur = display.get("sections")
cur = cur if isinstance(cur, dict) else {}
display.update(display_fields)
if thinking is not None:
sections["thinking"] = thinking
display["sections"] = sections
cur.update(sections or {})
for name in drop_sections:
cur.pop(name, None)
display["sections"] = cur
cfg["display"] = display
_save_cfg(cfg)
@@ -72,6 +66,21 @@ def _toggle_display_bool(rid, key, value, *, cfg_key, on_words, off_words):
return _ok(rid, {"key": key, "value": "on" if nv_b else "off"})
def _cfgset_await_agent(session, rid):
"""Wait for an in-progress agent build; the error envelope if it failed, else None."""
init_err = _wait_agent(session, rid)
if init_err:
return init_err
if session.get("agent") is None:
return _err(rid, 5032, "agent initialization failed")
return None
def _cfgset_model_ok(rid, key, value, warning, confirm_required, confirm_message, scope, **extra):
return _ok(rid, {"key": key, "value": value, "warning": warning, "confirm_required": confirm_required,
"confirm_message": confirm_message, "scope": scope, **extra})
# ── per-key handlers ──────────────────────────────────────────────────
@@ -80,165 +89,74 @@ def _set_model(rid, params, key, value, session):
try:
if not value:
return _err(rid, 4002, "model value required")
confirmed = bool(params.get("confirm_expensive_model", False))
if session:
from hermes_cli.model_switch import parse_model_switch_args
# A live swap can't run in-place while a turn streams:
# agent.switch_model() mutates self.model / self.provider /
# self.base_url / self.client, and the worker thread running
# agent.run_conversation reads those every iteration — a
# mid-turn swap can fire an HTTP request with the new base_url
# but old model (400/404s). So instead of rejecting the pick
# (the old 4009), stash it and apply it at the NEXT turn start
# (_apply_pending_model_switch), where nothing is in flight.
# The user gets to pick, keep typing, and send the next turn on
# the new model without waiting for the swap or interrupting.
sid = params.get("session_id", "")
# No live swap while a turn streams: agent.switch_model() mutates model/provider/
# base_url/client that the worker thread reads every iteration. Stash the pick and
# apply it at the NEXT turn start (_apply_pending_model_switch).
if session.get("running"):
parsed = parse_model_switch_args(value)
try:
pending_model = parsed.model_input
except Exception:
pending_model = str(value)
pending_provider = (
getattr(parsed, "explicit_provider", "") or ""
).strip()
confirmed = bool(params.get("confirm_expensive_model", False))
# Run the selection guards HERE, not only at apply time.
# This branch used to answer confirm_required=False without
# consulting them, so a client that implements the confirm
# round-trip was told no consent was needed. It stashed the
# pick, and _apply_pending_model_switch -- which calls the
# guards with the stashed (unconfirmed) flag -- dropped the
# switch at the next turn start. The model reverted with no
# confirm ever offered, because the one moment a round-trip
# was possible had already passed.
pending_provider = (getattr(parsed, "explicit_provider", "") or "").strip()
# Selection guards run HERE (the only moment a confirm round-trip is possible);
# otherwise an unconfirmed stashed pick is dropped at turn start, never confirmed.
if not confirmed:
pending_warning = _pending_switch_selection_warning(
pending_model, pending_provider
)
pending_warning = _pending_switch_selection_warning(pending_model, pending_provider)
if pending_warning is not None:
# Nothing is stashed: an unconfirmed guarded pick
# leaves the session exactly as it was, and the
# client re-sends with confirm_expensive_model to
# queue it for real.
return _ok(
rid,
{
"key": key,
"value": pending_model,
# `confirm_message` is the field to read.
# `warning` carries the same text only so
# clients written before the confirm
# round-trip existed still show something;
# `_apply_pending_model_switch` already
# prefers confirm_message and falls back to
# warning. Keep them identical or drop
# `warning` -- do not let them diverge.
"warning": pending_warning,
"confirm_required": True,
"confirm_message": pending_warning,
"scope": "session",
"deferred": False,
},
# Nothing stashed; the client re-sends with confirm_expensive_model.
# `confirm_message` is canonical, `warning` its legacy alias — identical.
return _cfgset_model_ok(
rid, key, pending_model, pending_warning, True, pending_warning, "session", deferred=False
)
session["pending_model_switch"] = {
"raw": value,
"confirm_expensive_model": confirmed,
# The resolved model/provider the next turn will run on.
# _session_info reports these while the switch is pending
# so the end-of-turn settle keeps showing the user's pick
# instead of blipping back to the still-live old model.
# _session_info reports these while pending so the end-of-turn settle keeps
# showing the user's pick instead of the still-live old model.
"display_model": pending_model,
"display_provider": pending_provider,
}
return _ok(
rid,
{
"key": key,
"value": pending_model,
"warning": "",
"confirm_required": False,
"confirm_message": "",
"scope": "session",
"deferred": True,
},
)
return _cfgset_model_ok(rid, key, pending_model, "", False, "", "session", deferred=True)
parsed_flags = parse_model_switch_args(value)
explicit_provider = parsed_flags.explicit_provider
failed_agent_init = (
session.get("agent") is None
and session.get("agent_error") is not None
)
failed_agent_init = session.get("agent") is None and session.get("agent_error") is not None
failed_ready = session.get("agent_ready") if failed_agent_init else None
if failed_agent_init:
if failed_ready is None:
return _err(
rid,
5032,
session.get("agent_error")
or "agent initialization failed",
)
return _err(rid, 5032, session.get("agent_error") or "agent initialization failed")
if not failed_ready.wait(timeout=30.0):
return _err(rid, 5032, "agent initialization timed out")
failed_agent_init = (
failed_agent_init
and session.get("agent") is None
and session.get("agent_error") is not None
and session.get("agent_ready") is failed_ready
and failed_ready.is_set()
failed_agent_init and session.get("agent") is None and session.get("agent_error") is not None
and session.get("agent_ready") is failed_ready and failed_ready.is_set()
)
if (
session.get("agent") is None
and not explicit_provider.strip()
and not failed_agent_init
):
session_id = params.get("session_id", "")
_start_agent_build(session_id, session)
init_err = _wait_agent(session, rid)
if session.get("agent") is None and not explicit_provider.strip() and not failed_agent_init:
_start_agent_build(sid, session)
init_err = _cfgset_await_agent(session, rid)
if init_err:
return init_err
if session.get("agent") is None:
return _err(rid, 5032, "agent initialization failed")
with _session_profile_runtime_scope(session):
result = _apply_model_switch(
params.get("session_id", ""),
session,
value,
confirm_expensive_model=bool(
params.get("confirm_expensive_model", False)
),
parsed_flags=parsed_flags,
sid, session, value, confirm_expensive_model=confirmed, parsed_flags=parsed_flags
)
if failed_agent_init and not result.get("confirm_required"):
_restart_completed_failed_agent_build(
params.get("session_id", ""), session, failed_ready
)
init_err = _wait_agent(session, rid)
_restart_completed_failed_agent_build(sid, session, failed_ready)
init_err = _cfgset_await_agent(session, rid)
if init_err:
return init_err
if session.get("agent") is None:
return _err(rid, 5032, "agent initialization failed")
with _session_profile_runtime_scope(session):
_persist_live_session_runtime(session)
else:
result = _apply_model_switch(
"",
{"agent": None},
value,
confirm_expensive_model=bool(
params.get("confirm_expensive_model", False)
),
)
return _ok(
rid,
{
"key": key,
"value": result["value"],
"warning": result["warning"],
"confirm_required": result.get("confirm_required", False),
"confirm_message": result.get("confirm_message", ""),
"scope": result.get("scope", "session"),
},
result = _apply_model_switch("", {"agent": None}, value, confirm_expensive_model=confirmed)
return _cfgset_model_ok(
rid, key, result["value"], result["warning"], result.get("confirm_required", False),
result.get("confirm_message", ""), result.get("scope", "session"),
)
except Exception as e:
return _err(rid, 5001, str(e))
@@ -250,20 +168,14 @@ def _set_fast(rid, params, key, value, session):
if agent is not None:
current_tier = getattr(agent, "service_tier", None)
elif session is not None and session.get("create_service_tier_override") is not None:
# Pre-build session with a pinned tier (desktop draft pick or an
# earlier session-scoped toggle) — report/toggle from the pin, not
# the global default.
# Pre-build session with a pinned tier: report/toggle from the pin, not the global.
current_tier = session["create_service_tier_override"] or None
else:
current_tier = _load_service_tier()
current_fast = current_tier == "priority"
if raw in {"status"}:
return _ok(
rid,
{"key": key, "value": {"priority": "fast", None: "normal"}.get(current_tier, current_tier)},
)
return _ok(rid, {"key": key, "value": {"priority": "fast", None: "normal"}.get(current_tier, current_tier)})
if raw in {"", "toggle"}:
nv = "normal" if current_fast else "fast"
elif raw in {"fast", "on"}:
@@ -282,42 +194,21 @@ def _set_fast(rid, params, key, value, session):
if agent is not None:
target_model = getattr(agent, "model", None)
else:
# A pre-build session may already have a picked model riding in
# model_override (desktop draft) — validate fast support against
# THAT model, not the global default it will never use.
# A pre-build session may carry a picked model (desktop draft) — validate against THAT.
session_override = (session or {}).get("model_override") or {}
target_model = (
session_override.get("model")
if isinstance(session_override, dict)
else None
) or _resolve_model()
target_model = (isinstance(session_override, dict) and session_override.get("model")) or _resolve_model()
if not target_model:
return _err(
rid,
4002,
"fast mode is not available without a selected model",
)
return _err(rid, 4002, "fast mode is not available without a selected model")
overrides = resolve_fast_mode_overrides(
target_model,
provider=getattr(agent, "provider", None),
base_url=getattr(agent, "base_url", None),
target_model, provider=getattr(agent, "provider", None), base_url=getattr(agent, "base_url", None)
)
if overrides is None:
return _err(
rid,
4002,
"fast mode is not available for this model",
)
return _err(rid, 4002, "fast mode is not available for this model")
if session is not None:
# Session-scoped, like `reasoning` below (global persistence is
# `--global` / Settings → Model territory). Writing config.yaml
# here let every desktop model-menu selection (per-model fast
# preset) rewrite the user's global agent.service_tier — flipping
# fast mode for every OTHER session, profile, CLI, and gateway
# build ("switch one session, switches everywhere"). Pin the
# create override so lazily-built sessions and rebuilds (/new,
# deferred resume) keep the choice; "" pins normal explicitly.
# Session-scoped like `reasoning` (global persistence is `--global` / Settings → Model):
# writing config.yaml here flipped fast mode for every other session/profile/CLI/gateway.
# The create override keeps the choice across lazy builds and rebuilds; "" pins normal.
session["create_service_tier_override"] = {"fast": "priority", "normal": ""}.get(nv, nv)
else:
_write_config_key("agent.service_tier", nv)
@@ -330,7 +221,7 @@ def _set_fast(rid, params, key, value, session):
current_overrides.update(overrides)
agent.request_overrides = current_overrides
_persist_live_session_runtime(session)
_emit("session.info", params.get("session_id", ""), _session_info(agent, session))
_emit_session_info(params.get("session_id", ""), session)
return _ok(rid, {"key": key, "value": nv})
@@ -346,20 +237,13 @@ def _set_busy(rid, params, key, value, session):
def _set_verbose(rid, params, key, value, session):
cycle = ["off", "new", "all", "verbose"]
cur = (
session.get("tool_progress_mode", _load_tool_progress_mode())
if session
else _load_tool_progress_mode()
)
cur = session.get("tool_progress_mode", _load_tool_progress_mode()) if session else _load_tool_progress_mode()
if value and value != "cycle":
nv = str(value).strip().lower()
if nv not in cycle:
return _err(rid, 4002, f"unknown verbose mode: {value}")
else:
try:
idx = cycle.index(cur)
except ValueError:
idx = 2
idx = cycle.index(cur) if cur in cycle else 2
nv = cycle[(idx + 1) % len(cycle)]
_write_config_key("display.tool_progress", nv)
if session:
@@ -371,16 +255,9 @@ def _set_verbose(rid, params, key, value, session):
def _set_focus(rid, params, key, value, session):
# Focus view — display-only reduced-output mode (/focus). Composes with
# the tool_progress machinery rather than duplicating it: enabling it
# pins tool_progress to "off" (the same value /verbose off uses) after
# stashing the configured mode, and disabling it restores that mode.
# Nothing about the request payload changes.
from hermes_cli.focus_view import (
FOCUS_TOOL_PROGRESS_MODE,
normalize_tool_progress_mode,
resolve_focus_arg,
)
# Focus view (/focus): display-only reduced output composed with tool_progress — enabling
# stashes the configured mode and pins tool_progress "off"; disabling restores the stash.
from hermes_cli.focus_view import FOCUS_TOOL_PROGRESS_MODE, normalize_tool_progress_mode, resolve_focus_arg
d_f = _display_section(_load_cfg())
cur_focus = bool(d_f.get("focus_view", False))
@@ -388,30 +265,16 @@ def _set_focus(rid, params, key, value, session):
if action == "usage":
return _err(rid, 4002, f"unknown focus value: {value} (use on|off|status)")
if action == "status" or target is None:
return _ok(
rid,
{
"key": key,
"value": "on" if cur_focus else "off",
"tool_progress": _load_tool_progress_mode(),
},
)
return _ok(rid, {"key": key, "value": "on" if cur_focus else "off", "tool_progress": _load_tool_progress_mode()})
if target:
saved = normalize_tool_progress_mode(
(d_f.get("focus_saved_tool_progress") or _load_tool_progress_mode())
if cur_focus
else _load_tool_progress_mode()
)
_write_config_key("display.focus_saved_tool_progress", saved)
saved = (cur_focus and d_f.get("focus_saved_tool_progress")) or _load_tool_progress_mode()
_write_config_key("display.focus_saved_tool_progress", normalize_tool_progress_mode(saved))
_write_config_key("display.tool_progress", FOCUS_TOOL_PROGRESS_MODE)
effective = FOCUS_TOOL_PROGRESS_MODE
else:
saved = normalize_tool_progress_mode(
d_f.get("focus_saved_tool_progress") or "all"
)
_write_config_key("display.tool_progress", saved)
effective = saved
effective = normalize_tool_progress_mode(d_f.get("focus_saved_tool_progress") or "all")
_write_config_key("display.tool_progress", effective)
_write_config_key("display.focus_view", bool(target))
if session:
@@ -419,144 +282,95 @@ def _set_focus(rid, params, key, value, session):
session["tool_progress_mode"] = effective
agent_f = session.get("agent")
if agent_f is not None:
try:
with contextlib.suppress(Exception):
agent_f.tool_progress_mode = effective
except Exception:
pass
return _ok(
rid,
{
"key": key,
"value": "on" if target else "off",
"tool_progress": effective,
},
)
return _ok(rid, {"key": key, "value": "on" if target else "off", "tool_progress": effective})
def _set_approval_mode(rid, params, key, value, session):
raw = str(value or "").strip().lower()
if raw not in _APPROVAL_MODES:
return _err(
rid,
4002,
f"unknown approval mode: {value}; pick one of manual|smart|off",
)
return _err(rid, 4002, f"unknown approval mode: {value}; pick one of manual|smart|off")
_write_config_key("approvals.mode", raw)
_emit_all_session_info()
return _ok(rid, {"key": "approvals.mode", "value": raw})
def _set_yolo(rid, params, key, value, session):
# Approval bypass. Two scopes:
# scope="session" (default) — same as the TUI's Shift+Tab. Toggles
# ONLY this session's _session_yolo flag; never touches global
# config, so CLI / TUI / cron behavior is unaffected.
# scope="global" (Shift+click the zap) — flips the persistent global
# approvals.mode in config.yaml between "off" (bypass on) and
# "manual" (bypass off). This DOES affect every session, the CLI,
# the TUI, and cron, and survives restarts.
# Approval bypass. scope="session" (default; TUI Shift+Tab) toggles ONLY this session's flag.
# scope="global" (Shift+click the zap) flips persistent approvals.mode between "off" (bypass
# on) and "manual" (bypass off) for every surface, surviving restarts.
scope = str(params.get("scope") or "session").strip().lower()
try:
from tools.approval import (
disable_session_yolo,
enable_session_yolo,
is_session_yolo_enabled,
)
from tools.approval import disable_session_yolo, enable_session_yolo, is_session_yolo_enabled
raw = str(value or "").strip().lower()
def _resolve_toggle(current: bool) -> bool:
if raw in {"1", "on", "true", "yes"}:
return True
if raw in {"0", "off", "false", "no"}:
return False
return not current
return _BOOL_WORDS.get(raw, not current)
if scope == "global":
from tools.approval import _normalize_approval_mode
cfg = _load_cfg()
appr = cfg.get("approvals") if isinstance(cfg, dict) else None
if not isinstance(appr, dict):
appr = {}
current = _normalize_approval_mode(appr.get("mode", "manual")) == "off"
enable = _resolve_toggle(current)
# Toggle between full bypass and the default manual gate. We do
# not try to restore a prior "smart"/custom mode — the zap is a
# binary on/off affordance; users with bespoke modes set them in
# config.yaml.
appr = appr if isinstance(appr, dict) else {}
enable = _resolve_toggle(_normalize_approval_mode(appr.get("mode", "manual")) == "off")
# Binary affordance: no restore of a prior "smart"/custom mode (those live in config.yaml).
_write_config_key("approvals.mode", "off" if enable else "manual")
nv = "1" if enable else "0"
# Reflect the global flip in every live session's indicator.
_emit_all_session_info()
return _ok(rid, {"key": key, "value": nv, "scope": "global"})
_emit_all_session_info() # reflect the flip in every live indicator
return _ok(rid, {"key": key, "value": "1" if enable else "0", "scope": "global"})
if session:
current = is_session_yolo_enabled(session["session_key"])
enable = _resolve_toggle(current)
if enable:
enable_session_yolo(session["session_key"])
nv = "1"
else:
disable_session_yolo(session["session_key"])
nv = "0"
skey = session["session_key"]
enable = _resolve_toggle(is_session_yolo_enabled(skey))
(enable_session_yolo if enable else disable_session_yolo)(skey)
_emit_session_info(params.get("session_id", ""), session)
else:
current = is_truthy_value(os.environ.get("HERMES_YOLO_MODE"))
enable = _resolve_toggle(current)
enable = _resolve_toggle(is_truthy_value(os.environ.get("HERMES_YOLO_MODE")))
if enable:
os.environ["HERMES_YOLO_MODE"] = "1"
nv = "1"
else:
os.environ.pop("HERMES_YOLO_MODE", None)
nv = "0"
return _ok(rid, {"key": key, "value": nv, "scope": "session"})
return _ok(rid, {"key": key, "value": "1" if enable else "0", "scope": "session"})
except Exception as e:
return _err(rid, 5001, str(e))
# /reasoning display words: (accepted inputs, reported value, display field, sections.thinking,
# session show_reasoning or None). full/clamp mirror the CLI's reasoning_full toggle; the TUI
# renders thinking as an expand/collapse section and display.reasoning_full is persisted too.
_REASONING_DISPLAY_WORDS = (
({"show", "on"}, "show", {"show_reasoning": True}, "expanded", True),
({"hide", "off"}, "hide", {"show_reasoning": False}, "hidden", False),
({"full", "all"}, "full", {"reasoning_full": True}, "expanded", None),
({"clamp", "collapse", "short"}, "clamp", {"reasoning_full": False}, "collapsed", None),
)
def _set_reasoning(rid, params, key, value, session):
try:
from hermes_constants import parse_reasoning_effort
arg = str(value or "").strip().lower()
scope = str(params.get("scope") or "").strip().lower()
global_scope = scope == "global"
if arg in {"show", "on"}:
_write_display_sections(show_reasoning=True, thinking="expanded")
if session:
session["show_reasoning"] = True
return _ok(rid, {"key": key, "value": "show"})
if arg in {"hide", "off"}:
_write_display_sections(show_reasoning=False, thinking="hidden")
if session:
session["show_reasoning"] = False
return _ok(rid, {"key": key, "value": "hide"})
# /reasoning full | clamp — parity with the classic CLI's reasoning_full
# toggle. The TUI renders thinking as an expand/collapse section, so full
# maps to sections.thinking=expanded and clamp to collapsed;
# display.reasoning_full is persisted too so CLI and TUI stay consistent.
if arg in {"full", "all"}:
_write_display_sections(reasoning_full=True, thinking="expanded")
return _ok(rid, {"key": key, "value": "full"})
if arg in {"clamp", "collapse", "short"}:
_write_display_sections(reasoning_full=False, thinking="collapsed")
return _ok(rid, {"key": key, "value": "clamp"})
for words, reported, fields, thinking, show in _REASONING_DISPLAY_WORDS:
if arg in words:
_write_display_sections(sections={"thinking": thinking}, **fields)
if show is not None and session:
session["show_reasoning"] = show
return _ok(rid, {"key": key, "value": reported})
parsed = parse_reasoning_effort(arg)
if parsed is None:
return _err(rid, 4002, f"unknown reasoning value: {value}")
if global_scope or session is None:
if scope == "global" or session is None:
_write_config_key("agent.reasoning_effort", arg)
if session is not None:
session.pop("create_reasoning_override", None)
else:
# Session-scoped, like the messaging gateway's `/reasoning <level>`
# (global persistence is `--global` / Settings → Model territory).
# Writing config.yaml here let every desktop model-menu selection
# rewrite the user's global agent.reasoning_effort to the preset default.
# Session-scoped like the messaging gateway's `/reasoning <level>`; otherwise every
# desktop model-menu pick rewrote the global default.
session["create_reasoning_override"] = parsed
if session and session.get("agent") is not None:
session["agent"].reasoning_config = parsed
@@ -571,54 +385,33 @@ def _set_details_mode(rid, params, key, value, session):
nv = str(value or "").strip().lower()
if nv not in _DETAIL_MODES:
return _err(rid, 4002, f"unknown details_mode: {value}")
cfg = _load_cfg_raw() # write-back round-trip
display = _display_section(cfg)
sections = display.get("sections") if isinstance(display.get("sections"), dict) else {}
display["details_mode"] = nv
for section in _DETAIL_SECTION_NAMES:
sections[section] = nv
display["sections"] = sections
cfg["display"] = display
_save_cfg(cfg)
_write_display_sections(sections={section: nv for section in _DETAIL_SECTION_NAMES}, details_mode=nv)
return _ok(rid, {"key": key, "value": nv})
def _set_details_section(rid, params, key, value, session):
# Per-section override: `details_mode.<section>` writes to
# `display.sections.<section>`. Empty value clears the explicit override and
# lets frontend resolution apply built-in section defaults before the global
# details_mode.
# `details_mode.<section>` -> `display.sections.<section>`. Empty value clears the explicit
# override so the frontend applies built-in section defaults before the global details_mode.
section = key.split(".", 1)[1]
if section not in _DETAIL_SECTION_NAMES:
return _err(rid, 4002, f"unknown section: {section}")
cfg = _load_cfg_raw() # write-back round-trip
display = _display_section(cfg)
sections_cfg = display.get("sections") if isinstance(display.get("sections"), dict) else {}
nv = str(value or "").strip().lower()
if not nv:
sections_cfg.pop(section, None)
_write_display_sections(drop_sections=(section,))
elif nv not in _DETAIL_MODES:
return _err(rid, 4002, f"unknown details_mode: {value}")
else:
sections_cfg[section] = nv
display["sections"] = sections_cfg
cfg["display"] = display
_save_cfg(cfg)
_write_display_sections(sections={section: nv})
return _ok(rid, {"key": key, "value": nv})
def _set_thinking_mode(rid, params, key, value, session):
nv = str(value or "").strip().lower()
allowed_tm = frozenset({"collapsed", "truncated", "full"})
if nv not in allowed_tm:
if nv not in {"collapsed", "truncated", "full"}:
return _err(rid, 4002, f"unknown thinking_mode: {value}")
_write_config_key("display.thinking_mode", nv)
# Backward compatibility bridge: keep details_mode aligned.
_write_config_key(
"display.details_mode", "expanded" if nv == "full" else "collapsed"
)
_write_config_key("display.details_mode", "expanded" if nv == "full" else "collapsed")
return _ok(rid, {"key": key, "value": nv})
@@ -633,8 +426,7 @@ def _set_battery(rid, params, key, value, session):
def _set_theme(rid, params, key, value, session):
# TUI light/dark mode pin: 'light'/'dark' beat background
# auto-detection (xterm.js hosts misreport OSC 11); 'auto' trusts it.
# 'light'/'dark' pin beats background auto-detection (xterm.js hosts misreport OSC 11).
raw = str(value or "").strip().lower()
if raw not in {"auto", "light", "dark"}:
return _err(rid, 4002, f"unknown theme value: {value} (use auto|light|dark)")
@@ -645,7 +437,6 @@ def _set_theme(rid, params, key, value, session):
def _set_statusbar(rid, params, key, value, session):
raw = str(value or "").strip().lower()
current = _coerce_statusbar(_display_section(_load_cfg()).get("tui_statusbar", "top"))
if raw in {"", "toggle"}:
nv = "top" if current == "off" else "off"
elif raw == "on":
@@ -654,42 +445,30 @@ def _set_statusbar(rid, params, key, value, session):
nv = raw
else:
return _err(rid, 4002, f"unknown statusbar value: {value}")
_write_config_key("display.tui_statusbar", nv)
return _ok(rid, {"key": key, "value": nv})
def _set_mouse(rid, params, key, value, session):
# Explicit None check rather than `value or ""` so falsy non-string
# inputs (0, False) reach the alias map as themselves — both map to
# 'off' via _MOUSE_TRACKING_ALIASES — instead of being collapsed to
# '' and triggering the toggle path. The slash command always passes
# a string, but programmatic JSON-RPC callers may send booleans.
# Explicit None check (not `value or ""`) so falsy non-string inputs (0, False from
# programmatic callers) reach the alias map as themselves (-> 'off') instead of toggling.
raw = ("" if value is None else str(value)).strip().lower()
current = _display_mouse_tracking(_display_section(_load_cfg()))
if raw in {"", "toggle"}:
nv = "all" if current == "off" else "off"
elif raw in _MOUSE_TRACKING_ALIASES:
nv = _MOUSE_TRACKING_ALIASES[raw]
else:
return _err(rid, 4002, f"unknown mouse value: {value}")
_write_config_key("display.mouse_tracking", nv)
return _ok(rid, {"key": key, "value": nv})
def _set_indicator(rid, params, key, value, session):
# Use an explicit None check rather than `value or ""` so falsy
# non-string inputs (0, False, []) still surface as themselves
# in the error message instead of looking like a blank value.
# Explicit None check so falsy non-string inputs (0, False, []) surface in the error message.
raw = ("" if value is None else str(value)).strip().lower()
if raw not in INDICATOR_STYLES:
return _err(
rid,
4002,
f"unknown indicator: {raw!r}; pick one of {'|'.join(INDICATOR_STYLES)}",
)
return _err(rid, 4002, f"unknown indicator: {raw!r}; pick one of {'|'.join(INDICATOR_STYLES)}")
_write_config_key("display.tui_status_indicator", raw)
return _ok(rid, {"key": key, "value": raw})
@@ -703,50 +482,39 @@ def _set_cwd(rid, params, key, value, session):
return _err(rid, 4002, f"working directory does not exist: {raw}")
_write_config_key("terminal.cwd", cwd)
os.environ["TERMINAL_CWD"] = cwd
return _ok(
rid,
{"key": "terminal.cwd", "value": cwd, "cwd": cwd, "branch": _git_branch_for_cwd(cwd)},
)
return _ok(rid, {"key": "terminal.cwd", "value": cwd, "cwd": cwd, "branch": _git_branch_for_cwd(cwd)})
def _set_prompt_like(rid, params, key, value, session):
try:
cfg = _load_cfg_raw() # write-back round-trip ("prompt" saves cfg)
resp = {"key": key, "value": value}
if key == "prompt":
if value == "clear":
cfg.pop("custom_prompt", None)
nv = ""
resp["value"] = ""
else:
cfg["custom_prompt"] = value
nv = value
_save_cfg(cfg)
elif key == "personality":
sid_key = params.get("session_id", "")
pname, new_prompt = _validate_personality(str(value or ""), cfg)
# Personality text is an in-session overlay. Persistence goes
# through hermes_cli.personality (single owner) and never
# touches the user-owned global system prompt.
# Personality text is an in-session overlay; persistence goes through
# hermes_cli.personality (single owner), never the user-owned global system prompt.
from hermes_cli.personality import persist_personality
persist_personality(pname)
nv = str(value or "none")
history_reset, info = _apply_personality_to_session(
sid_key, session, new_prompt, pname
)
else:
_write_config_key(f"display.{key}", value)
nv = value
if key == "skin":
# Every connected surface repaints, not just the RPC's
# client; then sync the watcher baseline so the poll loop
# doesn't re-broadcast the skin this RPC just applied.
_broadcast_global_event("skin.changed", resolve_skin())
_note_skin_broadcast()
resp = {"key": key, "value": nv}
if key == "personality":
resp["value"] = str(value or "none")
history_reset, info = _apply_personality_to_session(params.get("session_id", ""), session, new_prompt, pname)
resp["history_reset"] = history_reset
if info is not None:
resp["info"] = info
else:
_write_config_key(f"display.{key}", value)
if key == "skin":
# Every connected surface repaints; then sync the watcher baseline so the poll
# loop doesn't re-broadcast the skin this RPC just applied.
_broadcast_global_event("skin.changed", resolve_skin())
_note_skin_broadcast()
return _ok(rid, resp)
except Exception as e:
return _err(rid, 5001, str(e))
@@ -763,29 +531,13 @@ def _set_display_toggle(rid, params, key, value, session):
# ── dispatch ──────────────────────────────────────────────────────────
_CONFIG_SETTERS = {
"model": _set_model,
"fast": _set_fast,
"busy": _set_busy,
"verbose": _set_verbose,
"focus": _set_focus,
"approval_mode": _set_approval_mode,
"approvals.mode": _set_approval_mode,
"yolo": _set_yolo,
"reasoning": _set_reasoning,
"details_mode": _set_details_mode,
"thinking_mode": _set_thinking_mode,
"density": _set_density,
"battery": _set_battery,
"theme": _set_theme,
"statusbar": _set_statusbar,
"mouse": _set_mouse,
"indicator": _set_indicator,
"cwd": _set_cwd,
"terminal.cwd": _set_cwd,
"workdir": _set_cwd,
"prompt": _set_prompt_like,
"personality": _set_prompt_like,
"skin": _set_prompt_like,
"model": _set_model, "fast": _set_fast, "busy": _set_busy, "verbose": _set_verbose, "focus": _set_focus,
"approval_mode": _set_approval_mode, "approvals.mode": _set_approval_mode, "yolo": _set_yolo,
"reasoning": _set_reasoning, "details_mode": _set_details_mode, "thinking_mode": _set_thinking_mode,
"density": _set_density, "battery": _set_battery, "theme": _set_theme, "statusbar": _set_statusbar,
"mouse": _set_mouse, "indicator": _set_indicator,
"cwd": _set_cwd, "terminal.cwd": _set_cwd, "workdir": _set_cwd,
"prompt": _set_prompt_like, "personality": _set_prompt_like, "skin": _set_prompt_like,
}
+61 -72
View File
@@ -1,79 +1,68 @@
"""Image-generation JSON-RPC handler (ws twin of the image_generate tool).
"""Image-generation JSON-RPC handler (ws twin of the image_generate tool), so UI
surfaces (avatar pickers, artifact panes) can generate directly. The result is
returned as a data URL: a remote desktop can't read a gateway file path and hosted
URLs are often CORS-opaque to a renderer canvas.
Desktop plugins reach the backend only through ws JSON-RPC; the image
generation capability existed solely as a model tool. ``image.generate``
lets UI surfaces (avatar pickers, artifact panes) generate directly.
The result image is returned as a data URL (``image_data``): a remote
desktop client cannot read a file path on the gateway host, and hosted
result URLs are often CORS-opaque to a renderer canvas. Data URLs work
identically over local and remote gateways.
Handlers are rebound onto server.py's globals at install time (see
method_ctx.py) — helpers must stay nested inside the handler body.
Bodies are rebound onto server.py's globals at install time (see
method_ctx.bind_module), so they reference server.py globals bare.
"""
from .method_ctx import HandlerRegistry
from .method_ctx import HandlerRegistry, bind_module
_registry = HandlerRegistry()
method = _registry.method
def _image_gen_available() -> bool:
try:
from tools.image_generation_tool import check_image_generation_requirements
return bool(check_image_generation_requirements())
except Exception:
return False
def _image_to_data_url(ref: str, cap: int):
"""Fetch a URL or read a local path into a data URL; None when missing, over *cap*, or failing."""
import base64
import mimetypes
import os
try:
if ref.startswith(("http://", "https://")):
import urllib.request
req = urllib.request.Request(ref, headers={"User-Agent": "hermes-agent"})
with urllib.request.urlopen(req, timeout=60) as resp:
if resp.length is not None and resp.length > cap:
return None
data = resp.read(cap + 1)
mime = resp.headers.get_content_type() or "image/png"
elif os.path.isfile(ref):
if os.path.getsize(ref) > cap:
return None
with open(ref, "rb") as fh:
data = fh.read(cap + 1)
mime = mimetypes.guess_type(ref)[0] or "image/png"
else:
return None
if len(data) > cap:
return None
if not mime.startswith("image/"):
mime = "image/png"
return f"data:{mime};base64,{base64.b64encode(data).decode('ascii')}"
except Exception:
return None
@method("image.generate")
def _(rid, params: dict) -> dict:
"""Generate an image with the configured backend.
Params: ``prompt`` (required unless ``probe``), ``aspect_ratio``
(landscape|square|portrait), ``probe`` (return availability only),
``max_bytes`` (cap on the returned data URL payload, default 8MB).
Result: ``{available, success, image, image_data, error}`` where
``image`` is the backend's URL/path and ``image_data`` is a data URL
of the downloaded bytes (omitted when the download fails — callers
should fall back to ``image``).
"""
def _availability() -> bool:
try:
from tools.image_generation_tool import check_image_generation_requirements
return bool(check_image_generation_requirements())
except Exception:
return False
def _to_data_url(ref: str, cap: int):
"""Fetch a URL or read a local path into a data URL, size-capped."""
import base64
import mimetypes
import os
try:
if ref.startswith(("http://", "https://")):
import urllib.request
req = urllib.request.Request(ref, headers={"User-Agent": "hermes-agent"})
with urllib.request.urlopen(req, timeout=60) as resp:
if resp.length is not None and resp.length > cap:
return None
data = resp.read(cap + 1)
mime = resp.headers.get_content_type() or "image/png"
elif os.path.isfile(ref):
if os.path.getsize(ref) > cap:
return None
with open(ref, "rb") as fh:
data = fh.read(cap + 1)
mime = mimetypes.guess_type(ref)[0] or "image/png"
else:
return None
if len(data) > cap:
return None
if not mime.startswith("image/"):
mime = "image/png"
return f"data:{mime};base64,{base64.b64encode(data).decode('ascii')}"
except Exception:
return None
available = _availability()
"""Params: ``prompt`` (required unless ``probe``), ``aspect_ratio``
(landscape|square|portrait), ``probe`` (availability only), ``max_bytes`` (cap
on the data URL, default 8MB, max 16MB). Result: ``{available, success, image,
image_data, error}`` — ``image_data`` is omitted when the download fails, so
callers fall back to ``image`` (the backend's URL/path)."""
available = _image_gen_available()
if is_truthy_value(params.get("probe", False)):
return _ok(rid, {"available": available})
if not available:
@@ -99,10 +88,9 @@ def _(rid, params: dict) -> dict:
try:
from tools.image_generation_tool import _handle_image_generate
# Full provider dispatcher — the same path the model tool takes:
# source-image confinement, plugin-registered providers, managed
# Krea routing, then the in-tree FAL fallback. Calling the FAL leaf
# (image_generate_tool) directly here bypassed configured providers.
# Full provider dispatcher — same path as the model tool (source-image
# confinement, plugin providers, managed routing, FAL fallback); calling
# the FAL leaf directly bypassed configured providers.
raw = _handle_image_generate({"prompt": prompt, "aspect_ratio": aspect})
result = json.loads(raw)
except Exception as e:
@@ -120,11 +108,12 @@ def _(rid, params: dict) -> dict:
image_ref = str(result.get("image") or "")
payload = {"available": True, "success": True, "image": image_ref}
data_url = _to_data_url(image_ref, cap) if image_ref else None
data_url = _image_to_data_url(image_ref, cap) if image_ref else None
if data_url:
payload["image_data"] = data_url
return _ok(rid, payload)
def register(server) -> None:
_registry.install(server)
"""Publish this module's helpers + handlers onto ``server``, rebound to its globals."""
bind_module(globals(), server, skip=("_",))
+237 -319
View File
@@ -1,14 +1,9 @@
"""Profile JSON-RPC handlers — the ws twin of the dashboard's /api/profiles.
"""Profile JSON-RPC handlers — the ws twin of the dashboard's /api/profiles (desktop plugins
only have the ws door), on the same `hermes_cli.profiles` primitives.
Desktop plugins reach the backend only through the ws JSON-RPC door, so bot rosters
and profile pickers need profile enumeration/creation/editing here, delegating to
the same `hermes_cli.profiles` primitives the REST endpoints use.
Every function here is rebound onto server.py's globals at install time
(method_ctx.bind_module): bodies use server.py globals bare (`_ok`, `_err`, `os`,
`json`, `Path`, `is_truthy_value`, `get_hermes_home`, `*_hermes_home_override`,
`_profile_ui_meta_lock`), and module-level names are published onto server.py, so
they must not collide with its own globals.
Bodies are rebound onto server.py's globals (method_ctx.bind_module) and use them bare
(`_ok`, `_err`, `os`, `json`, `Path`, `is_truthy_value`, `get_hermes_home`, ...); module-level
names are published onto server.py, so they must not collide with its globals.
"""
import contextlib
@@ -20,16 +15,24 @@ method = _registry.method
# ext -> mime; iteration order is the on-disk lookup order for assets.
_ASSET_EXTS = {"png": "image/png", "jpg": "image/jpeg", "webp": "image/webp"}
# session.list's deny-list: sub-agent and kanban dispatcher workers.
_WORKER_SOURCES = frozenset({"kanban", "tool"})
def _profile_handler(name: str, code: int):
"""``@method(name)`` whose body's uncaught exception becomes ``_err(rid, code, str(e))``."""
def deco(fn):
def handler(rid, params: dict) -> dict:
try:
return fn(rid, params)
except Exception as e:
return _err(rid, code, str(e))
return method(name)(handler)
return deco
def _lazy(module, name):
"""Late-bound attribute lookup (the wrapped modules are heavy / cyclic at import time).
Uses the ``__import__`` builtin: rebound bodies only see server.py globals, so this
module's own imports (e.g. ``importlib``) are NOT available here.
"""
"""Late-bound attribute lookup (heavy / cyclic modules). ``__import__`` builtin on purpose:
rebound bodies see only server.py globals, not this module's imports."""
return getattr(__import__(module, fromlist=[name]), name)
@@ -69,28 +72,21 @@ def _hermes_home_scope(path):
reset_hermes_home_override(token)
def _profile_dir_or_err(rid, name):
"""``(profile_dir, None)`` for an existing profile, else ``(None, 4064 error)``."""
from hermes_cli.profiles import get_profile_dir
profile_dir = Path(get_profile_dir(name))
if not profile_dir.is_dir():
return None, _err(rid, 4064, f"profile '{name}' not found")
return profile_dir, None
def _resolve_profile(rid, params):
"""``(name, profile_dir, err)`` — err is the 4063 (name required) / 4064 (not found) response."""
name = str(params.get("name") or "").strip()
if not name:
return name, None, _err(rid, 4063, "name required")
profile_dir, err = _profile_dir_or_err(rid, name)
return name, profile_dir, err
from hermes_cli.profiles import get_profile_dir
profile_dir = Path(get_profile_dir(name))
if not profile_dir.is_dir():
return name, None, _err(rid, 4064, f"profile '{name}' not found")
return name, profile_dir, None
def _read_profile_yaml(profile_dir) -> dict:
"""profile.yaml as a mapping; ``{}`` when missing, unparseable, or not a mapping."""
import yaml
meta_path = profile_dir / "profile.yaml"
loaded = (yaml.safe_load(meta_path.read_text(encoding="utf-8")) or {}) if meta_path.is_file() else {}
return loaded if isinstance(loaded, dict) else {}
@@ -102,12 +98,9 @@ def _clean_revisions(raw: dict) -> dict:
def _latest_message_preview(db, session_id):
"""Excerpt (≤80 chars) of the NEWEST active user/assistant message, or "".
Messaging-app semantics for rosters (latest exchange), unlike the first-message
preview session lists use for recognition. Agent-delivery prefixes are kept.
Same query shape as ``SessionDB.latest_message_row_id`` — keep them in step.
"""
"""≤80-char excerpt of the NEWEST active user/assistant message, or "" (roster semantics:
latest exchange, not the first-message preview). Same query shape as
``SessionDB.latest_message_row_id`` — keep them in step."""
try:
with db._lock:
row = db._conn.execute(
@@ -126,12 +119,8 @@ def _latest_message_preview(db, session_id):
def _open_profile_session_db_readonly(profile_path):
"""Read-only attach for roster previews, or None.
A writable ``SessionDB()`` waits up to 20s for the write lock and runs schema init;
the roster polls every 5s while the live backend holds the writer, which stalled the
RPC past the desktop timeout. ``read_only=True`` takes neither the lock nor the DDL.
"""
"""Read-only attach for roster previews, or None. A writable ``SessionDB()`` waits up to
20s for the write lock + runs DDL; the 5s roster poll stalled past the desktop timeout."""
db_path = Path(profile_path) / "state.db"
if not _try(db_path.exists, False):
return None
@@ -139,11 +128,8 @@ def _open_profile_session_db_readonly(profile_path):
def _resurrect_recoverable_canonical(db, profile_path, session_id):
"""Un-archive an accidentally archived canonical row, or False.
Recoverability is judged on the read-only handle first; the write uses a
short-lived writable handle so the 20s lock patience is never paid on the poll.
"""
"""Un-archive an accidentally archived canonical row, or False. Recoverability is judged on
the read-only handle; the write uses a short-lived writable handle."""
try:
row = db.get_session(session_id)
if not row or not row.get("archived"):
@@ -163,14 +149,10 @@ def _resurrect_recoverable_canonical(db, profile_path, session_id):
def _canonical_session_row(db, profile_path):
"""Summary of the profile's canonical "Bot Chat" registry row, or None.
Identity is the NAME (UNIQUE(title) ⇒ ≤1 row), so preview and click target agree
without a client pointer. Exact lookup: hidden rows resolve (canonical chats are
always hidden); lineages resolve via ``get_compression_tip``, NOT the resume walker
whose unmarked-child fallback can pick an ordinary child. Worker sources count as
absent. ``id`` is the durable registry row, ``resolved_id`` the live tip.
"""
"""Summary of the profile's canonical "Bot Chat" row, or None. Identity is the NAME, so
preview and click target agree without a client pointer. Hidden rows resolve; lineages
via ``get_compression_tip`` (NOT the resume walker's unmarked-child fallback); worker
sources count as absent. ``id`` is the registry row, ``resolved_id`` the live tip."""
if db is None:
return None
try:
@@ -178,10 +160,9 @@ def _canonical_session_row(db, profile_path):
if not row:
return None
session_id = str(row.get("id") or "").strip()
if not session_id or (row.get("source") or "").strip().lower() in _WORKER_SOURCES:
if not session_id or _denied_source(row):
return None
# Archived usually means the user retired it — report absent — but the
# ws-orphan reaper / older cleanup can archive by accident: resurrect those.
# Archived = retired (absent), except accidental reaper archives: resurrect those.
if row.get("archived") and not _resurrect_recoverable_canonical(db, profile_path, session_id):
return None
tip = _try(lambda: db.get_compression_tip(session_id), None) or session_id
@@ -202,22 +183,18 @@ def _canonical_session_row(db, profile_path):
def _latest_profile_session_rows(db):
"""(newest human-facing session, newest worker session) for a profile.
The second is the newest DENIED row so rosters can show a profile as working
even though worker sessions never surface in conversation lists (workers
heartbeat ``last_activity_at`` every ≤60s; the client picks a liveness window).
"""
"""(newest human-facing session, newest worker session). The worker row lets rosters show
a profile as working (workers heartbeat ``last_activity_at`` every ≤60s)."""
if db is None:
return None, None
try:
human = worker = None
for s in db.list_sessions_rich(source=None, limit=20, order_by_last_active=True, compact_rows=True):
src = (s.get("source") or "").strip().lower()
title = s.get("title") or ""
last_active = s.get("last_active") or s.get("started_at") or 0
if src in _WORKER_SOURCES:
if _denied_source(s):
if worker is None:
src = (s.get("source") or "").strip().lower()
worker = {"id": s["id"], "source": src, "title": title, "last_active": last_active}
continue
if human is not None:
@@ -251,50 +228,53 @@ def _profile_session_fields(row, profile_path):
_best_effort(db.close)
@method("profiles.list")
def _profile_ui_meta_fields(row: dict, profile_dir) -> None:
"""Attach ``ui_meta`` / ``ui_meta_revisions`` / ``has_avatar`` from profile.yaml + assets.
Client-agnostic UI metadata lives in profile.yaml so every client paints the
same roster. ``ui_meta_revisions`` is always present: it feature-detects
gateway-owned CAS even for a brand-new profile.
"""
row["ui_meta_revisions"] = {}
raw_meta = _try(lambda: _read_profile_yaml(profile_dir), {})
ui_meta = raw_meta.get("ui_meta")
if isinstance(ui_meta, dict) and ui_meta:
row["ui_meta"] = ui_meta
revisions = raw_meta.get("_ui_meta_revisions")
if isinstance(revisions, dict) and revisions:
row["ui_meta_revisions"] = _try(lambda: _clean_revisions(revisions), {})
# Cheap existence flag so rosters skip a get_asset probe per paint.
row["has_avatar"] = _try(lambda: any((profile_dir / "assets" / f"avatar.{e}").is_file() for e in _ASSET_EXTS), False)
@_profile_handler("profiles.list", 5061)
def _(rid, params: dict) -> dict:
"""List Hermes profiles (name, path, model, description, skill count).
``include_sessions`` (default true) adds ``last_session`` / ``worker_session``
/ ``canonical_session`` so a roster paints per-agent previews without N calls.
"""
try:
from hermes_cli.profiles import list_profiles
include_sessions = is_truthy_value(params.get("include_sessions", True))
out = []
for p in list_profiles():
row = {
"name": p.name,
"path": str(p.path),
"is_default": bool(p.is_default),
"model": p.model,
"provider": p.provider,
"description": getattr(p, "description", "") or "",
"display_name": getattr(p, "display_name", "") or "",
"skill_count": getattr(p, "skill_count", 0) or 0,
}
if include_sessions:
_profile_session_fields(row, p.path)
# Client-agnostic UI metadata lives in profile.yaml so every client paints
# the same roster. ``ui_meta_revisions`` is always present: it
# feature-detects gateway-owned CAS even for a brand-new profile.
profile_dir = Path(str(p.path))
row["ui_meta_revisions"] = {}
raw_meta = _try(lambda: _read_profile_yaml(profile_dir), {})
ui_meta = raw_meta.get("ui_meta")
if isinstance(ui_meta, dict) and ui_meta:
row["ui_meta"] = ui_meta
revisions = raw_meta.get("_ui_meta_revisions")
if isinstance(revisions, dict) and revisions:
row["ui_meta_revisions"] = _try(lambda: _clean_revisions(revisions), {})
# Cheap existence flag so rosters skip a get_asset probe per paint.
row["has_avatar"] = _try(lambda: any((profile_dir / "assets" / f"avatar.{e}").is_file() for e in _ASSET_EXTS), False)
out.append(row)
# Capability flag: this backend injects the Bot Mode teammate-messaging
# protocol into every session, so clients must not append it to SOUL.md.
return _ok(rid, {"profiles": out, "bot_mode_protocol": True})
except Exception as e:
return _err(rid, 5061, str(e))
from hermes_cli.profiles import list_profiles
include_sessions = is_truthy_value(params.get("include_sessions", True))
out = []
for p in list_profiles():
row = {
"name": p.name,
"path": str(p.path),
"is_default": bool(p.is_default),
"model": p.model,
"provider": p.provider,
"description": getattr(p, "description", "") or "",
"display_name": getattr(p, "display_name", "") or "",
"skill_count": getattr(p, "skill_count", 0) or 0,
}
if include_sessions:
_profile_session_fields(row, p.path)
_profile_ui_meta_fields(row, Path(str(p.path)))
out.append(row)
# Capability flag: this backend injects the Bot Mode teammate-messaging
# protocol into every session, so clients must not append it to SOUL.md.
return _ok(rid, {"profiles": out, "bot_mode_protocol": True})
def _has_real_env_content(env_path) -> bool:
@@ -320,30 +300,21 @@ def _mirror_env(path, launch_home) -> bool:
def _mirror_auth(path, launch_home) -> bool:
"""Copy the launch auth.json when absent, dropping single-use OAuth grants.
Skipped under ``share_auth`` so the profile reads token state via the global-root
fallback (refreshes write through): a copy forks token state and the first refresh
in either store strands the other. Static .env keys have no refresh semantics.
"""
"""Copy the launch auth.json when absent (skipped under ``share_auth``: a copy forks token
state and the first refresh in either store strands the other)."""
src, dst = launch_home / "auth.json", path / "auth.json"
if not (src.is_file() and not dst.exists()):
return False
_copy_secret_file(src, dst)
# Never fork single-use OAuth grants (Anthropic / Codex / xAI): the first profile
# to refresh strands every sibling. API keys stay; OAuth rows are dropped and
# read from the root grant via the pool fallback.
# Drop single-use OAuth grants (first refresh strands every sibling); they read from
# the root grant via the pool fallback. API keys stay.
_best_effort(lambda: _lazy("hermes_cli.auth", "strip_cloned_single_use_oauth_grants")(path))
return True
def _mirror_voice_sections(path) -> bool:
"""Copy voice config (stt/tts/voice) from the launch profile; True if written.
Dictation/TTS resolve ``stt`` inside the TARGET profile's home, and a fresh
profile has only a ``model`` section, so voice fell back to defaults. Goes
through the canonical loaders under the home override (config-read-guard).
"""
"""Copy stt/tts/voice sections from the launch profile (a fresh profile has only ``model``,
so voice fell back to defaults); True if written. Canonical loaders under the home override."""
try:
from hermes_cli.config import load_config_readonly, read_user_config_raw, save_config
src_cfg = load_config_readonly() or {}
@@ -351,9 +322,8 @@ def _mirror_voice_sections(path) -> bool:
if not sections:
return False
with _hermes_home_scope(path):
# Round-trip the RAW file: load_config() merges DEFAULT_CONFIG, making every
# section look present (no-op mirror) and save_config would then persist
# the whole default tree into the fresh profile.
# RAW file: load_config() merges DEFAULT_CONFIG (every section looks present
# and save_config would persist the whole default tree).
dst_cfg = read_user_config_raw() or {}
missing = {k: v for k, v in sections.items() if k not in dst_cfg}
if missing:
@@ -365,14 +335,9 @@ def _mirror_voice_sections(path) -> bool:
def _inherit_launch_model(path) -> bool:
"""Inherit the launch profile's model.provider/default when the new profile has none.
Gate on the MODEL SECTION being absent, not on config.yaml existing: voice
mirroring legitimately creates the file first, and a file-existence gate
silently skipped inheritance for every non-clone bot. Clones keep theirs.
"""
"""Inherit launch model.provider/default when the new profile has none. Gate on the MODEL
SECTION, not config.yaml existing: voice mirroring creates the file first."""
from hermes_cli.config import load_config_readonly, read_user_config_raw
with _hermes_home_scope(path):
dst_model = (read_user_config_raw() or {}).get("model") or {}
if dst_model.get("provider") and dst_model.get("default"):
@@ -385,17 +350,34 @@ def _inherit_launch_model(path) -> bool:
return True
def _mirror_launch_credentials(path, params: dict) -> dict:
"""Copy launch .env / auth.json / voice sections into a new profile (best-effort per item).
``share_auth`` reports ``auth: "shared"`` and skips the auth copy; ``mirror_credentials``
false skips everything. ``model_inherited`` is filled in by the caller.
"""
mirrored = {"env": False, "auth": False, "model_inherited": False, "voice": False}
share_auth = is_truthy_value(params.get("share_auth", False))
if share_auth:
mirrored["auth"] = "shared"
if not is_truthy_value(params.get("mirror_credentials", True)):
return mirrored
launch_home = get_hermes_home()
mirrored["env"] = _try(lambda: _mirror_env(path, launch_home), False)
if not share_auth:
mirrored["auth"] = _try(lambda: _mirror_auth(path, launch_home), False)
mirrored["voice"] = _mirror_voice_sections(path)
return mirrored
@method("profiles.create")
def _(rid, params: dict) -> dict:
"""Create a profile — the ws twin of POST /api/profiles.
"""Create a profile (ws twin of POST /api/profiles).
Params: ``name`` (lowercase slug), ``description``, ``clone_from`` (omitted =
fresh profile with bundled skills), ``clone_all``, ``no_skills``, ``soul``,
``model`` + ``provider`` (optional pin), ``share_auth``, ``mirror_credentials``
(default true: copy the launch .env, auth.json and voice sections; inherit its
model when unpinned). Mirroring exists because ``create_profile()`` seeds a
comment-only .env and never copies auth.json, so a headlessly created profile had
NO inference provider and no interactive ``hermes setup`` to recover.
Params: ``name``, ``description``, ``clone_from`` (omitted = fresh + bundled skills),
``clone_all``, ``no_skills``, ``soul``, ``model`` + ``provider``, ``share_auth``,
``mirror_credentials`` (default true). Mirroring exists because ``create_profile()``
seeds a comment-only .env and no auth.json — a headless profile had NO provider.
"""
name = str(params.get("name") or "").strip()
if not name:
@@ -405,9 +387,7 @@ def _(rid, params: dict) -> dict:
clone_from = str(params.get("clone_from") or "").strip() or None
clone_all = is_truthy_value(params.get("clone_all", False))
path = profiles_mod.create_profile(
name=name,
clone_from=clone_from,
clone_all=clone_all,
name=name, clone_from=clone_from, clone_all=clone_all,
clone_config=bool(clone_from) and not clone_all,
no_skills=is_truthy_value(params.get("no_skills", False)),
description=str(params.get("description") or "").strip() or None,
@@ -417,37 +397,22 @@ def _(rid, params: dict) -> dict:
except Exception as e:
return _err(rid, 5062, str(e))
# Mirror the CLI/REST create flow: bundled skills for fresh profiles, then the
# alias wrapper. Both best-effort.
# CLI/REST create flow: bundled skills for fresh profiles, then the alias wrapper.
if not clone_from:
_best_effort(lambda: profiles_mod.seed_profile_skills(path, quiet=True))
_best_effort(lambda: profiles_mod.check_alias_collision(name) or profiles_mod.create_wrapper_script(name))
soul = params.get("soul")
soul_written = False
if isinstance(soul, str) and soul.strip():
soul_written = _best_effort(lambda: (path / "SOUL.md").write_text(soul, encoding="utf-8"))
mirrored = {"env": False, "auth": False, "model_inherited": False, "voice": False}
share_auth = is_truthy_value(params.get("share_auth", False))
if share_auth:
mirrored["auth"] = "shared"
mirror = is_truthy_value(params.get("mirror_credentials", True))
if mirror:
launch_home = get_hermes_home()
mirrored["env"] = _try(lambda: _mirror_env(path, launch_home), False)
if not share_auth:
mirrored["auth"] = _try(lambda: _mirror_auth(path, launch_home), False)
mirrored["voice"] = _mirror_voice_sections(path)
mirrored = _mirror_launch_credentials(path, params)
model = str(params.get("model") or "").strip()
provider = str(params.get("provider") or "").strip()
model_set = False
if model and provider:
model_set = _best_effort(lambda: _pin_profile_model(path, provider, model))
elif mirror:
elif is_truthy_value(params.get("mirror_credentials", True)):
mirrored["model_inherited"] = _try(lambda: _inherit_launch_model(path), False)
return _ok(
rid,
{"ok": True, "name": name, "path": str(path), "soul_written": soul_written, "model_set": model_set, "mirrored": mirrored},
@@ -455,12 +420,8 @@ def _(rid, params: dict) -> dict:
def _describe_toolsets(cfg):
"""``(toolsets, pinned_set)`` as the `hermes tools` checklist presents them.
Configurable universe minus platform-restricted, enablement resolved as the runtime
does. The raw registry leaks internal platform composites and reports everything
"enabled" when the profile has no pin.
"""
"""``(toolsets, pinned_set)`` as the `hermes tools` checklist presents them (the raw registry
leaks platform composites and reports everything "enabled" without a pin)."""
from hermes_cli.tools_config import _get_effective_configurable_toolsets, _get_platform_tools, _toolset_allowed_for_platform
from toolsets import resolve_toolset
pinned = (cfg.get("tools") if isinstance(cfg.get("tools"), dict) else {}).get("enabled_toolsets")
@@ -472,8 +433,7 @@ def _describe_toolsets(cfg):
if not _toolset_allowed_for_platform(ts_name, "cli"):
continue
enabled = ts_name in pinned_set if pinned_set is not None else ts_name in platform_enabled
# Default-off integrations (a2a, spotify, ...) and the equally opt-in yuanbao
# are noise in a per-profile editor unless already enabled.
# Default-off integrations (+ opt-in yuanbao) are noise unless already enabled.
if (ts_name in default_off or ts_name == "yuanbao") and not enabled:
continue
tool_count = _try(lambda: len(set(resolve_toolset(ts_name))), 0)
@@ -503,57 +463,45 @@ def _describe_mcp_servers(cfg):
)
@method("profiles.describe")
@_profile_handler("profiles.describe", 5063)
def _(rid, params: dict) -> dict:
"""Full configuration snapshot of one profile, for an editor UI.
Result: ``{name, description, soul, model: {provider, default}, skills:
[{name, enabled}], toolsets: [...], toolsets_pinned, mcp_servers}``. Skill
enablement mirrors the disabled-list model (installed = enabled unless in
``skills.disabled``). All reads are scoped to the profile via the home override.
"""
try:
name, profile_dir, err = _resolve_profile(rid, params)
if err is not None:
return err
with _hermes_home_scope(profile_dir):
from hermes_cli.config import load_config
from hermes_cli.skills_config import get_disabled_skills
cfg = load_config() or {}
disabled = {s.lower() for s in get_disabled_skills(cfg)}
skills_root = profile_dir / "skills"
installed = [
{"name": md.parent.name, "enabled": md.parent.name.lower() not in disabled}
for md in (sorted(skills_root.rglob("SKILL.md")) if skills_root.is_dir() else ())
]
toolsets_out, pinned_set = _describe_toolsets(cfg)
soul = _read_text_if_file(profile_dir / "SOUL.md")
mcp_out = _describe_mcp_servers(cfg)
model_cfg = cfg.get("model") if isinstance(cfg.get("model"), dict) else {}
meta = _try(lambda: _lazy("hermes_cli.profiles", "read_profile_meta")(profile_dir), {})
result = {
"name": name,
"description": str(meta.get("description") or ""),
"soul": soul,
"model": {"provider": str(model_cfg.get("provider") or ""), "default": str(model_cfg.get("default") or "")},
"skills": installed,
"toolsets": toolsets_out,
"toolsets_pinned": pinned_set is not None,
"mcp_servers": mcp_out,
}
return _ok(rid, result)
except Exception as e:
return _err(rid, 5063, str(e))
"""Editor snapshot: ``{name, description, soul, model, skills: [{name, enabled}], toolsets,
toolsets_pinned, mcp_servers}``; installed skills are enabled unless in ``skills.disabled``."""
name, profile_dir, err = _resolve_profile(rid, params)
if err is not None:
return err
with _hermes_home_scope(profile_dir):
from hermes_cli.config import load_config
from hermes_cli.skills_config import get_disabled_skills
cfg = load_config() or {}
disabled = {s.lower() for s in get_disabled_skills(cfg)}
skills_root = profile_dir / "skills"
installed = [
{"name": md.parent.name, "enabled": md.parent.name.lower() not in disabled}
for md in (sorted(skills_root.rglob("SKILL.md")) if skills_root.is_dir() else ())
]
toolsets_out, pinned_set = _describe_toolsets(cfg)
soul = _read_text_if_file(profile_dir / "SOUL.md")
mcp_out = _describe_mcp_servers(cfg)
model_cfg = cfg.get("model") if isinstance(cfg.get("model"), dict) else {}
meta = _try(lambda: _lazy("hermes_cli.profiles", "read_profile_meta")(profile_dir), {})
result = {
"name": name,
"description": str(meta.get("description") or ""),
"soul": soul,
"model": {"provider": str(model_cfg.get("provider") or ""), "default": str(model_cfg.get("default") or "")},
"skills": installed,
"toolsets": toolsets_out,
"toolsets_pinned": pinned_set is not None,
"mcp_servers": mcp_out,
}
return _ok(rid, result)
def _configure_ui_meta(profile_dir, params, applied) -> None:
"""Merge ``params["ui_meta"]`` key-wise into profile.yaml (None deletes a key).
Size-capped (64KB) because it rides profiles.list on every roster paint.
``ui_meta_expected_revisions`` are per-key CAS preconditions; any mismatch rejects
the whole write. Revisions survive deletion so a stale client cannot recreate a
removed key by presenting the initial revision.
"""
"""Merge ``params["ui_meta"]`` key-wise into profile.yaml (None deletes). 64KB cap (rides
every roster paint). ``ui_meta_expected_revisions``: per-key CAS, any mismatch rejects the
whole write; revisions survive deletion so a stale client cannot recreate a removed key."""
try:
incoming = params["ui_meta"]
if len(json.dumps(incoming)) > 65536:
@@ -598,13 +546,9 @@ def _configure_ui_meta(profile_dir, params, applied) -> None:
def _configure_model(profile_dir, params, applied):
"""Apply a ``model`` + ``provider`` pin; returns a confirm message instead of writing.
Same handshake as ``config.set model``: without ``confirm_expensive_model`` a
guarded (data-policy / expensive) pick answers ``confirm_required`` and writes
NOTHING; the client resends with the flag once confirmed. A misbehaving guard
must never break the save (treated as "no warning"), matching ``_apply_model_switch``.
"""
"""Apply a ``model`` + ``provider`` pin, or return a confirm message and write NOTHING (the
``config.set model`` handshake: client resends with ``confirm_expensive_model``). A failing
guard counts as "no warning", matching ``_apply_model_switch``."""
model = str(params.get("model") or "").strip()
provider = str(params.get("provider") or "").strip()
confirm_message = None
@@ -625,18 +569,12 @@ def _configure_model(profile_dir, params, applied):
def _configure_cfg_sections(profile_dir, params, applied) -> None:
"""Apply ``disabled_skills`` / ``enabled_toolsets`` / ``enabled_mcp_servers`` (replace semantics).
An empty ``enabled_toolsets`` clears the pin. ``enabled_mcp_servers`` toggles the
``disabled`` flag; enabling a server the profile doesn't define copies its
definition from the LAUNCH profile's catalog — unknown names are skipped, never
invented. Server defs are config, not secrets; credentials stay in .env/auth.
"""
"""Apply ``disabled_skills`` / ``enabled_toolsets`` / ``enabled_mcp_servers`` (replace
semantics; empty toolsets clears the pin). Enabling an undefined MCP server copies its
definition from the LAUNCH catalog (unknown names skipped); credentials stay in .env/auth."""
want_mcp = isinstance(params.get("enabled_mcp_servers"), list)
# Launch profile's MCP catalog, read BEFORE the home override flips config
# resolution to the target profile.
# Launch catalog read BEFORE the home override flips config resolution.
launch_mcp = _try(_launch_mcp_catalog, {}) if want_mcp else {}
with _hermes_home_scope(profile_dir):
from hermes_cli.config import load_config, save_config
cfg = load_config() or {}
@@ -688,42 +626,34 @@ def _save_mcp_toggles(cfg, enabled, launch_mcp, save_config) -> None:
save_config(cfg)
@method("profiles.configure")
@_profile_handler("profiles.configure", 5064)
def _(rid, params: dict) -> dict:
"""Apply configuration changes to a profile (editor Save).
Params: ``name`` plus any of ``ui_meta`` (+ ``ui_meta_expected_revisions``), ``soul``,
``description``, ``model`` + ``provider`` (+ ``confirm_expensive_model``),
``disabled_skills``, ``enabled_toolsets``, ``enabled_mcp_servers``. Sections are
independent and best-effort; ``applied`` reports per-section success.
"""
try:
_name, profile_dir, err = _resolve_profile(rid, params)
if err is not None:
return err
applied = {}
if isinstance(params.get("ui_meta"), dict):
_configure_ui_meta(profile_dir, params, applied)
if isinstance(params.get("soul"), str):
applied["soul"] = _best_effort(lambda: (profile_dir / "SOUL.md").write_text(params["soul"], encoding="utf-8"))
if isinstance(params.get("description"), str):
applied["description"] = _best_effort(
lambda: _lazy("hermes_cli.profiles", "write_profile_meta")(
profile_dir, description=params["description"].strip(), description_auto=False
)
"""Editor Save: ``name`` plus any of ``ui_meta`` (+ ``ui_meta_expected_revisions``), ``soul``,
``description``, ``model`` + ``provider`` (+ ``confirm_expensive_model``), ``disabled_skills``,
``enabled_toolsets``, ``enabled_mcp_servers``. Sections are independent; ``applied`` reports each."""
_name, profile_dir, err = _resolve_profile(rid, params)
if err is not None:
return err
applied = {}
if isinstance(params.get("ui_meta"), dict):
_configure_ui_meta(profile_dir, params, applied)
if isinstance(params.get("soul"), str):
applied["soul"] = _best_effort(lambda: (profile_dir / "SOUL.md").write_text(params["soul"], encoding="utf-8"))
if isinstance(params.get("description"), str):
applied["description"] = _best_effort(
lambda: _lazy("hermes_cli.profiles", "write_profile_meta")(
profile_dir, description=params["description"].strip(), description_auto=False
)
confirm_message = _configure_model(profile_dir, params, applied)
if any(isinstance(params.get(k), list) for k in ("disabled_skills", "enabled_toolsets", "enabled_mcp_servers")):
_configure_cfg_sections(profile_dir, params, applied)
result = {"ok": all(applied.values()) if applied else True, "applied": applied}
if confirm_message is not None:
# Same shape config.set returns, so clients reuse one confirm handler.
result["confirm_required"] = True
result["confirm_message"] = confirm_message
return _ok(rid, result)
except Exception as e:
return _err(rid, 5064, str(e))
)
confirm_message = _configure_model(profile_dir, params, applied)
if any(isinstance(params.get(k), list) for k in ("disabled_skills", "enabled_toolsets", "enabled_mcp_servers")):
_configure_cfg_sections(profile_dir, params, applied)
result = {"ok": all(applied.values()) if applied else True, "applied": applied}
if confirm_message is not None:
# Same shape config.set returns, so clients reuse one confirm handler.
result["confirm_required"] = True
result["confirm_message"] = confirm_message
return _ok(rid, result)
def _sniff_asset_ext(blob):
@@ -743,73 +673,61 @@ def _unlink_asset_files(assets_dir, asset) -> int:
return len(present)
@method("profiles.set_asset")
@_profile_handler("profiles.set_asset", 5065)
def _(rid, params: dict) -> dict:
"""Store a small binary asset (avatar image) as ``assets/<asset>.<ext>``, atomically.
Params: ``name``, ``asset`` (only ``"avatar"``), ``data`` (data URL or raw base64;
PNG/JPEG/WebP; decoded ≤2MB), or ``clear: true``. Result: ``{ok, asset, size}``.
"""
"""Store ``assets/<asset>.<ext>`` atomically. Params: ``name``, ``asset`` (``"avatar"`` only),
``data`` (data URL or base64; PNG/JPEG/WebP ≤2MB) or ``clear: true``. Result ``{ok, asset, size}``."""
asset = str(params.get("asset") or "avatar").strip().lower()
if not str(params.get("name") or "").strip():
return _err(rid, 4063, "name required")
if asset != "avatar":
return _err(rid, 4066, f"unknown asset '{asset}' (supported: avatar)")
import base64
import re
_name, profile_dir, err = _resolve_profile(rid, params)
if err is not None:
return err
assets_dir = profile_dir / "assets"
if is_truthy_value(params.get("clear", False)):
removed = _unlink_asset_files(assets_dir, asset)
return _ok(rid, {"ok": True, "asset": asset, "size": 0, "removed": removed})
data = str(params.get("data") or "")
if not data:
return _err(rid, 4067, "data required (data URL or base64)")
match = re.match(r"^data:(image/(?:png|jpeg|webp));base64,(.*)$", data, re.DOTALL)
try:
import base64
import re
_name, profile_dir, err = _resolve_profile(rid, params)
if err is not None:
return err
assets_dir = profile_dir / "assets"
if is_truthy_value(params.get("clear", False)):
removed = _unlink_asset_files(assets_dir, asset)
return _ok(rid, {"ok": True, "asset": asset, "size": 0, "removed": removed})
data = str(params.get("data") or "")
if not data:
return _err(rid, 4067, "data required (data URL or base64)")
match = re.match(r"^data:(image/(?:png|jpeg|webp));base64,(.*)$", data, re.DOTALL)
try:
blob = base64.b64decode(match.group(2) if match else data, validate=True)
except Exception:
return _err(rid, 4068, "data is not valid base64")
if len(blob) > 2_000_000:
return _err(rid, 4069, f"asset too large ({len(blob)} bytes; max 2MB)")
ext = _sniff_asset_ext(blob)
if ext is None:
return _err(rid, 4070, "unsupported image format (PNG/JPEG/WebP only)")
assets_dir.mkdir(parents=True, exist_ok=True)
_unlink_asset_files(assets_dir, asset) # one canonical file per asset
target = assets_dir / f"{asset}.{ext}"
tmp = target.with_suffix(target.suffix + ".tmp")
tmp.write_bytes(blob)
tmp.replace(target)
return _ok(rid, {"ok": True, "asset": asset, "size": len(blob)})
except Exception as e:
return _err(rid, 5065, str(e))
blob = base64.b64decode(match.group(2) if match else data, validate=True)
except Exception:
return _err(rid, 4068, "data is not valid base64")
if len(blob) > 2_000_000:
return _err(rid, 4069, f"asset too large ({len(blob)} bytes; max 2MB)")
ext = _sniff_asset_ext(blob)
if ext is None:
return _err(rid, 4070, "unsupported image format (PNG/JPEG/WebP only)")
assets_dir.mkdir(parents=True, exist_ok=True)
_unlink_asset_files(assets_dir, asset) # one canonical file per asset
target = assets_dir / f"{asset}.{ext}"
tmp = target.with_suffix(target.suffix + ".tmp")
tmp.write_bytes(blob)
tmp.replace(target)
return _ok(rid, {"ok": True, "asset": asset, "size": len(blob)})
@method("profiles.get_asset")
@_profile_handler("profiles.get_asset", 5066)
def _(rid, params: dict) -> dict:
"""Fetch a profile asset as a data URL: ``{found, data?, mime?, size?}``.
``found: false`` (not an error) when absent, so rosters can probe cheaply.
"""
"""Profile asset as a data URL: ``{found, data?, mime?, size?}``; absent is ``found: false``, not an error."""
asset = str(params.get("asset") or "avatar").strip().lower()
try:
import base64
_name, profile_dir, err = _resolve_profile(rid, params)
if err is not None:
return err
for ext, mime in _ASSET_EXTS.items():
target = profile_dir / "assets" / f"{asset}.{ext}"
if target.is_file():
blob = target.read_bytes()
data = f"data:{mime};base64,{base64.b64encode(blob).decode('ascii')}"
return _ok(rid, {"found": True, "mime": mime, "size": len(blob), "data": data})
return _ok(rid, {"found": False})
except Exception as e:
return _err(rid, 5066, str(e))
import base64
_name, profile_dir, err = _resolve_profile(rid, params)
if err is not None:
return err
for ext, mime in _ASSET_EXTS.items():
target = profile_dir / "assets" / f"{asset}.{ext}"
if target.is_file():
blob = target.read_bytes()
data = f"data:{mime};base64,{base64.b64encode(blob).decode('ascii')}"
return _ok(rid, {"found": True, "mime": mime, "size": len(blob), "data": data})
return _ok(rid, {"found": False})
def register(server) -> None:
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
+298 -314
View File
@@ -1,4 +1,4 @@
"""slash.exec helpers: command resolution, side-effect mirroring after a slash command ran in the worker.
"""slash.exec helpers: live-session command output and side-effect mirroring after a slash command ran in the worker.
Bodies are rebound onto server.py's globals at install time (see
method_ctx.bind_module), so they reference server.py globals bare.
@@ -7,61 +7,44 @@ method_ctx.bind_module), so they reference server.py globals bare.
from __future__ import annotations
import contextlib
from .method_ctx import HandlerRegistry, bind_module
_registry = HandlerRegistry()
# ── Methods: slash.exec ──────────────────────────────────────────────
# ── Live-session slash output ────────────────────────────────────────
_LIVE_SESSION_DIRECT_COMMANDS = frozenset(
{
"clear",
"compress",
"effort",
"history",
"models",
"prompt",
"rename",
"review",
"status",
"usage",
}
{"clear", "compress", "effort", "history", "models", "prompt", "rename", "review", "status", "usage"}
)
# Answered from the live session ONLY when the agent lives on a compute host.
_ISOLATED_SESSION_READ_COMMANDS = frozenset({"context", "tools", "help"})
_NO_AGENT_USAGE = "(._.) No active agent -- send a message first."
_NO_AGENT = "No active agent -- send a message first."
def _format_live_review_output(session: Optional[dict], arg: str) -> str:
"""Dispatch /review against the live TUI/desktop session's agent.
"""Dispatch /review against the live session's agent.
Spawns the reviewer subagent on the async delegation rail; the TUI
notification poller already drains async-delegation completions for the
owning session, so the finished review re-enters this chat as a normal
completion turn. The dispatch stamps the parent agent's durable
session_id as the completion's session_key (the delegate_task CLI-path
fallback), which is exactly what ``_session_owns_notification_event``
matches against.
The reviewer subagent runs on the async delegation rail; the TUI notification
poller drains its completion back into this chat. The dispatch stamps the
parent's durable session_id as the completion's session_key, which is what
``_session_owns_notification_event`` matches against.
"""
if session is None:
return "Nothing to review yet — send a message first."
if _session_uses_compute_host(session):
return (
"/review runs on the local agent only for now — this session's "
"agent lives on a remote compute host."
)
return "/review runs on the local agent only for now — this session's agent lives on a remote compute host."
agent = session.get("agent")
if agent is None:
return "Nothing to review yet — send a message first."
if session.get("running"):
return "session busy — wait for the current turn to finish, then /review"
history_lock = session.get("history_lock")
if history_lock is not None:
with history_lock:
snapshot = list(session.get("history", []))
else:
with session.get("history_lock") or contextlib.nullcontext():
snapshot = list(session.get("history", []))
if not snapshot:
snapshot = list(getattr(agent, "_session_messages", None) or [])
@@ -81,61 +64,60 @@ def _format_live_usage_output(session: dict) -> str:
agent = session.get("agent")
usage = _session_usage_snapshot(session)
if agent is None and not usage:
return "(._.) No active agent -- send a message first."
return _NO_AGENT_USAGE
if session.get("_metadata_message_count") is not None:
message_count = int(session.get("_metadata_message_count") or 0)
else:
with session["history_lock"]:
message_count = len(session.get("history", []))
def n(key: str) -> str:
return f"{int(usage.get(key) or 0):,}"
lines = [
"Session Token Usage",
"────────────────────────────────────────",
f"Model: {usage.get('model') or _metadata_mirror(session).get('model') or getattr(agent, 'model', '') or '(unknown)'}",
f"Input tokens: {int(usage.get('input') or 0):,}",
f"Output tokens: {int(usage.get('output') or 0):,}",
f"Input tokens: {n('input')}",
f"Output tokens: {n('output')}",
]
if int(usage.get("reasoning") or 0):
lines.append(f"Reasoning tokens: {n('reasoning')}")
lines += [
f"Prompt tokens: {n('prompt')}",
f"Completion tokens: {n('completion')}",
f"Total tokens: {n('total')}",
f"API calls: {n('calls')}",
]
reasoning = int(usage.get("reasoning") or 0)
if reasoning:
lines.append(f"Reasoning tokens: {reasoning:,}")
lines.extend(
[
f"Prompt tokens: {int(usage.get('prompt') or 0):,}",
f"Completion tokens: {int(usage.get('completion') or 0):,}",
f"Total tokens: {int(usage.get('total') or 0):,}",
f"API calls: {int(usage.get('calls') or 0):,}",
]
)
if usage.get("context_max"):
lines.append(
"Current context: "
f"{int(usage.get('context_used') or 0):,} / "
f"{int(usage.get('context_max') or 0):,} "
f"Current context: {n('context_used')} / {n('context_max')} "
f"({int(usage.get('context_percent') or 0)}%)"
)
lines.extend(
[
f"Messages: {message_count:,}",
f"Compressions: {int(usage.get('compressions') or 0):,}",
]
)
lines += [f"Messages: {message_count:,}", f"Compressions: {n('compressions')}"]
return "\n".join(lines)
def _live_session_messages(session: dict) -> Optional[list]:
"""Session-scoped transcript read; None when no db/key or the read fails. Uses
``_session_db`` (not ``_get_db()``): a profile session's rows live in its own
profile's state.db, and through the launch handle this read comes back empty."""
with _session_db(session) as db:
if db is not None and session.get("session_key"):
try:
return db.get_messages_as_conversation(
session["session_key"], include_ancestors=True, include_row_ids=True
)
except Exception:
pass
return None
def _format_live_history_output(session: dict) -> str:
with session["history_lock"]:
history = list(session.get("history", []))
# _session_db, not _get_db(): a profile session's transcript lives in its
# own profile's state.db, and this read is scoped by session id — through
# the launch handle it comes back empty and /history renders nothing.
with _session_db(session) as db:
if db is not None and session.get("session_key"):
try:
history = db.get_messages_as_conversation(
session["session_key"], include_ancestors=True, include_row_ids=True
)
except Exception:
pass
messages = _history_to_messages(history)
db_history = _live_session_messages(session)
messages = _history_to_messages(history if db_history is None else db_history)
if not messages:
return "No conversation history yet."
lines = ["Conversation History", "────────────────────────────────────────"]
@@ -153,7 +135,7 @@ def _format_live_prompt_output(session: dict) -> str:
agent = session.get("agent")
mirror = _metadata_mirror(session)
if agent is None and "system_prompt" not in mirror:
return "No active agent -- send a message first."
return _NO_AGENT
prompt = (
mirror.get("system_prompt")
or getattr(agent, "ephemeral_system_prompt", None)
@@ -166,27 +148,16 @@ def _format_live_prompt_output(session: dict) -> str:
def _format_live_context_output(session: dict) -> str:
messages = []
# Same session-scoped read as /history — resolve it against the db that
# owns this session's rows, not the launch profile's handle.
with _session_db(session) as db:
if db is not None and session.get("session_key"):
try:
messages = _history_to_messages(
db.get_messages_as_conversation(
session["session_key"], include_ancestors=True, include_row_ids=True
)
)
except Exception:
messages = []
try:
messages = _history_to_messages(_live_session_messages(session) or [])
except Exception:
messages = [] # malformed db rows fall back to the live history below
if not messages:
with session["history_lock"]:
messages = _history_to_messages(list(session.get("history", [])))
usage = _session_usage_snapshot(session)
mirror = _metadata_mirror(session)
lines = [
f"Conversation: {len(messages)} messages" if messages else "Conversation is empty (no messages yet)."
]
lines = [f"Conversation: {len(messages)} messages" if messages else "Conversation is empty (no messages yet)."]
roles: dict[str, int] = {}
for msg in messages:
role = str(msg.get("role") or "unknown")
@@ -196,20 +167,17 @@ def _format_live_context_output(session: dict) -> str:
f"tool: {roles.get('tool', 0)}, system: {roles.get('system', 0)}"
)
model = mirror.get("model") or usage.get("model") or ""
provider = mirror.get("provider") or "auto"
if model:
lines.append(f"Model: {model}")
lines.append(f"Provider: {provider}")
lines.append(f"Provider: {mirror.get('provider') or 'auto'}")
context_used = int(usage.get("context_used") or usage.get("total") or 0)
context_max = int(usage.get("context_max") or 0)
if context_used:
if context_max:
usage_pct = (context_used / context_max) * 100
lines.append(
f"Context usage: ~{context_used:,} / {context_max:,} tokens ({usage_pct:.1f}%)"
)
else:
lines.append(f"Context usage: ~{context_used:,} tokens")
if context_used and context_max:
lines.append(
f"Context usage: ~{context_used:,} / {context_max:,} tokens ({(context_used / context_max) * 100:.1f}%)"
)
elif context_used:
lines.append(f"Context usage: ~{context_used:,} tokens")
if usage.get("compressions"):
lines.append(f"Compressions: {int(usage.get('compressions') or 0):,}")
return "\n".join(lines)
@@ -220,16 +188,10 @@ def _format_live_tools_output(session: dict) -> str:
groups = info.get("tools") if isinstance(info, dict) else {}
if not isinstance(groups, dict) or not groups:
return "No tools available."
names: list[str] = []
for group_names in groups.values():
if isinstance(group_names, list):
names.extend(str(name) for name in group_names)
names = sorted(set(names))
names = sorted({str(n) for g in groups.values() if isinstance(g, list) for n in g})
if not names:
return "No tools available."
return "Available tools ({}):\n{}".format(
len(names), "\n".join(f" {name}" for name in names)
)
return "Available tools ({}):\n{}".format(len(names), "\n".join(f" {name}" for name in names))
def _format_live_help_output() -> str:
@@ -239,8 +201,7 @@ def _format_live_help_output() -> str:
lines = ["Available commands:", ""]
for category, commands in COMMANDS_BY_CATEGORY.items():
lines.append(f"{category}:")
for cmd, desc in commands.items():
lines.append(f" {cmd:<15} {desc}")
lines.extend(f" {cmd:<15} {desc}" for cmd, desc in commands.items())
return "\n".join(lines)
except Exception as exc:
return f"help unavailable: {exc}"
@@ -252,244 +213,267 @@ def _format_live_model_output(session: dict) -> str:
provider = getattr(agent, "provider", "") if agent is not None else ""
if model and provider:
return f"Current model: {model} ({provider})"
if model:
return f"Current model: {model}"
return "Current model: (unknown)"
return f"Current model: {model}" if model else "Current model: (unknown)"
def _format_live_status_output(sid: str) -> str:
response = _methods["session.status"]("status", {"session_id": sid})
if response.get("error"):
return str(response["error"].get("message") or "status unavailable")
return str(response.get("result", {}).get("output") or "")
# name → (reply when there is no session, formatter(sid, session, arg)). A None
# no-session reply means the formatter handles a missing session itself.
_LIVE_SLASH_OUTPUT = {
"compress": ("no active session for /compress", lambda sid, s, a: _mirror_slash_side_effects(sid, s, f"/compress {a}".strip())),
"usage": (_NO_AGENT_USAGE, lambda sid, s, a: _format_live_usage_output(s)),
"review": (None, lambda sid, s, a: _format_live_review_output(s, a)),
"history": ("No conversation history yet.", lambda sid, s, a: _format_live_history_output(s)),
"prompt": (_NO_AGENT, lambda sid, s, a: _format_live_prompt_output(s)),
"status": (None, lambda sid, s, a: _format_live_status_output(sid)),
"context": ("Conversation is empty (no messages yet).", lambda sid, s, a: _format_live_context_output(s)),
"tools": ("No tools available.", lambda sid, s, a: _format_live_tools_output(s)),
"help": (None, lambda sid, s, a: _format_live_help_output()),
"clear": (None, lambda sid, s, a: "Screen clear is terminal-only; desktop/TUI chat left unchanged."),
"models": (None, lambda sid, s, a: "Use /model to view or switch the current model; desktop users can also open the model picker."),
"rename": (None, lambda sid, s, a: "Use /title <name> to rename this session."),
"effort": (None, lambda sid, s, a: "Use /reasoning <effort> to change reasoning effort."),
}
def _live_slash_command_output(sid: str, session: Optional[dict], name: str, arg: str) -> Optional[str]:
"""Answer a slash command from the live session instead of the slash worker; None = not ours."""
name = (name or "").lstrip("/").lower()
arg = arg or ""
if name == "model" and not arg.strip():
return _format_live_model_output(session or {})
if name not in _LIVE_SESSION_DIRECT_COMMANDS:
if not (
name in _ISOLATED_SESSION_READ_COMMANDS
and session is not None
and _session_uses_compute_host(session)
):
if name in _ISOLATED_SESSION_READ_COMMANDS:
if not (session is not None and _session_uses_compute_host(session)):
return None
if name in _ISOLATED_SESSION_READ_COMMANDS and not (
session is not None and _session_uses_compute_host(session)
):
elif name not in _LIVE_SESSION_DIRECT_COMMANDS:
return None
if name == "compress":
if session is None:
return "no active session for /compress"
return _mirror_slash_side_effects(sid, session, f"/compress {arg}".strip())
if name == "usage":
if session is None:
return "(._.) No active agent -- send a message first."
return _format_live_usage_output(session)
if name == "review":
return _format_live_review_output(session, arg)
if name == "history":
if session is None:
return "No conversation history yet."
return _format_live_history_output(session)
if name == "prompt":
if session is None:
return "No active agent -- send a message first."
return _format_live_prompt_output(session)
if name == "status":
response = _methods["session.status"]("status", {"session_id": sid})
if response.get("error"):
return str(response["error"].get("message") or "status unavailable")
return str(response.get("result", {}).get("output") or "")
if name == "context":
if session is None:
return "Conversation is empty (no messages yet)."
return _format_live_context_output(session)
if name == "tools":
if session is None:
return "No tools available."
return _format_live_tools_output(session)
if name == "help":
return _format_live_help_output()
if name == "clear":
return "Screen clear is terminal-only; desktop/TUI chat left unchanged."
if name == "models":
return "Use /model to view or switch the current model; desktop users can also open the model picker."
if name == "rename":
return "Use /title <name> to rename this session."
if name == "effort":
return "Use /reasoning <effort> to change reasoning effort."
return None
entry = _LIVE_SLASH_OUTPUT.get(name)
if entry is None:
return None
no_session_reply, fmt = entry
if session is None and no_session_reply is not None:
return no_session_reply
return fmt(sid, session, arg)
# ── Side-effect mirroring ────────────────────────────────────────────
# Read-then-mutate live agent/session state that a running turn is using; rejected
# while running (parity with session.compress / session.undo and the gateway's
# running-agent /model guard).
_MUTATES_WHILE_RUNNING = frozenset({"model", "personality", "prompt", "compress"})
def _compress_live_with_feedback(sid: str, session: dict, agent, arg: str, *, snapshot_kwargs: bool) -> dict:
"""Compress the live session; return the ``summarize_manual_compression`` dict.
Shared by command.dispatch /compress and the slash mirror so every route shows
"compressed N → M messages / ~X → ~Y tokens". ``snapshot_kwargs`` forwards the
pre-read snapshot (approx_tokens/before_messages/history_version) to
``_compress_session_history``; the slash mirror passes only the raw arg. The raw
arg goes through unparsed — the choke point parses ``here [N]`` / ``--keep N``.
CompressionLockHeld and other errors propagate to the caller, which finalizes
the deferred context-engine notification.
"""
from agent.conversation_compression import finalize_context_engine_compression_notification
from agent.manual_compression_feedback import summarize_manual_compression
from agent.model_metadata import estimate_request_tokens_rough
with session["history_lock"]:
before_messages = list(session.get("history", []))
history_version = int(session.get("history_version", 0))
sys_prompt = getattr(agent, "_cached_system_prompt", "") or ""
tools = getattr(agent, "tools", None) or None
before_tokens = (
estimate_request_tokens_rough(before_messages, system_prompt=sys_prompt, tools=tools) if before_messages else 0
)
if snapshot_kwargs:
_compress_session_history(
session,
arg.strip() or None,
approx_tokens=before_tokens,
before_messages=before_messages,
history_version=history_version,
)
else:
_compress_session_history(session, arg)
_sync_session_key_after_compress(sid, session)
with session["history_lock"]:
after_messages = list(session.get("history", []))
after_tokens = (
estimate_request_tokens_rough(
after_messages,
system_prompt=getattr(agent, "_cached_system_prompt", "") or sys_prompt,
tools=getattr(agent, "tools", None) or tools,
)
if after_messages
else 0
)
_emit("session.info", sid, _session_info(agent, session))
fb = summarize_manual_compression(
before_messages,
after_messages,
before_tokens,
after_tokens,
compression_state=getattr(agent, "context_compressor", None),
)
finalize_context_engine_compression_notification(agent, committed=True)
return fb
def _mirror_model(sid, session, agent, arg) -> str:
if arg and agent:
return _apply_model_switch(sid, session, arg).get("warning", "")
return ""
def _mirror_approvals(sid, session, agent, arg) -> str:
# The worker already persisted approvals.mode; the bare read-only form needs no repaint.
if arg:
broadcast_session_info()
return ""
def _mirror_personality(sid, session, agent, arg) -> str:
if arg and agent:
pname, new_prompt = _validate_personality(arg, _load_cfg())
# Persist through the single owner so this surface never drifts from the others.
from hermes_cli.personality import persist_personality
persist_personality(pname)
_apply_personality_to_session(sid, session, new_prompt, pname)
return ""
def _mirror_prompt(sid, session, agent, arg) -> str:
if agent:
cfg = _load_cfg()
agent.ephemeral_system_prompt = _prompt_text((cfg.get("agent") or {}).get("system_prompt", "")) or None
agent._cached_system_prompt = None
return ""
def _mirror_compress(sid, session, agent, arg) -> str:
if not agent:
return ""
try:
fb = _compress_live_with_feedback(sid, session, agent, arg, snapshot_kwargs=False)
except CompressionLockHeld as e:
from agent.manual_compression_feedback import describe_compression_lock_skip
return describe_compression_lock_skip(e.holder)
lines = [fb["headline"], fb["token_line"]]
if fb.get("note"):
lines.append(fb["note"])
return "\n".join(lines)
def _mirror_fast(sid, session, agent, arg) -> str:
if agent:
mode = arg.lower()
if mode in {"fast", "on"}:
agent.service_tier = "priority"
elif mode in {"normal", "off"}:
agent.service_tier = None
elif mode in {"auto", "cold"}:
agent.service_tier = mode
_emit("session.info", sid, _session_info(agent, session))
return ""
def _mirror_reload_mcp(sid, session, agent, arg) -> str:
if agent and hasattr(agent, "reload_mcp_tools"):
agent.reload_mcp_tools()
return ""
def _mirror_stop(sid, session, agent, arg) -> str:
from tools.process_registry import process_registry
process_registry.kill_all()
return ""
_SLASH_MIRRORS = {
"model": _mirror_model,
"approvals": _mirror_approvals,
"personality": _mirror_personality,
"prompt": _mirror_prompt,
"compress": _mirror_compress,
"fast": _mirror_fast,
"reload-mcp": _mirror_reload_mcp,
"stop": _mirror_stop,
}
def _compute_host_slash(sid: str, session: dict, name: str, command: str) -> tuple[str, str]:
"""Forward a mutating slash command to the session's compute host.
Returns ``(status, text)``: ``pending`` (compress still running after the wait),
``failed`` (transport error/timeout), ``rejected`` (host control.error), ``ok``
(host output; metadata mirror already applied). Compress waits longer and installs
a late-ack adopter so a slow compression still lands in this session.
"""
route_name = f"slash.{name}"
is_compress = name == "compress"
_late_session = session
def _on_late_ack(late: dict, _sid=sid) -> None:
_adopt_late_compute_host_compress_ack(_sid, _late_session, late, route_name=route_name)
try:
ack = _send_compute_host_control(
sid,
route_name=route_name,
command=command,
wait=True,
**({"timeout": _compute_host_compress_wait_seconds(), "on_late_ack": _on_late_ack} if is_compress else {}),
)
except queue.Empty:
if is_compress:
return "pending", "compression still running in the background; the transcript will refresh when it finishes"
return "failed", f"compute-host {route_name} failed: timed out"
except Exception as exc:
return "failed", f"compute-host {route_name} failed: {exc}"
if ack.get("type") in {"control.error", "error"}:
return "rejected", str(ack.get("message") or f"compute-host {route_name} failed")
_apply_compute_host_metadata_mirror(session, ack)
return "ok", str(ack.get("output") or "")
def _mirror_slash_side_effects(sid: str, session: dict, command: str) -> str:
"""Apply side effects that must also hit the gateway's live agent."""
parts = command.lstrip("/").split(None, 1)
if not parts:
return ""
name, arg, agent = (
parts[0],
(parts[1].strip() if len(parts) > 1 else ""),
session.get("agent"),
)
name, arg, agent = parts[0], (parts[1].strip() if len(parts) > 1 else ""), session.get("agent")
if name == "compact":
# /compact is an alias of /compress in every host. The compute-host
# slash.compress control forwards the user's raw alias verbatim, so
# without normalizing here the child mirror silently no-ops — the
# session never compresses and the deferred context-engine
# notification wiring below is never exercised for that route.
# /compact aliases /compress everywhere; the compute-host control forwards the
# raw alias verbatim, so without this the child mirror silently no-ops.
name = "compress"
# Reject agent-mutating commands during an in-flight turn. These
# all do read-then-mutate on live agent/session state that the
# worker thread running agent.run_conversation is using. Parity
# with the session.compress / session.undo guards and the gateway
# runner's running-agent /model guard.
_MUTATES_WHILE_RUNNING = {"model", "personality", "prompt", "compress"}
if _session_uses_compute_host(session) and name in _MUTATES_WHILE_RUNNING:
route_name = f"slash.{name}"
is_compress = name == "compress"
_late_session = session
def _on_late_ack(late: dict, _sid=sid) -> None:
_adopt_late_compute_host_compress_ack(_sid, _late_session, late, route_name=route_name)
try:
ack = _send_compute_host_control(
sid,
route_name=route_name,
command=command,
wait=True,
**(
{"timeout": _compute_host_compress_wait_seconds(), "on_late_ack": _on_late_ack}
if is_compress
else {}
),
)
except queue.Empty:
if is_compress:
return "compression still running in the background; the transcript will refresh when it finishes"
return f"compute-host {route_name} failed: timed out"
except Exception as exc:
return f"compute-host {route_name} failed: {exc}"
if ack.get("type") in {"control.error", "error"}:
return str(ack.get("message") or f"compute-host {route_name} failed")
_apply_compute_host_metadata_mirror(session, ack)
return str(ack.get("output") or "")
return _compute_host_slash(sid, session, name, command)[1]
if name in _MUTATES_WHILE_RUNNING and session.get("running"):
return f"session busy — /interrupt the current turn before running /{name}"
mirror = _SLASH_MIRRORS.get(name)
if mirror is None:
return ""
try:
if name == "model" and arg and agent:
result = _apply_model_switch(sid, session, arg)
return result.get("warning", "")
elif name == "approvals" and arg:
# The slash worker already persisted the new approvals.mode; the
# bare (read-only) form has no arg and needs no repaint.
broadcast_session_info()
elif name == "personality" and arg and agent:
pname, new_prompt = _validate_personality(arg, _load_cfg())
# Persist through the single owner so this surface can never
# drift from the others (the old TUI slash path applied the
# overlay in-session but skipped persistence entirely).
from hermes_cli.personality import persist_personality
persist_personality(pname)
_apply_personality_to_session(sid, session, new_prompt, pname)
elif name == "prompt" and agent:
cfg = _load_cfg()
new_prompt = _prompt_text((cfg.get("agent") or {}).get("system_prompt", ""))
agent.ephemeral_system_prompt = new_prompt or None
agent._cached_system_prompt = None
elif name == "compress" and agent:
# Mirror the session.compress RPC: build a before/after summary so
# the user gets feedback (#46686). The slash path previously just
# compressed + emitted session.info and returned "", so the TUI
# showed no "compressed N → M messages / ~X → ~Y tokens" stats
# while CLI and gateway both did.
from agent.manual_compression_feedback import summarize_manual_compression
from agent.model_metadata import estimate_request_tokens_rough
from agent.conversation_compression import (
finalize_context_engine_compression_notification,
)
with session["history_lock"]:
_before_messages = list(session.get("history", []))
_before_count = len(_before_messages)
_sys_prompt = getattr(agent, "_cached_system_prompt", "") or ""
_tools = getattr(agent, "tools", None) or None
_before_tokens = (
estimate_request_tokens_rough(
_before_messages, system_prompt=_sys_prompt, tools=_tools
)
if _before_count
else 0
)
# The raw argument goes through unparsed: _compress_session_history
# (the choke point shared by all three manual-compress routes)
# parses the boundary-aware forms (here [N], up to here, --keep N)
# and does the partial head/tail split there (#35533).
try:
_compress_session_history(session, arg)
except CompressionLockHeld as e:
from agent.manual_compression_feedback import (
describe_compression_lock_skip,
)
return describe_compression_lock_skip(e.holder)
_sync_session_key_after_compress(sid, session)
with session["history_lock"]:
_after_messages = list(session.get("history", []))
_sys_prompt_after = getattr(agent, "_cached_system_prompt", "") or _sys_prompt
_tools_after = getattr(agent, "tools", None) or _tools
_after_tokens = (
estimate_request_tokens_rough(
_after_messages, system_prompt=_sys_prompt_after, tools=_tools_after
)
if _after_messages
else 0
)
_emit("session.info", sid, _session_info(agent, session))
_fb = summarize_manual_compression(
_before_messages,
_after_messages,
_before_tokens,
_after_tokens,
compression_state=getattr(agent, "context_compressor", None),
)
_lines = [_fb["headline"], _fb["token_line"]]
if _fb.get("note"):
_lines.append(_fb["note"])
finalize_context_engine_compression_notification(
agent,
committed=True,
)
return "\n".join(_lines)
elif name == "fast" and agent:
mode = arg.lower()
if mode in {"fast", "on"}:
agent.service_tier = "priority"
elif mode in {"normal", "off"}:
agent.service_tier = None
elif mode in {"auto", "cold"}:
agent.service_tier = mode
_emit("session.info", sid, _session_info(agent, session))
elif name == "reload-mcp" and agent and hasattr(agent, "reload_mcp_tools"):
agent.reload_mcp_tools()
elif name == "stop":
from tools.process_registry import process_registry
process_registry.kill_all()
return mirror(sid, session, agent, arg)
except Exception as e:
if name == "compress" and agent:
from agent.conversation_compression import (
finalize_context_engine_compression_notification,
)
from agent.conversation_compression import finalize_context_engine_compression_notification
finalize_context_engine_compression_notification(
agent,
committed=False,
)
finalize_context_engine_compression_notification(agent, committed=False)
return f"live session sync failed: {e}"
return ""
def register(server) -> None:
File diff suppressed because it is too large Load Diff
File diff suppressed because it is too large Load Diff
+67 -183
View File
@@ -14,35 +14,22 @@ _registry = HandlerRegistry()
def _persist_model_switch(result) -> None:
# Use targeted, atomic key writes (comment/ordering-preserving) instead of
# rewriting the whole `model:` block. A full-block rewrite via save_config()
# destroys sibling keys the user set under `model:` — `model_slots`,
# `model_fallback`, etc. — when switching models from the TUI (#48305).
# Targeted key writes: a full `model:` block rewrite via save_config() would
# destroy sibling keys the user set there (`model_slots`, `model_fallback`, ...).
from cli import save_config_value
save_config_value("model.default", result.new_model)
save_config_value("model.provider", result.target_provider)
if result.base_url:
save_config_value("model.base_url", result.base_url)
else:
# Clear any stale base_url when switching to a provider that doesn't use
# one (e.g. custom endpoint -> native provider). Reads coalesce null to
# absent (`model_cfg.get("base_url") or ""`), so a null is equivalent to
# removal without needing a key-delete. Leaving the old value would
# route the new model at the previous custom host (#48305).
save_config_value("model.base_url", None)
# A provider without a base_url must clear the stale one (custom endpoint ->
# native) or the new model routes at the old host; reads coalesce null to absent.
save_config_value("model.base_url", result.base_url or None)
def _snapshot_agent_model_runtime(agent) -> dict:
"""Capture the current agent model runtime for a one-turn restore."""
return {
"model": getattr(agent, "model", ""),
"provider": getattr(agent, "provider", ""),
"api_key": getattr(agent, "api_key", ""),
"base_url": getattr(agent, "base_url", ""),
"api_mode": getattr(agent, "api_mode", ""),
"primary_runtime": copy.deepcopy(getattr(agent, "_primary_runtime", None)),
}
snap = {k: getattr(agent, k, "") for k in ("model", "provider", "api_key", "base_url", "api_mode")}
snap["primary_runtime"] = copy.deepcopy(getattr(agent, "_primary_runtime", None))
return snap
def _restore_agent_model_runtime(agent, snapshot: dict | None) -> None:
@@ -61,12 +48,9 @@ def _restore_agent_model_runtime(agent, snapshot: dict | None) -> None:
logger.debug("TUI one-turn model restore via primary runtime failed", exc_info=True)
if hasattr(agent, "switch_model"):
agent.switch_model(
new_model=snapshot.get("model", ""),
new_provider=snapshot.get("provider", ""),
api_key=snapshot.get("api_key", ""),
base_url=snapshot.get("base_url", ""),
api_mode=snapshot.get("api_mode", ""),
capabilities=snapshot.get("capabilities"),
new_model=snapshot.get("model", ""), new_provider=snapshot.get("provider", ""),
api_key=snapshot.get("api_key", ""), base_url=snapshot.get("base_url", ""),
api_mode=snapshot.get("api_mode", ""), capabilities=snapshot.get("capabilities"),
)
@@ -79,27 +63,20 @@ def _session_profile_runtime_scope(session: dict):
return
home_token = set_hermes_home_override(profile_home)
secret_token = set_secret_scope(build_profile_secret_scope(Path(profile_home)))
# Same authoritative terminal policy the gateway binds per turn (#68559):
# a docker-configured dashboard profile must never resolve the launch
# process's pinned env. Failure → refusal scope (fail closed).
from tools.terminal_scope import (
install_profile_terminal_scope as _install_term_scope,
)
# Same terminal policy the gateway binds per turn: a docker-configured profile
# must never resolve the launch process's pinned env. Failure → refusal scope.
from tools.terminal_scope import install_profile_terminal_scope, reset_terminal_scope
terminal_token = _install_term_scope(Path(profile_home))
terminal_token = install_profile_terminal_scope(Path(profile_home))
try:
yield
finally:
from tools.terminal_scope import reset_terminal_scope
reset_terminal_scope(terminal_token)
reset_secret_scope(secret_token)
reset_hermes_home_override(home_token)
def _restart_completed_failed_agent_build(
sid: str, session: dict, failed_ready: threading.Event | None
) -> bool:
def _restart_completed_failed_agent_build(sid: str, session: dict, failed_ready: threading.Event | None) -> bool:
"""Replace one completed failed build generation and start its retry."""
if failed_ready is None:
return False
@@ -141,11 +118,8 @@ def _apply_model_switch(
persist_override: bool | None = None,
) -> dict:
from hermes_cli.model_switch import (
parse_model_switch_args,
resolve_persist_behavior,
switch_model,
MODEL_SWITCH_ERR_ONCE_WITH_GLOBAL,
MODEL_SWITCH_ERROR_TEXT,
parse_model_switch_args, resolve_persist_behavior, switch_model,
MODEL_SWITCH_ERR_ONCE_WITH_GLOBAL, MODEL_SWITCH_ERROR_TEXT,
)
from hermes_cli.runtime_provider import resolve_runtime_provider
@@ -160,20 +134,13 @@ def _apply_model_switch(
else:
model_input, explicit_provider, is_global_flag, _force_refresh, is_session = parsed_flags
one_turn = False
# Conflict validation delegates to the shared single-owner parser; the
# TUI surfaces it as a raised ValueError (its historical behavior)
# using the canonical error copy.
# Conflict validation is the shared parser's; surface it with the canonical copy.
if is_global_flag and one_turn:
raise ValueError(MODEL_SWITCH_ERROR_TEXT[MODEL_SWITCH_ERR_ONCE_WITH_GLOBAL])
persist_global = (
persist_override
if persist_override is not None
else resolve_persist_behavior(
is_global_flag,
is_session,
is_once=one_turn,
explicit_provider=explicit_provider,
)
else resolve_persist_behavior(is_global_flag, is_session, is_once=one_turn, explicit_provider=explicit_provider)
)
if not model_input:
raise ValueError("model value required")
@@ -195,22 +162,15 @@ def _apply_model_switch(
runtime = resolve_runtime_provider(requested=None)
current_provider = str(runtime.get("provider", "") or "")
current_base_url = str(runtime.get("base_url", "") or "")
# Preserve a callable api_key (Azure Foundry Entra ID bearer
# provider) unchanged — ``str(...)`` would produce
# ``"<function ...>"`` and poison downstream switch_model
# validation. Match the agent-present branch's behavior at the
# top of this block.
# Keep a callable api_key (Azure Entra bearer) unchanged: ``str()`` would
# yield "<function ...>" and poison switch_model validation.
_runtime_key = runtime.get("api_key", "")
if callable(_runtime_key) and not isinstance(_runtime_key, str):
current_api_key = _runtime_key
else:
current_api_key = str(_runtime_key or "")
is_bearer = callable(_runtime_key) and not isinstance(_runtime_key, str)
current_api_key = _runtime_key if is_bearer else str(_runtime_key or "")
# Load user-defined providers so switch_model can resolve named custom
# endpoints (e.g. "ollama-launch") and validate against saved model lists.
user_provs = None
custom_provs = None
cfg = None
# User-defined providers let switch_model resolve named custom endpoints
# (e.g. "ollama-launch") and validate against saved model lists.
user_provs = custom_provs = cfg = None
try:
from hermes_cli.config import get_compatible_custom_providers, load_config
@@ -221,15 +181,9 @@ def _apply_model_switch(
pass
result = switch_model(
raw_input=model_input,
current_provider=current_provider,
current_model=current_model,
current_base_url=current_base_url,
current_api_key=current_api_key,
is_global=persist_global,
explicit_provider=explicit_provider,
user_providers=user_provs,
custom_providers=custom_provs,
raw_input=model_input, current_provider=current_provider, current_model=current_model,
current_base_url=current_base_url, current_api_key=current_api_key, is_global=persist_global,
explicit_provider=explicit_provider, user_providers=user_provs, custom_providers=custom_provs,
)
if not result.success:
raise ValueError(result.error_message or "model switch failed")
@@ -246,11 +200,8 @@ def _apply_model_switch(
if isinstance(_mc, dict) and _mc.get("context_length") is not None:
_cfg_ctx = int(_mc["context_length"])
merge_preflight_compression_warning(
result,
agent=agent,
messages=list(session.get("history", [])),
custom_providers=custom_provs,
config_context_length=_cfg_ctx,
result, agent=agent, messages=list(session.get("history", [])),
custom_providers=custom_provs, config_context_length=_cfg_ctx,
)
except Exception as exc:
logger.debug("preflight-compression switch warning failed: %s", exc)
@@ -260,11 +211,8 @@ def _apply_model_switch(
from hermes_cli.model_selection_guards import combined_selection_warning
warning = combined_selection_warning(
result.new_model,
provider=result.target_provider,
base_url=result.base_url or current_base_url,
api_key=result.api_key or current_api_key,
model_info=result.model_info,
result.new_model, provider=result.target_provider, base_url=result.base_url or current_base_url,
api_key=result.api_key or current_api_key, model_info=result.model_info,
)
except Exception:
warning = None
@@ -272,34 +220,21 @@ def _apply_model_switch(
confirm_msg = warning.message
if result.warning_message:
confirm_msg = f"{confirm_msg}\n\n{result.warning_message}"
# Same contract as the deferred branch below: confirm_message is
# canonical, warning is the pre-confirm-era alias. Identical by
# design, not by accident.
return {
"value": result.new_model,
"warning": confirm_msg,
"confirm_required": True,
"confirm_message": confirm_msg,
}
# Same contract as _set_model's deferred branch: confirm_message is
# canonical, warning is the legacy alias — keep identical.
return {"value": result.new_model, "warning": confirm_msg, "confirm_required": True, "confirm_message": confirm_msg}
if agent:
try:
agent.switch_model(
new_model=result.new_model,
new_provider=result.target_provider,
api_key=result.api_key,
base_url=result.base_url,
api_mode=result.api_mode,
new_model=result.new_model, new_provider=result.target_provider, api_key=result.api_key,
base_url=result.base_url, api_mode=result.api_mode,
capabilities=getattr(result, "runtime_capabilities", None),
)
except Exception as exc:
# The in-place swap rolled the agent back to the old working
# model/client and re-raised. Abort the commit: do NOT restart the
# slash worker, persist runtime, append the switch marker, set a
# session model_override, or persist to config — all of which would
# otherwise leave the session pinned to a broken model and kill the
# conversation on the next turn (#50163). A failed switch is a
# no-op; surface a clean error to the client.
# The in-place swap rolled the agent back and re-raised. Abort the whole
# commit (worker restart, persist, marker, override, config write) or the
# session stays pinned to a broken model. A failed switch is a no-op.
logger.warning("In-place model switch failed for TUI agent: %s", exc)
raise ValueError(
f"Model switch to {result.new_model} failed ({exc}); "
@@ -308,35 +243,21 @@ def _apply_model_switch(
_restart_slash_worker(sid, session)
_persist_live_session_runtime(session)
_persist_live_session_system_prompt(session)
_append_model_switch_marker(
session, model=result.new_model, provider=result.target_provider
)
_emit("session.info", sid, _session_info(agent, session))
_append_model_switch_marker(session, model=result.new_model, provider=result.target_provider)
_emit_session_info(sid, session)
if one_turn:
session["one_turn_model_restore"] = restore_snapshot
else:
session.pop("one_turn_model_restore", None)
# Record the switch as a PER-SESSION override so a later rebuild of THIS
# session (e.g. /new via _reset_session_agent, or resume) re-derives the
# user's chosen model/provider instead of falling back to global config.
#
# We deliberately do NOT write process-global env vars (HERMES_MODEL /
# HERMES_INFERENCE_MODEL / HERMES_TUI_PROVIDER / HERMES_INFERENCE_PROVIDER)
# here. The desktop backend hosts every same-profile session in ONE process,
# so mutating os.environ on a /model switch leaked the new model/provider
# into every OTHER live session's next agent rebuild — switching the model
# in one session silently changed it in the others (the cross-session
# contamination bug). agent.switch_model() above already mutated the right
# agent in place; the override dict makes that choice survive a rebuild
# without touching shared process state.
# PER-SESSION override so a rebuild of THIS session (/new, resume) re-derives
# the chosen model. Deliberately NOT written to process-global env vars
# (HERMES_MODEL & co.): the desktop hosts every same-profile session in one
# process, so os.environ would leak the switch into every other session.
if pin_session_override and isinstance(session, dict) and not one_turn:
session["model_override"] = {
"model": result.new_model,
"provider": result.target_provider,
"base_url": result.base_url,
"api_key": result.api_key,
"api_mode": result.api_mode,
"model": result.new_model, "provider": result.target_provider,
"base_url": result.base_url, "api_key": result.api_key, "api_mode": result.api_mode,
}
if persist_global:
_persist_model_switch(result)
@@ -351,14 +272,10 @@ def _apply_model_switch(
def _sync_bot_capabilities(sid: str, session: dict) -> None:
"""Rebuild a Bot Chat session's agent when its capability surface changed.
Bot Chats are eternal sessions; toolsets/MCP tool definitions are baked
into the live agent at construction, so a capability edit (Settings →
Capabilities, skill install, MCP toggle) would otherwise not apply until
/new. At turn start, hash the profile's capability surface
(tools/bot_mode_probe.capability_fingerprint) and, on change, swap in a
freshly built agent for the SAME session — history is session/DB-backed,
and the prompt-restore epoch check rebuilds the system prompt to match.
One rebuild per user-initiated change; identical state is a no-op.
Bot Chats are eternal sessions with toolsets/MCP baked in at construction, so a
capability edit would otherwise wait for /new. At turn start, fingerprint the
profile's capabilities and on change swap in a fresh agent for the SAME session
(history is DB-backed). One rebuild per change; identical state is a no-op.
"""
agent = session.get("agent")
if agent is None:
@@ -373,8 +290,7 @@ def _sync_bot_capabilities(sid: str, session: dict) -> None:
return
from tools.bot_mode_probe import capability_fingerprint
home = session.get("profile_home") or None
current = capability_fingerprint(home)
current = capability_fingerprint(session.get("profile_home") or None)
if current == "unavailable":
return
seen = session.get("bot_caps_seen")
@@ -384,28 +300,18 @@ def _sync_bot_capabilities(sid: str, session: dict) -> None:
except Exception:
return
# Capability surface changed — rebuild the agent in place. Same
# session_id/key, so the DB-backed history and (epoch-refreshed) system
# prompt carry over; only tool definitions and prompt bytes change.
try:
tokens = _set_session_context(sid, cwd=_session_cwd(session))
try:
new_agent = _make_agent(
sid,
session["session_key"],
session_id=session["session_key"],
platform_override=_session_source(session),
sid, session["session_key"], session_id=session["session_key"], platform_override=_session_source(session)
)
finally:
_clear_session_context(tokens)
new_agent._session_title_hint = "Bot Chat"
session["agent"] = new_agent
session["config_model_seen"] = _config_model_target()
_emit(
"notice",
sid,
{"message": "Capabilities updated — this bot's tools and prompt were refreshed."},
)
_emit("notice", sid, {"message": "Capabilities updated — this bot's tools and prompt were refreshed."})
except Exception as e:
logger.warning("Bot capability sync failed for %s: %s", sid, e)
@@ -427,49 +333,27 @@ def _sync_agent_model_with_config(sid: str, session: dict) -> None:
if target == seen:
return
model, provider = target
# Already running the configured model (branched/resumed session before
# its first sync, or a config revert after a failed switch): adopt the
# baseline without a redundant switch.
if model == getattr(agent, "model", "") and (
not provider or provider == getattr(agent, "provider", "")
):
# Already on the configured model (resumed before first sync, or a config
# revert after a failed switch): adopt without switching.
if model == getattr(agent, "model", "") and (not provider or provider == getattr(agent, "provider", "")):
return
raw = f"{model} --provider {provider}" if provider else model
try:
# This sync ADOPTS a config.yaml change; it must never write config back
# (that is how `hermes --tui -m` once leaked into config.yaml).
_apply_model_switch(
sid,
session,
raw,
confirm_expensive_model=True,
pin_session_override=False,
# This sync ADOPTS a config.yaml change into the live session; it
# must never write config back. Without this, the flag/config
# default (persist_switch_by_default=True) re-persisted whatever
# target the sync computed — the path that leaked `hermes --tui -m`
# into config.yaml as the permanent global model.
persist_override=False,
sid, session, raw, confirm_expensive_model=True, pin_session_override=False, persist_override=False
)
except Exception as e:
_emit(
"error",
sid,
{"message": f"Could not switch to configured model {model}: {e}"},
)
_emit("error", sid, {"message": f"Could not switch to configured model {model}: {e}"})
def _pending_switch_selection_warning(model: str, provider: str) -> str | None:
"""Selection-guard message for a model queued mid-turn, or ``None``.
Runs BEFORE the pick is stashed, while the client still has a live response
it can turn into a confirm prompt. Only pre-resolution inputs exist here --
the model id the user picked and any explicit ``--provider`` -- which is
exactly what the data-policy guard keys on. Guards that can only decide
once base_url / api_key / model_info have settled still get their chance in
``_apply_model_switch``; the cost guard returns ``None`` when pricing is
unknown, so an early call can only under-fire, never over-fire.
A misbehaving guard must never break the pick, so exceptions are swallowed
and treated as "no warning" -- the apply-time check remains the backstop.
Runs BEFORE the pick is stashed, while the client can still turn the response
into a confirm prompt. Only pre-resolution inputs exist here, so this can only
under-fire; ``_apply_model_switch`` is the backstop. Exceptions mean "no warning".
"""
if not model:
return None
+54 -76
View File
@@ -6,6 +6,7 @@ method_ctx.bind_module), so they reference server.py globals bare.
from __future__ import annotations
import re as _re
from .method_ctx import HandlerRegistry, bind_module
@@ -25,21 +26,20 @@ _IMAGE_MAGIC: tuple[tuple[bytes, str], ...] = (
(b"BM", ".bmp"),
)
# Context-ref values containing any of these must be quoted (desktop formatRefValue parity).
_ATTACHMENT_REF_NEEDS_QUOTING_RE = _re.compile(r"""[\s()\[\]{}<>"'`]""")
del _re # bodies are rebound onto server globals: import inside functions only
def _decode_attach_base64(raw: str, *, mime_prefix: str) -> bytes | None:
"""Decode a base64 (optionally data-URL-wrapped) payload.
Accepts ``data:<mime_prefix>...;base64,<b64>`` plus embedded whitespace.
Returns the decoded bytes, or ``None`` when the input isn't valid base64.
"""
"""Decode a base64 payload, optionally ``data:<mime_prefix>...;base64,``-wrapped,
tolerating embedded whitespace. ``None`` when not valid base64."""
import base64 as _base64
import re as _re
cleaned = raw.strip()
m = _re.match(
rf"^data:{_re.escape(mime_prefix)}[a-zA-Z0-9.+-]*;base64,(.*)$",
cleaned,
_re.DOTALL,
rf"^data:{_re.escape(mime_prefix)}[a-zA-Z0-9.+-]*;base64,(.*)$", cleaned, _re.DOTALL,
)
if m:
cleaned = m.group(1)
@@ -50,12 +50,24 @@ def _decode_attach_base64(raw: str, *, mime_prefix: str) -> bytes | None:
return None
def _sniff_image_ext(img_bytes: bytes, filename: str = "") -> str:
"""Resolve an image extension from a filename hint, else magic bytes.
def _decode_attach_payload(rid, raw_b64: str, *, mime_prefix: str, max_bytes: int,
label: str, empty_msg: str):
"""``(bytes, None)`` or ``(None, error)`` for an upload: 4017 on bad/empty
base64, 4018 over *max_bytes*."""
data = _decode_attach_base64(raw_b64, mime_prefix=mime_prefix)
if data is None:
return None, _err(rid, 4017, "data is not valid base64")
if not data:
return None, _err(rid, 4017, empty_msg)
if len(data) > max_bytes:
mb = max_bytes // (1024 * 1024)
return None, _err(rid, 4018, f"{label} too large ({len(data)} bytes; cap is {mb} MB)")
return data, None
Falls back to ``.png``. WebP needs the RIFF/WEBP container check, handled
before the generic table.
"""
def _sniff_image_ext(img_bytes: bytes, filename: str = "") -> str:
"""Extension from the filename hint, else magic bytes (WebP needs the RIFF/WEBP
container check), else ``.png``."""
if filename:
suffix = Path(filename).suffix.lower()
if suffix:
@@ -78,33 +90,28 @@ def _allowed_image_extensions() -> frozenset[str]:
return frozenset({".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"})
def _session_images_dir(session: dict) -> Path:
"""Resolve the uploads ``images/`` dir against the session's effective home.
def _session_home_dir(session: dict, name: str) -> Path:
"""``<session home>/<name>``, anchored on the session's stored ``profile_home``.
Attach RPCs (``image.attach_bytes``, ``clipboard.paste``, ``pdf.attach``)
run BEFORE ``prompt.submit`` installs the session's profile HERMES_HOME
override, so ``get_hermes_home()`` here would return the gateway's launch
home. In a multi-profile / root-gateway deployment that writes the upload to
the launch home's ``images/`` while the sandbox mount and the vision host-
read allowlist both resolve the *session profile's* ``images/`` at run time
— so the file the agent tries to read is never the file we wrote (#69575).
Anchor the write on the session's stored ``profile_home`` when present
(matching the mount/read scope), else fall back to the launch home. Keeps
per-profile isolation: a profile's uploads stay under that profile's home.
Attach RPCs run BEFORE ``prompt.submit`` installs the profile HERMES_HOME
override, so ``get_hermes_home()`` would return the gateway's launch home —
while the sandbox mounts and the vision host-read allowlist resolve the
*session profile's* dirs at run time. Writing anywhere else means the agent
can never see the file.
"""
profile_home = session.get("profile_home")
base = Path(profile_home) if profile_home else _hermes_home
return base / "images"
return base / name
def _session_images_dir(session: dict) -> Path:
"""Uploads ``images/`` dir for the session (see ``_session_home_dir``)."""
return _session_home_dir(session, "images")
def _queue_attached_image(session: dict, img_bytes: bytes, ext: str, *, prefix: str) -> Path:
"""Write image bytes into the gateway's images dir and queue them.
Mirrors what ``image.attach`` does for a local path: appends to
``session["attached_images"]`` so the next ``prompt.submit`` picks it up via
the existing native-image-attach pipeline. Returns the written path.
"""
"""Write image bytes into the session images dir and append to
``session["attached_images"]`` so the next ``prompt.submit`` picks them up."""
session["image_counter"] = session.get("image_counter", 0) + 1
img_dir = _session_images_dir(session)
img_dir.mkdir(parents=True, exist_ok=True)
@@ -119,20 +126,9 @@ def _queue_attached_image(session: dict, img_bytes: bytes, ext: str, *, prefix:
return img_path
_ATTACHMENT_REF_NEEDS_QUOTING_RE = None
def _format_ref_value(value: str) -> str:
"""Quote a context-ref value when it contains whitespace or bracket chars.
Mirrors the desktop ``formatRefValue`` so the staged ``@file:`` ref round-trips
through ``agent.context_references`` cleanly.
"""
import re as _re
global _ATTACHMENT_REF_NEEDS_QUOTING_RE
if _ATTACHMENT_REF_NEEDS_QUOTING_RE is None:
_ATTACHMENT_REF_NEEDS_QUOTING_RE = _re.compile(r"""[\s()\[\]{}<>"'`]""")
"""Quote a context-ref value containing whitespace/brackets/quotes so the staged
``@file:`` ref round-trips through ``agent.context_references``."""
if not value or not _ATTACHMENT_REF_NEEDS_QUOTING_RE.search(value):
return value
if "`" not in value:
@@ -155,19 +151,10 @@ def _attachment_ref_path(session: dict, target: Path) -> str:
def _desktop_attachment_dir(session: dict) -> Path:
"""Resolve the file-attachment staging dir against the session's effective home.
Anchored on the session profile's ``attachments/`` dir (same rule as
``_session_images_dir``): ``file.attach`` runs BEFORE ``prompt.submit``
installs the session's profile HERMES_HOME override, while the docker/ssh
sandbox mounts are resolved against the *session profile's* home at run
time — so the staged file must land where the bind mount points, or the
container can never see it (#76577). ``attachments/`` is registered in
``tools.credential_files._CACHE_DIRS`` and auto-mounted into containers.
"""
profile_home = session.get("profile_home")
base = Path(profile_home) if profile_home else _hermes_home
root = base / "attachments"
"""File-attachment staging dir (``attachments/``, see ``_session_home_dir``);
registered in ``tools.credential_files._CACHE_DIRS`` and auto-mounted into
containers, so a staged file lands where the bind mount points."""
root = _session_home_dir(session, "attachments")
root.mkdir(parents=True, exist_ok=True)
return root
@@ -213,12 +200,8 @@ def _resolve_gateway_attachment_path(raw: str) -> Path | None:
def _decode_attachment_data_url(data_url: str) -> bytes:
"""Decode a ``data:<any-mime>;base64,<b64>`` payload to bytes.
Unlike ``_decode_attach_base64`` (image-mime-specific), this accepts any
media type — text/csv, application/pdf, etc. — so non-image file uploads
round-trip. Also tolerates a bare base64 string with no data-URL prefix.
"""
"""Decode a ``data:<any-mime>;base64,<b64>`` payload (any media type, unlike the
image-specific ``_decode_attach_base64``); bare base64 also accepted."""
import base64 as _base64
import binascii as _binascii
import re as _re
@@ -241,18 +224,13 @@ def _stage_session_file_attachment(
data_url: str,
name: str,
) -> tuple[Path, bool]:
"""Make a desktop file attachment available to the remote gateway agent.
Three cases:
1. The path resolves to a file already INSIDE the session workspace — use
it as-is (no copy, ``uploaded=False``).
2. The path resolves to a gateway-visible file OUTSIDE the workspace — copy
it into the session home's ``attachments/`` dir (bind-mounted into
container backends) so the ``@file:`` ref resolves inside the sandbox.
3. The path doesn't exist on the gateway (the common remote case: it's a
path on the CLIENT's disk) — decode the uploaded ``data_url`` bytes and
write them into the session home's ``attachments/`` dir.
"""Make a desktop file attachment available to the gateway agent.
1. Path resolves INSIDE the session workspace → use as-is (``uploaded=False``).
2. Gateway-visible file OUTSIDE the workspace → copy into ``attachments/``
(bind-mounted into container backends) so ``@file:`` resolves in the sandbox.
3. Not on the gateway (remote client disk) → decode ``data_url`` bytes into
``attachments/``.
Returns ``(stored_path, uploaded)``.
"""
workspace = Path(_session_cwd(session)).resolve()
File diff suppressed because it is too large Load Diff
+880 -3224
View File
File diff suppressed because it is too large Load Diff
+131 -280
View File
@@ -12,17 +12,11 @@ from .method_ctx import HandlerRegistry, bind_module
_registry = HandlerRegistry()
# ── Auto-continue: resume a turn killed by a process/machine death ────
#
# A turn that concludes — success, handled error, interrupt — clears its
# durable marker (see tui_gateway/turn_marker.py) in _run_prompt_submit's
# finally. Only a process death leaves the marker behind, so a marker found
# at session.resume time is positive proof the turn never finished AND the
# client never saw a terminal frame. If the interruption is fresh, re-submit
# the interrupted prompt automatically (the messaging gateway has done this
# for restart-interrupted sessions since #27856); if it's stale, clear the
# marker and let the recovered partial transcript speak for itself — the
# user can ask to continue manually.
# A concluded turn (success, handled error, interrupt) clears its durable marker
# (turn_marker.py) in _run_prompt_submit's finally; only a process death leaves it
# behind, so a marker at session.resume proves the turn never finished AND the
# client never saw a terminal frame. Fresh: re-submit automatically (as the
# messaging gateway does). Stale: clear it and let the partial transcript speak.
_AUTO_CONTINUE_ENABLED_DEFAULT = True
_AUTO_CONTINUE_FRESHNESS_MINUTES_DEFAULT = 15
@@ -57,12 +51,10 @@ def _session_home(session: dict) -> Path:
def _retire_turn_marker(session: dict, *keys: str) -> None:
"""Drop the crash marker for a turn whose outcome is about to reach the client.
Called immediately before the terminal frame rather than at the end of the
turn thread: post-turn work (titles, memory sync, goal hooks) runs for a
second or more after the client has its answer, and quitting inside that
window would leave a marker that looks like a crash — re-running a finished
turn on the next launch. Extra ``keys`` cover a session_key that
compression rotated mid-turn.
Called right before the terminal frame, not at turn-thread end: post-turn work
(titles, memory sync, goal hooks) outlives the client's answer, and quitting in
that window would leave a marker that re-runs a finished turn on next launch.
Extra ``keys`` cover a session_key that compression rotated mid-turn.
"""
home = _session_home(session)
for key in dict.fromkeys((*keys, str(session.get("session_key") or ""))):
@@ -71,10 +63,8 @@ def _retire_turn_marker(session: dict, *keys: str) -> None:
def _auto_continue_note(prompt: str) -> str:
# Same opening as the messaging gateway's recovery notes so transcript
# tooling recognizes both. The original prompt is embedded because a hard
# crash persists nothing of the interrupted turn to the session DB — this
# note is the only copy the model will see.
# Same opening as the gateway's recovery notes (transcript tooling recognizes
# both). The prompt is embedded: a hard crash persists nothing else of the turn.
return (
f"{_AUTO_CONTINUE_NOTE_PREFIX} — the app or its backend process "
"stopped before the turn could finish. Some of the work may already "
@@ -84,19 +74,23 @@ def _auto_continue_note(prompt: str) -> str:
)
def _ac_release_turn(session: dict, *, unschedule: bool = False) -> None:
with session["history_lock"]:
session["running"] = False
if unschedule:
session["_auto_continue_scheduled"] = False
def _maybe_schedule_auto_continue(sid: str, session: dict, session_key: str) -> dict | None:
"""Kick off a continuation turn for a crash-interrupted session.
Called from session.resume's cold paths after the live record is
registered. Returns a small descriptor for the resume payload when a
continuation was scheduled, else None. The turn itself runs on a
background thread after the (deferred) agent build finishes, through the
same _run_prompt_submit machinery as every other synthesized turn — so
the client that just resumed streams it live.
Called from session.resume's cold paths once the live record is registered.
Returns a descriptor for the resume payload when scheduled, else None. The turn
runs on a background thread after the deferred agent build via the normal
_run_prompt_submit path, so the client that just resumed streams it live.
"""
# Hosted room turns are recovered by their durable task/lease state
# machine. Generic session auto-continue would bypass its execution
# generation and can duplicate work after a process restart.
# Hosted room turns are recovered by their durable task/lease state machine;
# generic auto-continue would bypass its execution generation and duplicate work.
if session.get("source") == "bot_room":
return None
@@ -107,8 +101,7 @@ def _maybe_schedule_auto_continue(sid: str, session: dict, session_key: str) ->
enabled, freshness_secs, max_attempts = _auto_continue_config()
age = time.time() - marker["started_at"]
if not enabled or age > freshness_secs or marker["attempts"] >= max_attempts:
# Stale, disabled, or crash-looping: stop trying. The journal/partial
# transcript still shows what happened; a manual message continues it.
# Stale, disabled, or crash-looping: stop trying; a manual message continues.
clear_turn_marker(home, session_key)
return None
if session.get("_auto_continue_scheduled"):
@@ -131,92 +124,56 @@ def _maybe_schedule_auto_continue(sid: str, session: dict, session_key: str) ->
return
with session["history_lock"]:
if session.get("running") or session.get("_turn_cancel_requested") or session.get("_finalized"):
# A real user prompt beat us to it — their turn wins, and its
# own conclusion clears the marker.
# A real user prompt beat us; its own conclusion clears the marker.
session["_auto_continue_scheduled"] = False
return
session["running"] = True
session["last_active"] = time.time()
# Ownership admission BEFORE message.start: the interrupted-turn
# marker this continuation is recovering may have been written by a
# sibling backend that is still alive and mid-turn (#94778 — two
# backends share one HERMES_HOME; B resumes S while A runs it and
# sees A's fresh marker). Running the continuation anyway would be
# the double-writer this fence exists to prevent. Leave the marker:
# once the owner finishes or dies, a later resume retries.
# Ownership admission BEFORE message.start: a sibling backend sharing this
# HERMES_HOME may have written the marker and still be mid-turn. Leave the
# marker so a later resume retries once the owner finishes or dies.
if _ensure_active_session_slot(sid, session) is not None:
logger.info(
"auto-continue for %s refused: session has another live owner",
session_key,
)
with session["history_lock"]:
session["running"] = False
session["_auto_continue_scheduled"] = False
logger.info("auto-continue for %s refused: session has another live owner", session_key)
_ac_release_turn(session, unschedule=True)
return
with session["history_lock"]:
# Hand this turn its own marker inputs (read back by
# _run_prompt_submit): count the attempt so a crash during the
# continuation trips the breaker, and re-record the ORIGINAL
# prompt so a second crash doesn't nest note inside note. Set
# here, not at schedule time, so a bail above leaves nothing
# behind for a racing user turn to inherit.
# Marker inputs read back by _run_prompt_submit: count the attempt (crash
# breaker) and re-record the ORIGINAL prompt (no nested notes). Set here,
# not at schedule time, so a bail above leaves nothing for a racing user turn.
session["_auto_continue_attempt"] = attempt
session["_auto_continue_prompt"] = marker["prompt"]
try:
_emit(
"status.update",
sid,
{"kind": "process", "text": "Resuming interrupted turn…"},
)
_emit("status.update", sid, {"kind": "process", "text": "Resuming interrupted turn…"})
_emit("message.start", sid)
_run_prompt_submit(rid, sid, session, text, display_kind="auto_continue")
except Exception as exc:
print(
f"[tui_gateway] auto-continue dispatch failed: "
f"{type(exc).__name__}: {exc}",
file=sys.stderr,
)
with session["history_lock"]:
session["running"] = False
print(f"[tui_gateway] auto-continue dispatch failed: {type(exc).__name__}: {exc}", file=sys.stderr)
_ac_release_turn(session)
threading.Thread(target=kickoff, daemon=True).start()
logger.info(
"auto-continue scheduled for session %s (attempt %d, interrupted %.0fs ago)",
session_key,
attempt,
age,
session_key, attempt, age,
)
return {"attempt": attempt, "interrupted_at": marker["started_at"]}
def _enqueue_prompt(
session: dict,
text: Any,
transport: Any,
image_paths: list[str] | None = None,
) -> None:
def _enqueue_prompt(session: dict, text: Any, transport: Any, image_paths: list[str] | None = None) -> None:
"""Stash a message to run as the very next turn once the live one ends.
Used when a prompt arrives mid-turn (see ``_handle_busy_submit``). Text-only
arrivals share a slot and merge losslessly (mirroring the consecutive-user
merge in ``repair_message_sequence``). Image-bearing submissions stay as
separate envelopes, so their attachment ownership and chronology survive.
``transport`` is pinned so the drained turn streams back to the client that
sent it even if the session transport is rebound meanwhile.
Text-only arrivals share a slot and merge losslessly (like the consecutive-user
merge in ``repair_message_sequence``); image-bearing ones stay separate envelopes
so attachment ownership/chronology survive. ``transport`` is pinned so the drained
turn streams back to its sender even if the session transport is rebound.
"""
image_paths = list(image_paths or [])
# #84417: scrub any live-turn self-duplicates first so the consecutive-text
# merge below cannot glue "{original}\\n\\n{later}" and re-fire original
# on drain after a later correction settles.
# Scrub live-turn self-duplicates first so the text merge below can't glue
# "{original}\n\n{later}" and re-fire the original after a correction settles.
_drop_queued_duplicates_of_inflight_user(session)
# Never queue a text-only self-copy of the live inflight user prompt. The
# live turn already owns that text; draining it after settle would restart
# the same user turn as a fresh agent invocation.
# Never queue a text-only self-copy of the live prompt: draining it would restart it.
if not image_paths and isinstance(text, str):
turn = session.get("inflight_turn")
original = (
str(turn.get("user") or "").strip() if isinstance(turn, dict) else ""
)
original = (str(turn.get("user") or "").strip() if isinstance(turn, dict) else "")
if original and text.strip() == original:
return
queued = {"text": text, "transport": transport}
@@ -240,17 +197,12 @@ def _enqueue_prompt(
session["queued_prompt"] = queued
def _sanitize_queued_entry_vs_inflight_user(
entry: Any, original: str
) -> dict | None:
"""Drop or rewrite a queue envelope that re-carries the live user text.
def _sanitize_queued_entry_vs_inflight_user(entry: Any, original: str) -> dict | None:
"""Drop (``None``) or rewrite a queue envelope that re-carries the live user text.
Returns ``None`` to drop the envelope, or a (possibly rewritten) dict to
keep. Text-only self-duplicates of ``original`` are dropped. A merged
slot ``"{original}\\n\\n{later}"`` (from ``_enqueue_prompt``'s consecutive
text merge) is rewritten to just ``later`` so a later correction is not
lost and the original is not re-fired (#84417). Image-bearing envelopes
are left alone — their chronology/ownership is load-bearing.
Text-only self-duplicates are dropped; a merged slot ``"{original}\\n\\n{later}"``
is rewritten to ``later`` so the correction survives without re-firing the
original. Image-bearing envelopes are left alone (chronology is load-bearing).
"""
if not original or not isinstance(entry, dict):
return entry if isinstance(entry, dict) else None
@@ -260,9 +212,7 @@ def _sanitize_queued_entry_vs_inflight_user(
if not isinstance(text, str):
return entry
stripped = text.strip()
if not stripped:
return None
if stripped == original:
if not stripped or stripped == original:
return None
# Lossless text-merge glued the live original onto a later follow-up.
for sep in ("\n\n", "\n"):
@@ -271,24 +221,16 @@ def _sanitize_queued_entry_vs_inflight_user(
rest = text[len(prefix) :].strip()
if not rest or rest == original:
return None
cleaned = dict(entry)
cleaned["text"] = rest
return cleaned
return {**entry, "text": rest}
return entry
def _drop_queued_duplicates_of_inflight_user(session: dict) -> None:
"""Remove server-queue copies of the live turn's original user text.
A mid-turn ``prompt.submit`` of the same text can land in
``queued_prompt`` when redirect is not yet available (model not active,
build window, tool boundary). If the user then corrects the turn with a
different prompt via redirect, that stale self-duplicate must not
``_drain_queued_prompt`` after the redirected turn completes — otherwise
the original prompt restarts as a fresh agent turn (#84417).
Unrelated follow-ups (different text, image-bearing envelopes) stay.
Merged ``original + later`` slots are rewritten to ``later`` only.
A mid-turn ``prompt.submit`` of the same text can be queued while redirect is
unavailable (build window, tool boundary); after a later redirect it must not
drain and restart the original as a fresh turn. Unrelated follow-ups stay.
"""
turn = session.get("inflight_turn")
if not isinstance(turn, dict):
@@ -305,26 +247,24 @@ def _drop_queued_duplicates_of_inflight_user(session: dict) -> None:
if cleaned is not None:
kept.append(cleaned)
if not kept:
session["queued_prompt"] = None
session.pop("queued_prompts", None)
return
session["queued_prompt"] = kept[0]
if len(kept) > 1:
session["queued_prompts"] = kept[1:]
_ac_set_queue(session, kept)
def _ac_set_queue(session: dict, entries: list) -> None:
"""Write ``entries`` back as queued_prompt (head) + queued_prompts (rest)."""
session["queued_prompt"] = entries[0] if entries else None
if len(entries) > 1:
session["queued_prompts"] = entries[1:]
else:
session.pop("queued_prompts", None)
def _interrupt_busy_session(sid: str, session: dict, agent: Any) -> None:
"""Interrupt a busy turn without blocking the RPC reader or session lock.
"""Interrupt a busy turn on a worker thread, never under ``history_lock``.
Some providers cannot apply ``interrupt()`` until a synchronous tool or
network call returns. Running that call inline used to leave
``prompt.submit`` holding ``history_lock`` for the whole wait, which in turn
blocked ``session.resume`` and delayed the queued prompt itself. Keep at
most one interrupt worker per session so repeated steering cannot leak an
unbounded number of blocked threads.
Some providers can't apply ``interrupt()`` until a blocking tool/network call
returns; doing it inline stalled ``session.resume`` and the queued prompt.
At most one interrupt worker per session so repeated steering can't leak threads.
"""
use_agent = agent is not None and hasattr(agent, "interrupt")
use_compute_host = not use_agent and _session_uses_compute_host(session)
@@ -351,58 +291,49 @@ def _interrupt_busy_session(sid: str, session: dict, agent: Any) -> None:
threading.Thread(target=interrupt, daemon=True, name=f"busy-interrupt-{sid}").start()
def _ac_record_inflight_correction(session: dict, plain_text: str) -> None:
"""Record an accepted steer/redirect; scrub stale self-duplicates so the
live turn's original text is not re-fired from the queue after settle."""
with session["history_lock"]:
_record_inflight_correction(session, plain_text)
_drop_queued_duplicates_of_inflight_user(session)
session["last_active"] = time.time()
def _handle_busy_submit(
rid, sid: str, session: dict, text: Any, transport: Any, queued: bool = False
) -> dict | None:
"""Apply the ``display.busy_input_mode`` policy to a prompt that lands while
a turn is in flight, instead of rejecting it with ``session busy``.
"""Apply ``display.busy_input_mode`` to a prompt that lands mid-turn instead of
rejecting it with ``session busy`` (rejection made clients busy-retry and
silently drop sends when teardown outlived their deadline).
The old rejection forced clients into a deadline-bounded busy-retry that
silently dropped the send when turn teardown outlived the deadline. The
default policy now redirects a capable core agent in place; older agents
retain the proven interrupt-and-queue path drained from ``run``'s tail.
Modes: ``interrupt`` (default) → redirect the live turn, falling back to
hard interrupt + queue for older agents; ``queue`` → queue without
interrupting; ``steer`` → inject after the current atomic action.
``queued=True`` (client's queue drain, ``prompt.submit`` param) overrides
the mode entirely: the message was explicitly queued as "run after", so it
must NEVER become a live-turn correction or interrupt. Without this, a
drain that loses the settle race (client observed idle, server still
unwinding the turn) redirected the live turn with next-turn text — queue
semantics betrayed by a millisecond race the user can't see.
Modes: ``interrupt`` (default) → redirect the live turn, falling back to hard
interrupt + queue for older agents; ``queue`` → queue only; ``steer`` → inject
after the current atomic action. ``queued=True`` (client queue drain) forces
queue mode: a "run after" message must NEVER become a live-turn correction,
even when the drain loses the settle race against a still-unwinding turn.
"""
mode = "queue" if queued else _load_busy_input_mode()
agent = session.get("agent")
with session["history_lock"]:
if not session.get("running"):
# The turn ended between prompt.submit's first busy check and this
# helper. Let the caller retry and claim the now-idle session.
return None
with session["history_lock"]:
if not session.get("running"):
# Turn ended since prompt.submit's busy check; caller retries on the idle session.
return None
image_paths = list(session.get("attached_images", []))
if image_paths:
# Claim at submission time. A later paste must not be consumed by
# this prompt after the active turn finally yields.
# Claim now so a later paste isn't consumed by this prompt when the turn yields.
session["attached_images"] = []
text_only = not image_paths and _is_text_only_busy_payload(text)
plain_text = _coerce_message_text(text).strip() if text_only else ""
if mode == "steer" and text_only and plain_text and agent is not None and hasattr(agent, "steer"):
try:
if agent.steer(plain_text):
with session["history_lock"]:
_record_inflight_correction(session, plain_text)
_drop_queued_duplicates_of_inflight_user(session)
session["last_active"] = time.time()
_ac_record_inflight_correction(session, plain_text)
return _ok(rid, {"status": "steered"})
except Exception:
pass # fall through to queue
# Text-only corrections redirect the live turn in place when the runtime
# supports it; media/attachment payloads and older agents fall through to
# the proven interrupt + queue path below.
# Text-only corrections redirect in place when supported; media payloads and
# older agents fall through to the proven interrupt + queue path.
if (
mode == "interrupt"
and text_only
@@ -413,18 +344,12 @@ def _handle_busy_submit(
):
try:
if agent.redirect(plain_text):
with session["history_lock"]:
_record_inflight_correction(session, plain_text)
# #84417: do not re-fire the live turn's original user text
# from a stale server-queue self-duplicate after settle.
_drop_queued_duplicates_of_inflight_user(session)
session["last_active"] = time.time()
_ac_record_inflight_correction(session, plain_text)
return _ok(rid, {"status": "redirected"})
except Exception:
pass # preserve the proven interrupt + queue fallback below
# Queue before asking the live turn to stop. In particular, never call a
# provider or compute-host method while holding history_lock: an interrupt
# can wait behind the very operation it is trying to cancel.
# Queue before asking the live turn to stop. Never call a provider/compute-host
# method under history_lock: an interrupt can wait behind the op it cancels.
with session["history_lock"]:
if not session.get("running"):
if image_paths:
@@ -433,17 +358,10 @@ def _handle_busy_submit(
_enqueue_prompt(session, text, transport, image_paths=image_paths)
session["last_active"] = time.time()
# Attachments need a separate model invocation. Queue them without
# cancelling the active turn so the user gets both results in order.
#
# #86134: ``steer`` mode must NEVER escalate to a hard interrupt. A burst
# of user messages while the agent is busy can land as a mix of accepted
# steers (stashed in ``AIAgent._pending_steer``) and fall-through queue
# envelopes (payload not steerable, ``steer()`` rejected/raised). A hard
# interrupt here kills the live turn AND ``AIAgent.interrupt()`` drops
# the pending steer buffer — silently destroying the earlier messages of
# the burst. Steer-mode fall-throughs keep queue semantics: preserved
# FIFO in ``queued_prompt``/``queued_prompts`` and drained on turn end.
# Attachments need their own model invocation: queue without cancelling so the
# user gets both results in order. ``steer`` must NEVER escalate to a hard
# interrupt: it would kill the live turn AND drop ``AIAgent._pending_steer``,
# destroying earlier accepted steers; steer fall-throughs stay FIFO-queued.
if mode == "interrupt" and not image_paths:
_interrupt_busy_session(sid, session, agent)
return _ok(rid, {"status": "queued"})
@@ -452,9 +370,8 @@ def _handle_busy_submit(
def _drain_queued_prompt(rid, sid: str, session: dict) -> bool:
"""Fire a queued next-turn prompt if one is waiting and the session is idle.
Returns True if a queued prompt was dispatched (the caller should then skip
lower-priority follow-ups this cycle — the user's message wins). Mirrors the
claim-under-lock pattern used by the goal-continuation re-fire.
True when dispatched: the caller skips lower-priority follow-ups this cycle
(the user's message wins). Claim-under-lock like the goal-continuation re-fire.
"""
with session["history_lock"]:
if session.get("_closing"):
@@ -473,39 +390,24 @@ def _drain_queued_prompt(rid, sid: str, session: dict) -> bool:
use_compute_host = _session_uses_compute_host(session)
with session["history_lock"]:
if int(session.get("_queued_prompt_generation", 0)) != queue_generation:
# Generation cancelled the claim (Stop, compress re-anchor, …).
# Do not dispatch — but put the claimed envelope back so a
# legitimate follow-up is not silently dropped. Order: claimed
# head first, then whatever advanced into the slot while we held
# the claim (#84417 belt accuracy).
# Generation bump cancelled the claim (Stop, compress re-anchor, …): don't
# dispatch, but restore the envelope (claimed head first, then whatever
# advanced into the slot) so a legitimate follow-up isn't dropped.
rest: list = []
advanced = session.get("queued_prompt")
if advanced:
rest.append(advanced)
rest.extend(session.get("queued_prompts") or [])
session["queued_prompt"] = queued
if rest:
session["queued_prompts"] = rest
else:
session.pop("queued_prompts", None)
_ac_set_queue(session, [queued, *rest])
session["running"] = False
return True
kwargs: dict = {"queued_prompt_generation": queue_generation}
if queued.get("image_paths"):
kwargs["image_paths"] = queued["image_paths"]
dispatch_failed = False
try:
if use_compute_host:
if queued.get("image_paths"):
resp = _submit_prompt_to_compute_host(
rid,
sid,
session,
queued["text"],
image_paths=queued["image_paths"],
queued_prompt_generation=queue_generation,
)
else:
resp = _submit_prompt_to_compute_host(
rid, sid, session, queued["text"], queued_prompt_generation=queue_generation
)
resp = _submit_prompt_to_compute_host(rid, sid, session, queued["text"], **kwargs)
if resp.get("error"):
message = str(((resp.get("error") or {}).get("message")) or "queued prompt failed")
with session["history_lock"]:
@@ -514,37 +416,14 @@ def _drain_queued_prompt(rid, sid: str, session: dict) -> bool:
_emit("error", sid, {"message": message})
dispatch_failed = True
else:
if queued.get("image_paths"):
_run_prompt_submit(
rid,
sid,
session,
queued["text"],
image_paths=queued["image_paths"],
queued_prompt_generation=queue_generation,
)
else:
_run_prompt_submit(
rid,
sid,
session,
queued["text"],
queued_prompt_generation=queue_generation,
)
_run_prompt_submit(rid, sid, session, queued["text"], **kwargs)
except Exception as exc:
print(
f"[tui_gateway] queued prompt dispatch failed: "
f"{type(exc).__name__}: {exc}",
file=sys.stderr,
)
with session["history_lock"]:
session["running"] = False
print(f"[tui_gateway] queued prompt dispatch failed: {type(exc).__name__}: {exc}", file=sys.stderr)
_ac_release_turn(session)
dispatch_failed = True
if dispatch_failed:
with session["history_lock"]:
drain_next = bool(session.get("queued_prompt")) and not session.get(
"_turn_cancel_requested"
)
drain_next = bool(session.get("queued_prompt")) and not session.get("_turn_cancel_requested")
if drain_next:
_drain_queued_prompt(rid, sid, session)
return True
@@ -560,11 +439,7 @@ def _inflight_snapshot(session: dict) -> dict | None:
error = str(turn.get("error") or "").strip()
if not user and not assistant and not streaming and not error:
return None
snapshot = {
"assistant": assistant,
"streaming": streaming,
"user": user,
}
snapshot = {"assistant": assistant, "streaming": streaming, "user": user}
raw_corrections = turn.get("corrections") or []
raw_offsets = turn.get("correction_offsets") or []
correction_pairs = [
@@ -573,19 +448,15 @@ def _inflight_snapshot(session: dict) -> dict | None:
if str(c).strip()
]
if correction_pairs:
# Mid-turn redirects. Carried alongside the original prompt (not over
# it) so resume can rebuild every user bubble the turn produced.
# Mid-turn redirects alongside (not over) the original prompt so resume can
# rebuild every user bubble; offsets only when every correction has one so
# clients can trust the pairing.
snapshot["corrections"] = [c for c, _ in correction_pairs]
# Assistant-text lengths at each correction boundary (parallel list).
# Only sent when every correction has one, so clients can trust the
# pairing; older in-memory turns without offsets omit the field and
# clients fall back to placing corrections after the assistant dump.
if all(isinstance(offset, int) and offset >= 0 for _, offset in correction_pairs):
snapshot["correction_offsets"] = [int(offset) for _, offset in correction_pairs] # type: ignore[arg-type]
if error:
# Retained failed turn (see _fail_inflight_turn): carry the error
# semantics so a resuming client can rebuild the failed-turn bubble
# instead of rendering the partial text as a healthy reply.
# Retained failed turn (_fail_inflight_turn): a resuming client must rebuild
# the failed bubble, not render the partial text as a healthy reply.
snapshot["error"] = error
snapshot["status"] = str(turn.get("status") or "error")
snapshot["recoverable"] = bool(turn.get("recoverable"))
@@ -596,29 +467,17 @@ def _inflight_snapshot(session: dict) -> dict | None:
def _emit_terminal_turn_error(
sid: str,
session: dict,
error: Any,
error_surface: Optional[dict] = None,
*,
retire_marker: bool = True,
sid: str, session: dict, error: Any, error_surface: Optional[dict] = None, *, retire_marker: bool = True
) -> None:
"""Close a failed turn with a terminal ``message.complete`` frame.
Emits the same ``status: "error"`` frame shape the returned-error path in
``_run_prompt_submit`` already produces (so TUI/desktop handling is
uniform), and retains the failed turn via ``_fail_inflight_turn`` so a
client that missed this frame (disconnect window) can recover it from
``session.resume``'s ``inflight`` payload.
``error_surface`` lets callers that already know the failing layer (e.g.
agent-init failures = local runtime) pass it explicitly; exception
callers leave it None and the classifier derives it here.
"""Close a failed turn with the same ``status: "error"`` ``message.complete``
frame as ``_run_prompt_submit``'s returned-error path, retaining the turn via
``_fail_inflight_turn`` so a client that missed the frame recovers it from
``session.resume``'s ``inflight``. Callers that know the failing layer pass
``error_surface``; exception callers leave it None and it is classified here.
"""
agent = session.get("agent")
# Classify the failure into a {layer, code, retryable} descriptor so the
# desktop can say "Provider error" / "Gateway error" with matching
# recovery actions instead of a generic toast. Never raises (advisory).
# {layer, code, retryable} descriptor so the desktop can say "Provider error" /
# "Gateway error" with matching recovery actions. Advisory: never raises.
if error_surface is None and isinstance(error, BaseException):
try:
from agent.error_surface import build_error_surface_from_exception
@@ -660,12 +519,9 @@ def _emit_terminal_turn_error(
def _restore_agent_history_after_turn_error(session: dict, agent) -> bool:
"""Keep a failed turn's working transcript in the gateway session.
``AIAgent`` persists its working messages independently of the gateway's
history snapshot. If the turn raises after that persistence, the next
prompt must see the working transcript instead of the pre-turn snapshot.
"""
"""Keep a failed turn's working transcript: ``AIAgent`` persists its messages
independently, so after a raise the next prompt must see them, not the
pre-turn snapshot."""
agent_messages = getattr(agent, "_session_messages", None)
if not isinstance(agent_messages, list):
return False
@@ -676,13 +532,8 @@ def _restore_agent_history_after_turn_error(session: dict, agent) -> bool:
def _queued_prompt_snapshot(session: dict) -> dict | None:
"""Return the accepted next-turn prompt without its transport handle.
A busy ``prompt.submit`` lives only in ``session["queued_prompt"]`` until
the current turn winds down. Desktop may reconnect or restart during that
window, so the live-session projection must carry the user-visible text;
otherwise the accepted prompt disappears until it finally drains.
"""
"""The accepted next-turn prompt without its transport handle, for the
live-session projection (Desktop may reconnect while it is still queued)."""
queued = session.get("queued_prompt")
if not isinstance(queued, dict):
return None
+120 -315
View File
@@ -1,33 +1,27 @@
"""Live compression: config hot-reload onto a running agent, pending model switch apply, /compress (CompressionLockHeld when a turn holds the lock), session-key sync after compress.
"""Live compression: config hot-reload onto a running agent, pending model switch apply, /compress
(CompressionLockHeld when a turn holds the lock), session-key sync after compress.
Bodies are rebound onto server.py's globals at install time (see
method_ctx.bind_module), so they reference server.py globals bare.
Bodies are rebound onto server.py's globals (method_ctx.bind_module) and reference them bare.
"""
from __future__ import annotations
import contextlib
from .method_ctx import HandlerRegistry, bind_module
_registry = HandlerRegistry()
def _tui_compression_config_signature(cfg: dict | None) -> tuple:
"""Stable snapshot of compression/context keys that must apply next turn.
Reuses the messaging-gateway cache-busting extract so Desktop/TUI and
messaging stay on the same key set. Adds ``idle_compact_after_seconds``
and ``tail_mode``, which affect live TUI sessions but are not in the
gateway tuple today.
"""
"""Stable snapshot of compression/context keys that must apply next turn: the messaging-gateway
cache-busting extract (same key set as messaging) plus ``idle_compact_after_seconds`` and
``tail_mode`` (affect live TUI sessions, not in the gateway tuple)."""
from gateway.run import GatewayRunner
keys = GatewayRunner._extract_cache_busting_config(cfg)
picked = {
key: value
for key, value in keys.items()
if key.startswith("compression.") or key == "model.context_length"
}
picked = {k: v for k, v in keys.items() if k.startswith("compression.") or k == "model.context_length"}
compression = cfg.get("compression") if isinstance(cfg, dict) and isinstance(cfg.get("compression"), dict) else {}
for extra in ("idle_compact_after_seconds", "tail_mode"):
picked[f"compression.{extra}"] = compression.get(extra)
@@ -35,88 +29,65 @@ def _tui_compression_config_signature(cfg: dict | None) -> tuple:
def _compressor_ctor_default(name: str, fallback: Any) -> Any:
"""Read a normalized default from ContextCompressor's REAL signature.
Unset restoration must go through the same derivation the construction
path uses (#94724 review finding on #95980) — pulling the default off
``ContextCompressor.__init__`` itself instead of hardcoding copies keeps
the two from drifting.
"""
"""Default read off ContextCompressor.__init__'s REAL signature, so unset-key restoration uses the
construction path's derivation instead of a hardcoded copy that could drift."""
try:
import inspect
from agent.context_compressor import ContextCompressor
default = inspect.signature(ContextCompressor.__init__).parameters[
name
].default
if default is inspect.Parameter.empty:
return fallback
return default
default = inspect.signature(ContextCompressor.__init__).parameters[name].default
return fallback if default is inspect.Parameter.empty else default
except Exception:
return fallback
def _derived_default_threshold_percent(agent: Any, compression: dict) -> float:
"""Default compaction threshold when ``compression.threshold`` is unset.
Mirrors agent_init exactly: the ctor's global default, then the per-model
resolution (Codex gpt-5.4/5.5 + spark autoraise, Arcee Trinity, etc.)
via the SAME ``_resolve_compression_threshold`` helper — so removing the
key restores the model-derived value, not a bare constant.
"""
"""Default compaction threshold when ``compression.threshold`` is unset. Mirrors agent_init: ctor
global default, then per-model resolution (Codex autoraise etc.) via the SAME
``_resolve_compression_threshold`` — removing the key restores the model-derived value."""
try:
pct = float(_compressor_ctor_default("threshold_percent", 0.50))
except (TypeError, ValueError):
pct = 0.50
try:
from agent.agent_init import _resolve_compression_threshold
from agent.auxiliary_client import (
_compression_threshold_for_model,
_is_codex_gpt54_or_gpt55,
_is_codex_spark,
)
from agent.auxiliary_client import _compression_threshold_for_model, _is_codex_gpt54_or_gpt55, _is_codex_spark
model = getattr(agent, "model", "") or ""
provider = getattr(agent, "provider", "") or ""
autoraise_enabled = str(
compression.get("codex_gpt55_autoraise", True)
).lower() in {"true", "1", "yes"}
autoraise_enabled = str(compression.get("codex_gpt55_autoraise", True)).lower() in {"true", "1", "yes"}
model_cthresh = _compression_threshold_for_model(
model,
provider,
allow_codex_gpt55_autoraise=autoraise_enabled,
model, provider, allow_codex_gpt55_autoraise=autoraise_enabled
)
pct, _notice = _resolve_compression_threshold(
pct,
model_cthresh,
model=model,
is_codex_autoraise=(
_is_codex_gpt54_or_gpt55(model, provider)
or _is_codex_spark(model, provider)
),
pct, model_cthresh, model=model,
is_codex_autoraise=_is_codex_gpt54_or_gpt55(model, provider) or _is_codex_spark(model, provider),
)
except Exception:
pass
return pct
# (config key == compressor attr, ctor-default fallback, min_value)
_COMPRESSION_INT_KEYS = (
("proactive_prune_tokens", 0, 0),
("proactive_prune_min_result_chars", 8000, 0),
("proactive_prune_min_reclaim_tokens", 4096, 0),
("protect_last_n", 20, 0),
("min_tail_user_messages", 1, 1),
)
def _apply_live_compression_config(agent: Any, cfg: dict | None) -> None:
"""Update a live session's compressor from current config.yaml.
"""Update a live session's compressor from current config.yaml, preserving the agent object,
session identity, history and callbacks. Recomputes the trigger from the ratio threshold, then
applies ``compression.threshold_tokens`` so raising/lowering/clearing the cap lands next preflight.
Preserves the agent object, session identity, history, and callbacks.
Recomputes the trigger from the ratio-based threshold and then applies
``compression.threshold_tokens`` so raising, lowering, or clearing the
cap all take effect on the next preflight.
Every adopted key has UNSET semantics (#94724 review finding on the
merged #95980): removing a key from config.yaml restores the normalized
default — or the model-derived value — on the next turn, through the
same derivation the construction path uses (ContextCompressor ctor
defaults read off its real signature, the Codex threshold autoraise via
``_resolve_compression_threshold``, context-length re-inference via the
deferred ``get_model_context_length`` resolution). The old behavior
acted only on PRESENT keys, leaving stale values active forever.
Every adopted key has UNSET semantics: a removed key restores the normalized default (or the
model-derived value) through the construction path's own derivation (ctor signature defaults,
Codex autoraise, deferred context-length re-inference). Acting only on PRESENT keys would leave
stale values active forever.
"""
cfg = cfg if isinstance(cfg, dict) else {}
compression_raw = cfg.get("compression")
@@ -129,12 +100,8 @@ def _apply_live_compression_config(agent: Any, cfg: dict | None) -> None:
else:
agent.compression_enabled = str(enabled_raw).lower() in {"true", "1", "yes"}
agent.codex_responses_native_compaction = is_truthy_value(
compression.get("codex_responses_native", False)
)
native_threshold_raw = compression.get(
"codex_responses_compact_threshold", 200_000
)
agent.codex_responses_native_compaction = is_truthy_value(compression.get("codex_responses_native", False))
native_threshold_raw = compression.get("codex_responses_compact_threshold", 200_000)
try:
if isinstance(native_threshold_raw, bool):
raise ValueError
@@ -142,11 +109,7 @@ def _apply_live_compression_config(agent: Any, cfg: dict | None) -> None:
if native_threshold <= 0:
raise ValueError
except (TypeError, ValueError):
logger.warning(
"Invalid compression.codex_responses_compact_threshold=%r; "
"using 200000.",
native_threshold_raw,
)
logger.warning("Invalid compression.codex_responses_compact_threshold=%r; using 200000.", native_threshold_raw)
native_threshold = 200_000
agent.codex_responses_compact_threshold = native_threshold
@@ -161,52 +124,22 @@ def _apply_live_compression_config(agent: Any, cfg: dict | None) -> None:
if cc is None:
return
# tail_mode: ctor normalization — unknown/absent values land on "lean",
# matching agent_init's default and the compressor's own fallback.
# tail_mode: unknown/absent values land on the ctor default ("lean"), matching agent_init.
default_tail = str(_compressor_ctor_default("tail_mode", "lean"))
mode = str(compression.get("tail_mode", default_tail) or default_tail)
mode = mode.strip().lower()
mode = str(compression.get("tail_mode", default_tail) or default_tail).strip().lower()
cc.tail_mode = mode if mode in ("legacy", "lean") else default_tail
def _assign_int(key: str, attr: str, default: int, min_value: int = 0) -> None:
for key, fallback, min_value in _COMPRESSION_INT_KEYS:
default = int(_compressor_ctor_default(key, fallback))
raw = compression.get(key, default)
try:
value = default if raw is None else int(raw)
except (TypeError, ValueError):
return
setattr(cc, attr, max(min_value, value))
_assign_int(
"proactive_prune_tokens",
"proactive_prune_tokens",
int(_compressor_ctor_default("proactive_prune_tokens", 0)),
)
_assign_int(
"proactive_prune_min_result_chars",
"proactive_prune_min_result_chars",
int(_compressor_ctor_default("proactive_prune_min_result_chars", 8000)),
)
_assign_int(
"proactive_prune_min_reclaim_tokens",
"proactive_prune_min_reclaim_tokens",
int(_compressor_ctor_default("proactive_prune_min_reclaim_tokens", 4096)),
)
_assign_int(
"protect_last_n",
"protect_last_n",
int(_compressor_ctor_default("protect_last_n", 20)),
)
_assign_int(
"min_tail_user_messages",
"min_tail_user_messages",
int(_compressor_ctor_default("min_tail_user_messages", 1)),
min_value=1,
)
continue
setattr(cc, key, max(min_value, value))
try:
ratio_raw = compression.get(
"target_ratio", _compressor_ctor_default("summary_target_ratio", 0.20)
)
ratio_raw = compression.get("target_ratio", _compressor_ctor_default("summary_target_ratio", 0.20))
cc.summary_target_ratio = max(0.10, min(float(ratio_raw), 0.80))
except (TypeError, ValueError):
pass
@@ -215,16 +148,13 @@ def _apply_live_compression_config(agent: Any, cfg: dict | None) -> None:
if isinstance(raw_thresholds, dict):
cc.model_thresholds = {
str(k): float(v)
for k, v in raw_thresholds.items()
if isinstance(v, (int, float)) and not isinstance(v, bool)
for k, v in raw_thresholds.items() if isinstance(v, (int, float)) and not isinstance(v, bool)
}
else:
# Absent (or invalid shape — agent_init treats both as empty):
# stale per-model overrides must stop steering the live threshold.
# Absent or invalid shape (agent_init treats both as empty): stale overrides must stop steering.
cc.model_thresholds = {}
# threshold: present value wins; absence derives the default through
# the same agent_init resolution (global default + per-model autoraise).
# threshold: present value wins; absence derives via the agent_init resolution (default + autoraise).
pct: float | None = None
if "threshold" in compression:
try:
@@ -241,17 +171,11 @@ def _apply_live_compression_config(agent: Any, cfg: dict | None) -> None:
if model_thresholds:
from agent.context_compressor import resolve_model_threshold
base = resolve_model_threshold(
getattr(agent, "model", "") or "",
model_thresholds,
pct,
)
base = resolve_model_threshold(getattr(agent, "model", "") or "", model_thresholds, pct)
cc._base_threshold_percent = base
if hasattr(cc, "_effective_threshold_percent"):
try:
cc.threshold_percent = cc._effective_threshold_percent(
cc.context_length, base
)
cc.threshold_percent = cc._effective_threshold_percent(cc.context_length, base)
except Exception:
cc.threshold_percent = pct
else:
@@ -272,11 +196,8 @@ def _apply_live_compression_config(agent: Any, cfg: dict | None) -> None:
except Exception:
pass
elif getattr(cc, "_config_context_length", None) is not None:
# model.context_length removed: drop the config override and force
# re-inference from model metadata on next access — the same
# deferred get_model_context_length resolution agent construction
# uses (#32221). The re-resolve also re-applies the small-context
# threshold floor for the genuinely re-inferred window.
# model.context_length removed: drop the override and force re-inference from model metadata
# on next access (construction's deferred resolution); re-applies the small-context floor too.
cc._config_context_length = None
cc._resolved_context_length = None
@@ -292,8 +213,7 @@ def _apply_live_compression_config(agent: Any, cfg: dict | None) -> None:
else:
cc.threshold_tokens_cap = None
# Invalidate cached trigger so the next preflight re-derives from the
# current percent/window and then applies the (possibly new) cap.
# Invalidate the cached trigger so the next preflight re-derives from percent/window, then the cap.
if hasattr(cc, "_threshold_tokens"):
cc._threshold_tokens = None
if hasattr(cc, "_tail_token_budget"):
@@ -315,12 +235,8 @@ def _apply_live_compression_config(agent: Any, cfg: dict | None) -> None:
def _sync_agent_compression_with_config(sid: str, session: dict) -> None:
"""Adopt compression.* / model.context_length edits at turn start.
Messaging gateways already rebuild a cached agent when these keys change.
Desktop/TUI only synced the model; the live compressor kept the threshold
captured at agent creation (#95151).
"""
"""Adopt compression.* / model.context_length edits at turn start (messaging gateways rebuild the
agent on these keys; Desktop/TUI keeps the live compressor, so it must be updated in place)."""
agent = session.get("agent")
if agent is None:
return
@@ -333,20 +249,14 @@ def _sync_agent_compression_with_config(sid: str, session: dict) -> None:
try:
_apply_live_compression_config(agent, cfg)
except Exception as e:
logger.warning(
"Could not apply live compression config for %s: %s", sid, e
)
logger.warning("Could not apply live compression config for %s: %s", sid, e)
def _apply_pending_model_switch(sid: str, session: dict) -> None:
"""Apply a model switch queued while a turn was running.
"""Apply a model switch queued (``session["pending_model_switch"]``) while a turn was running.
``config.set model`` on a busy session doesn't mutate the live agent (the
worker thread is reading model/client mid-request); it stashes the pick in
``session["pending_model_switch"]``. This runs on the TURN thread at turn
start — before the first model call, nothing in flight — so the in-place
swap (client rebuild, the slow part) is safe here. A failed switch keeps
the current model and never blocks the turn, matching
Runs on the TURN thread at turn start — nothing in flight — so the in-place swap (client rebuild)
is safe. A failed switch keeps the current model and never blocks the turn, matching
``_sync_agent_model_with_config``.
"""
pending = session.pop("pending_model_switch", None)
@@ -354,85 +264,55 @@ def _apply_pending_model_switch(sid: str, session: dict) -> None:
return
try:
result = _apply_model_switch(
sid,
session,
pending["raw"],
confirm_expensive_model=bool(pending.get("confirm_expensive_model")),
sid, session, pending["raw"], confirm_expensive_model=bool(pending.get("confirm_expensive_model"))
)
# A queued pick is a deliberate user action; honour the expensive-model
# confirm by NOT applying it silently — surface the warning and drop the
# switch rather than spend on a pricey model the user never confirmed.
# Honour the expensive-model confirm: surface the warning and drop the switch rather than
# spend on a model the user never confirmed.
if result.get("confirm_required"):
_emit(
"error",
sid,
{"message": result.get("confirm_message") or result.get("warning") or ""},
)
_emit("error", sid, {"message": result.get("confirm_message") or result.get("warning") or ""})
except Exception as e:
_emit(
"error",
sid,
{"message": f"Could not switch model: {e}"},
)
_emit("error", sid, {"message": f"Could not switch model: {e}"})
class CompressionLockHeld(Exception):
"""Raised by _compress_session_history when compression skipped due
to a concurrent lock on the session's compression_locks row."""
"""Raised by _compress_session_history when a concurrent compression_locks row skipped compression."""
def __init__(self, holder: str | None = None):
self.holder = holder
super().__init__(f"Compression lock held: {holder or 'unknown'}")
def _compress_session_history(
session: dict,
focus_topic: str | None = None,
approx_tokens: int | None = None,
before_messages: list | None = None,
history_version: int | None = None,
session: dict, focus_topic: str | None = None, approx_tokens: int | None = None,
before_messages: list | None = None, history_version: int | None = None,
) -> tuple[int, dict]:
"""Compress a session's history — the single choke point shared by all
three manual-compress routes (session.compress RPC, command.dispatch
/compress|/compact, and the slash-exec mirror).
"""Single choke point for all manual-compress routes (session.compress RPC, command.dispatch
/compress|/compact, slash-exec mirror).
``focus_topic`` is the RAW argument string after ``/compress``. It is
parsed here with :func:`parse_partial_compress_args` so boundary-aware
forms (``here [N]``, ``up to here``, ``--keep N``) trigger a partial
compress — head summarized, most recent ``keep_last`` exchanges kept
verbatim — on EVERY route, mirroring cli.py's ``_manual_compress`` and
gateway/slash_commands.py (PR #35252). Parsing at the choke point (not
per-route) is what fixes #35533: previously "/compress here 3" reached
this helper unparsed and ran a FULL compress focused on the literal
text "here 3".
``focus_topic`` is the RAW argument string after ``/compress``, parsed HERE (not per-route) with
:func:`parse_partial_compress_args` so boundary forms (``here [N]``, ``up to here``, ``--keep N``)
trigger a partial compress on EVERY route — otherwise "/compress here 3" would run a FULL compress
focused on the literal text "here 3". Mirrors cli.py ``_manual_compress`` / gateway slash_commands.
"""
from agent.conversation_compression import (
finalize_context_engine_compression_notification,
)
from agent.conversation_compression import finalize_context_engine_compression_notification
from agent.model_metadata import estimate_request_tokens_rough
from hermes_cli.partial_compress import (
parse_partial_compress_args,
rejoin_compressed_head_and_tail,
split_history_for_partial_compress,
parse_partial_compress_args, rejoin_compressed_head_and_tail, split_history_for_partial_compress,
)
agent = session["agent"]
# Snapshot history under the lock so the LLM-bound compression call
# below does NOT hold history_lock for the duration of the request —
# otherwise other handlers acquiring the lock (prompt.submit etc.)
# block on the dispatcher loop while compaction runs.
# Snapshot under the lock so the LLM-bound compression call does NOT hold history_lock for the
# request — otherwise prompt.submit etc. block on the dispatcher loop while compaction runs.
if before_messages is None or history_version is None:
with session["history_lock"]:
before_messages = list(session.get("history", []))
history_version = int(session.get("history_version", 0))
history = before_messages
if len(history) < 4:
usage = _get_usage(agent)
return 0, usage
return 0, _get_usage(agent)
partial, keep_last, focus_topic = parse_partial_compress_args(focus_topic or "")
# Boundary-aware split: only the head is summarized; the most recent
# `keep_last` exchanges ride along verbatim. A degenerate split (empty
# tail — everything would be kept, or no head left to compress) falls
# back to full compression so the user still gets an action.
# Only the head is summarized; the last `keep_last` exchanges ride along verbatim. A degenerate
# split (empty tail) falls back to full compression so the user still gets an action.
tail: list = []
head = history
if partial:
@@ -441,100 +321,53 @@ def _compress_session_history(
partial = False
head = history
if approx_tokens is None:
# Include system prompt + tool schemas so the figure reflects real
# request pressure, not a transcript-only underestimate (#6217).
# Include system prompt + tool schemas so the figure reflects real request pressure.
_sys_prompt = getattr(agent, "_cached_system_prompt", "") or ""
_tools = getattr(agent, "tools", None) or None
approx_tokens = estimate_request_tokens_rough(
history, system_prompt=_sys_prompt, tools=_tools
)
# Pass system_message=None so AIAgent._compress_context rebuilds the
# system prompt cleanly via _build_system_prompt(None). Passing the
# cached prompt (which already contains the agent identity block)
# makes the rebuild append the identity a second time. Mirrors the
# CLI's _manual_compress fix for issue #15281.
# force=True: every caller of this helper is a manual /compress path
# (session.compress RPC, slash compress/compact, slash-worker mirror) —
# auto-compaction runs inside the agent loop, not here. Manual
# compaction bypasses the summary-failure cooldown, matching the CLI
# and gateway handlers.
approx_tokens = estimate_request_tokens_rough(history, system_prompt=_sys_prompt, tools=_tools)
# system_message=None: _compress_context rebuilds the system prompt via _build_system_prompt(None);
# passing the cached prompt (already holding the identity block) appends the identity twice.
# force=True: every caller is a manual /compress path, which bypasses the summary-failure
# cooldown like the CLI and gateway handlers. Partial compress has no focus topic (exclusive modes).
try:
compressed, _ = agent._compress_context(
head,
None,
approx_tokens=approx_tokens,
# Partial compress has no focus topic (the modes are exclusive;
# parse_partial_compress_args returns focus_topic=None for the
# boundary-aware forms).
focus_topic=focus_topic or None,
force=True,
head, None, approx_tokens=approx_tokens, focus_topic=focus_topic or None, force=True,
defer_context_engine_notification=True,
)
except Exception:
finalize_context_engine_compression_notification(
agent,
committed=False,
)
finalize_context_engine_compression_notification(agent, committed=False)
raise
# If _compress_context returned unchanged because a concurrent
# compression lock is held, raise so callers can surface a clear
# message instead of the misleading "No changes from compression" text.
# Type-pinned (is True / str): real values are None/True/holder-string;
# bare truthiness is fooled by MagicMock auto-attrs on test doubles.
# Lock-skipped: raise so callers surface a clear message instead of "No changes from compression".
# Type-pinned (is True / str) because bare truthiness is fooled by MagicMock auto-attrs.
_lock_skipped = getattr(agent, "_compression_skipped_due_to_lock", None)
if _lock_skipped is True or isinstance(_lock_skipped, str):
agent._compression_skipped_due_to_lock = None
# No boundary was committed on a lock-skip; discard any pending
# deferred context-engine notification (exactly-once, no-op safe).
finalize_context_engine_compression_notification(
agent,
committed=False,
)
raise CompressionLockHeld(
_lock_skipped if isinstance(_lock_skipped, str) else None
)
# No boundary committed; discard the pending deferred notification (exactly-once, no-op safe).
finalize_context_engine_compression_notification(agent, committed=False)
raise CompressionLockHeld(_lock_skipped if isinstance(_lock_skipped, str) else None)
if partial and tail:
compressed = rejoin_compressed_head_and_tail(compressed, tail)
with session["history_lock"]:
if int(session.get("history_version", 0)) != history_version:
# External mutation during compaction — drop the compressed
# result so we don't clobber concurrent edits.
finalize_context_engine_compression_notification(
agent,
committed=False,
)
usage = _get_usage(agent)
return 0, usage
# External mutation during compaction — drop the result so we don't clobber concurrent edits.
finalize_context_engine_compression_notification(agent, committed=False)
return 0, _get_usage(agent)
session["history"] = compressed
session["history_version"] = history_version + 1
usage = _get_usage(agent)
return len(history) - len(compressed), usage
return len(history) - len(compressed), _get_usage(agent)
def _sync_session_key_after_compress(
sid: str,
session: dict,
*,
clear_pending_title: bool = True,
restart_slash_worker: bool = True,
sid: str, session: dict, *, clear_pending_title: bool = True, restart_slash_worker: bool = True
) -> None:
"""Re-anchor session_key when AIAgent._compress_context rotates session_id.
"""Re-anchor the gateway-side ``session_key`` when _compress_context rotates ``agent.session_id``
to a SessionDB continuation; otherwise approval routing, slash worker init, DB title/history
lookups and yolo state keep targeting the ended parent.
AIAgent._compress_context ends the current SessionDB session and creates
a new continuation session, rotating ``agent.session_id``. The TUI
gateway keeps the gateway-side ``session_key`` separate (used for
approval routing, slash worker init, DB title/history lookups, yolo
state). Without this sync, those operations would target the ended
parent session while the agent writes to the new continuation session.
Policy flags:
clear_pending_title: True for manual /compress (title belongs to old
session). False for post-turn auto-compression (preserve user
intent so pending_title can be applied to the continuation).
restart_slash_worker: True for manual /compress and post-turn
auto-compression (worker holds stale session key). False only
if the caller manages the worker lifecycle separately.
clear_pending_title: True for manual /compress (title belongs to the old session); False for
post-turn auto-compression so pending_title applies to the continuation.
restart_slash_worker: True unless the caller manages the worker (it holds the stale key).
"""
agent = session.get("agent")
new_session_id = getattr(agent, "session_id", None) or ""
@@ -542,73 +375,45 @@ def _sync_session_key_after_compress(
if not new_session_id or new_session_id == old_key:
return
lease_reanchored = _transfer_active_session_slot(
sid,
session,
new_session_id=new_session_id,
)
lease_reanchored = _transfer_active_session_slot(sid, session, new_session_id=new_session_id)
if not lease_reanchored:
logger.warning(
"Compression session lease did not re-anchor: sid=%s old_session_id=%s new_session_id=%s",
sid,
old_key,
new_session_id,
sid, old_key, new_session_id,
)
try:
from tools.approval import (
disable_session_yolo,
enable_session_yolo,
is_session_yolo_enabled,
register_gateway_notify,
disable_session_yolo, enable_session_yolo, is_session_yolo_enabled, register_gateway_notify,
unregister_gateway_notify,
)
try:
with contextlib.suppress(Exception):
unregister_gateway_notify(old_key)
except Exception:
pass
session["session_key"] = new_session_id
try:
yolo_was_on = is_session_yolo_enabled(old_key)
except Exception:
yolo_was_on = False
if yolo_was_on:
try:
with contextlib.suppress(Exception):
enable_session_yolo(new_session_id)
disable_session_yolo(old_key)
except Exception:
pass
try:
register_gateway_notify(
new_session_id,
lambda data: _emit_approval_request(sid, data),
)
except Exception:
pass
with contextlib.suppress(Exception):
register_gateway_notify(new_session_id, lambda data: _emit_approval_request(sid, data))
except Exception:
# Even if the approval module fails to import, still anchor the
# session_key on the new continuation id so downstream lookups
# don't keep targeting the ended row.
# Even if the approval module fails to import, anchor session_key on the continuation id.
session["session_key"] = new_session_id
# #84417 (belt): invalidate any in-flight ``_drain_queued_prompt`` claim
# that captured generation under the pre-rotation session_key. A raced
# drain must not dispatch on the continuation with a stale claim; the
# claimed envelope is restored to the queue (see ``_drain_queued_prompt``)
# so legitimate follow-ups still survive. Complements self-duplicate
# scrubbing on redirect.
session["_queued_prompt_generation"] = int(
session.get("_queued_prompt_generation", 0)
) + 1
# Invalidate any in-flight ``_drain_queued_prompt`` claim taken under the pre-rotation key: a raced
# drain must not dispatch on the continuation (its envelope is restored to the queue).
session["_queued_prompt_generation"] = int(session.get("_queued_prompt_generation", 0)) + 1
if clear_pending_title:
session["pending_title"] = None
if restart_slash_worker:
try:
with contextlib.suppress(Exception):
_restart_slash_worker(sid, session)
except Exception:
pass
def register(server) -> None:
+125 -352
View File
@@ -1,7 +1,7 @@
"""Session history/message shaping: image-ref messages, content coercion, history->wire messages, in-flight turn tracking and turn-failure detail.
"""Session history/message shaping: image-ref messages, content coercion, history->wire messages,
in-flight turn tracking and turn-failure detail.
Bodies are rebound onto server.py's globals at install time (see
method_ctx.bind_module), so they reference server.py globals bare.
Bodies are rebound onto server.py's globals (method_ctx.bind_module) and reference them bare.
"""
from __future__ import annotations
@@ -16,40 +16,17 @@ def _active_image_routing_identity(agent: Any) -> tuple[str, str]:
"""Return the live provider/model, falling back before agent startup."""
from agent.auxiliary_client import _read_main_model, _read_main_provider
return (
getattr(agent, "provider", "") or _read_main_provider(),
getattr(agent, "model", "") or _read_main_model(),
)
return (getattr(agent, "provider", "") or _read_main_provider(), getattr(agent, "model", "") or _read_main_model())
def _build_image_ref_message(user_text: str, image_paths: list[str]) -> str:
"""Reference attached images by path so the agent analyzes them in-loop.
This used to pre-analyze every image with the auxiliary vision model
*before* the turn was dispatched (``_enrich_with_attached_images``):
serial blocking calls on the submit path — 60-90s per large photo —
with failures silently swallowed and an interrupt during the window
killing the turn with zero API calls (#83291). It also prepended the
vision description to the first user message, poisoning session
auto-titles (#82339). The CLI never gates turn dispatch on vision
like this, which is why the same message was seconds there and
minutes on desktop.
Now the turn starts immediately. The agent examines each image itself
with ``vision_analyze`` — its own retries, visible tool progress —
exactly how the ``@folder:`` reference path already behaves, which
responds in seconds for the same images.
"""
parts: list[str] = []
for path in image_paths:
p = Path(path)
if not p.exists():
continue
parts.append(
f"[The user attached an image: {p.name}]\n"
f"[Examine it with the vision_analyze tool using image_url: {p}]"
)
"""Reference attached images by path so the agent analyzes them in-loop with ``vision_analyze``.
Pre-analyzing with the auxiliary vision model blocked submit 60-90s per photo and poisoned
auto-titles with the description."""
parts = [
f"[The user attached an image: {p.name}]\n[Examine it with the vision_analyze tool using image_url: {p}]"
for p in map(Path, image_paths) if p.exists()
]
text = user_text or ""
prefix = "\n\n".join(parts)
if prefix:
@@ -58,21 +35,10 @@ def _build_image_ref_message(user_text: str, image_paths: list[str]) -> str:
def _build_persist_message_with_image_refs(user_text: str, image_paths: list[str]) -> str:
"""Build the clean, UI-recognizable version of the user's message for
persisting to session history. Uses ``@image:<path>`` directives — the
format the desktop client (directive-text.tsx / HERMES_DIRECTIVE_RE)
actually parses and renders as an image — unlike
``_build_image_ref_message``, which embeds an
``image_url:`` hint meant only for the model and must never be
persisted as-is (it silently breaks image rendering after a full
restart, and reorders image/text on live session-switch reconciliation).
The caption leads and the directives trail: session previews are the first
60 characters of the first user message (``list_sessions_rich``), so a
leading directive would label the session with a truncated file path in the
sidebar, switcher, and command palette. Clients lift the refs out of the
body by line, so their position does not affect how the turn renders.
"""
"""Persisted form of the user's message: ``@image:<path>`` directives (the desktop renders them
as images). ``_build_image_ref_message``'s ``image_url:`` hint is model-only, never persisted.
Caption first, directives last: session previews are the first 60 chars of the first user
message, so a leading directive would label the session with a truncated path."""
from agent.context_references import format_reference_value
text = user_text or ""
@@ -83,16 +49,9 @@ def _build_persist_message_with_image_refs(user_text: str, image_paths: list[str
def _build_persist_user_message(user_text: str, image_paths: list[str], run_message: Any) -> Any:
"""Shape the persisted user turn to match what was sent to the model.
Native-vision turns send ``content`` as a parts list, and
``_flush_messages_to_session_db`` deliberately ignores a plain-string
override for a list payload (a text override must not erase a turn's
image/audio summary). So mirror the shape: replace only the text part with
the ``@image:`` ref form and keep the image parts, so the model still has
the pixels for the rest of the session. Any API-only text part (the
barge-in note) is dropped along the way, which is the point of the override.
"""
"""Shape the persisted user turn like the model payload: ``_flush_messages_to_session_db`` ignores
a plain-string override for a list (native-vision) payload, so swap only the text part for the
``@image:`` form, keep image parts, and drop API-only text parts (barge-in note)."""
persist_text = _build_persist_message_with_image_refs(user_text, image_paths)
if not isinstance(run_message, list):
return persist_text
@@ -100,6 +59,36 @@ def _build_persist_user_message(user_text: str, image_paths: list[str], run_mess
return [{"type": "text", "text": persist_text}, *image_parts]
_HISTORY_TEXT_KINDS = frozenset({"text", "input_text", "output_text"})
_HISTORY_IMAGE_KINDS = frozenset({"image_url", "input_image", "image"})
_HISTORY_AUDIO_KINDS = frozenset({"input_audio", "audio"})
def _history_part_image_url(part: dict) -> str:
"""The URL carried by an image part (``image_url`` dict or str), else ""."""
image_url = part.get("image_url")
if isinstance(image_url, dict):
candidate = image_url.get("url")
return candidate if isinstance(candidate, str) else ""
return image_url if isinstance(image_url, str) else ""
def _history_dict_text(content: dict, *, image_urls: bool) -> str:
"""Placeholder/text rendering of one structured content dict."""
kind = content.get("type")
if kind in _HISTORY_TEXT_KINDS:
return str(content.get("text") or content.get("content") or "")
if kind in _HISTORY_IMAGE_KINDS:
return (_history_part_image_url(content) if image_urls else "") or "[image]"
if kind in _HISTORY_AUDIO_KINDS:
return "[audio]"
if kind:
return f"[{kind}]"
if "text" in content:
return str(content.get("text") or "")
return "[structured content]"
def _content_display_text(content: Any) -> str:
if content is None:
return ""
@@ -108,47 +97,18 @@ def _content_display_text(content: Any) -> str:
if isinstance(content, (int, float)):
return str(content)
if isinstance(content, list):
parts = []
for part in content:
text = _content_display_text(part).strip()
if text:
parts.append(text)
return "\n".join(parts)
parts = (_content_display_text(part).strip() for part in content)
return "\n".join(text for text in parts if text)
if isinstance(content, dict):
kind = content.get("type")
if kind in {"text", "input_text", "output_text"}:
return str(content.get("text") or content.get("content") or "")
if kind in {"image_url", "input_image", "image"}:
return "[image]"
if kind in {"input_audio", "audio"}:
return "[audio]"
if kind:
return f"[{kind}]"
if "text" in content:
return str(content.get("text") or "")
return "[structured content]"
return _history_dict_text(content, image_urls=False)
return str(content)
def _coerce_message_text(content: Any) -> str:
"""Render ``message['content']`` as a plain string for transport.
Provider-side, ``content`` may be a string (most common), a list of
multimodal parts (e.g. ``[{"type": "text", "text": "..."},
{"type": "image_url", "image_url": {...}}]``), or a single structured
dict. Calling ``.strip()`` on a list raises ``'list' object has no
attribute 'strip'`` and breaks session resume entirely.
Image parts (``image_url``) are preserved by appending the underlying
URL (data: or http:) into the text. The desktop renderer pulls these
back out via ``extractEmbeddedImages`` so the user sees the image
instead of the URL — and it stops the resume payload from disagreeing
with the cached message (which would otherwise cause the inline image
to flash, then disappear when the resume payload overwrites the cache).
Other structured dict shapes (audio, unknown types) fall back to a
bracketed placeholder so resume doesn't drop the message entirely.
"""
"""Render ``message['content']`` (str, parts list, or one structured dict) as a plain string.
Image parts keep their URL inline so the desktop's ``extractEmbeddedImages`` and the resume payload
agree with the cached message (else the inline image flashed, then vanished); other structured
shapes become a bracketed placeholder so resume doesn't drop the message."""
if content is None:
return ""
if isinstance(content, str):
@@ -168,56 +128,23 @@ def _coerce_message_text(content: Any) -> str:
chunks.append(text)
continue
kind = part.get("type")
if kind in {"text", "input_text", "output_text"}:
if kind in _HISTORY_TEXT_KINDS:
t = part.get("text") or part.get("content") or ""
if t:
chunks.append(str(t))
continue
if kind in {"image_url", "input_image", "image"}:
image_url = part.get("image_url")
url = ""
if isinstance(image_url, dict):
candidate = image_url.get("url")
if isinstance(candidate, str):
url = candidate
elif isinstance(image_url, str):
url = image_url
if url:
chunks.append(f"\n{url}")
else:
chunks.append("\n[image]")
continue
if kind in {"input_audio", "audio"}:
elif kind in _HISTORY_IMAGE_KINDS:
chunks.append(f"\n{_history_part_image_url(part) or '[image]'}")
elif kind in _HISTORY_AUDIO_KINDS:
chunks.append("\n[audio]")
continue
if kind:
elif kind:
chunks.append(f"\n[{kind}]")
return "".join(chunks)
if isinstance(content, dict):
kind = content.get("type")
if kind in {"text", "input_text", "output_text"}:
return str(content.get("text") or content.get("content") or "")
if kind in {"image_url", "input_image", "image"}:
image_url = content.get("image_url")
url = ""
if isinstance(image_url, dict):
candidate = image_url.get("url")
if isinstance(candidate, str):
url = candidate
elif isinstance(image_url, str):
url = image_url
return url or "[image]"
if kind in {"input_audio", "audio"}:
return "[audio]"
if kind:
return f"[{kind}]"
if "text" in content:
return str(content.get("text") or "")
return "[structured content]"
return _history_dict_text(content, image_urls=True)
return str(content)
_TEXT_ONLY_BUSY_PART_KINDS = frozenset({"text", "input_text", "output_text"})
_TEXT_ONLY_BUSY_PART_KINDS = _HISTORY_TEXT_KINDS
def _is_text_only_busy_payload(content: Any) -> bool:
@@ -227,109 +154,69 @@ def _is_text_only_busy_payload(content: Any) -> bool:
if isinstance(content, (str, int, float)):
return True
if isinstance(content, list):
if not content:
return False
for part in content:
if isinstance(part, str):
continue
if not isinstance(part, dict):
return False
kind = part.get("type")
if kind in _TEXT_ONLY_BUSY_PART_KINDS:
continue
if kind is None and isinstance(part.get("text"), str):
continue
return False
return True
return bool(content) and all(
isinstance(part, str) or (isinstance(part, dict) and _history_text_only_part(part)) for part in content
)
if isinstance(content, dict):
kind = content.get("type")
if kind in _TEXT_ONLY_BUSY_PART_KINDS:
return True
return kind is None and isinstance(content.get("text"), str)
return _history_text_only_part(content)
return False
def _is_display_hidden_marker(role: str | None, text: str) -> bool:
"""Gateway bookkeeping notices (model-switch, personality) are persisted as
role=user ``[System: …]`` rows so strict providers accept them mid-history.
They are model-facing runtime metadata, not user turns, and must never
render as a user bubble in ANY client transcript (desktop, TUI, CLI, web).
def _history_text_only_part(part: dict) -> bool:
kind = part.get("type")
return kind in _TEXT_ONLY_BUSY_PART_KINDS or (kind is None and isinstance(part.get("text"), str))
Filtering here — the single display projection every surface reads — hides
them everywhere while the raw marker stays in ``session["history"]`` for the
model. It also removes the stored marker from the payload the desktop
reconciles against, so it can no longer shift user-message ordinals and
duplicate the optimistic prompt (#67603)."""
def _is_display_hidden_marker(role: str | None, text: str) -> bool:
"""Gateway notices (model-switch, personality) persist as role=user ``[System: …]`` rows so strict
providers accept them mid-history; they must never render as a user bubble. Filtering in this one
projection hides them everywhere (raw marker stays in ``session["history"]``) and keeps them from
shifting the user-message ordinals the desktop reconciles against."""
return role == "user" and text.lstrip().startswith("[System:")
def _skill_scaffold_projection(content_text: str) -> str:
"""Return the invocation a slash-skill-expanded turn came from, else "".
A ``/skill`` invocation expands into a model-facing message that embeds the
whole skill body. That payload belongs to the agent — every UI renders the
invocation (``/work fix the leak``) instead, so no surface can leak the
body into a chat bubble.
"""
"""The invocation a slash-skill-expanded turn came from, else "" — every UI renders
``/work fix the leak`` instead of the embedded skill body."""
return describe_skill_invocation(content_text, separator=" ") or ""
def _expand_skill_invocation_for_replay(text: str, task_id: str) -> str:
"""Re-expand a projected `/skill` invocation before re-running that turn.
The inverse of :func:`_skill_scaffold_projection`. Because a skill turn is
displayed as its invocation, a rewind/regenerate hands us back
``/work fix the leak`` rather than the body the agent originally saw —
re-running that verbatim would drop the skill. Re-expanding here keeps the
body server-side (no client ever holds it) and makes the replayed turn
identical to the original.
Returns *text* unchanged when it isn't a resolvable skill invocation.
"""
"""Inverse of :func:`_skill_scaffold_projection`: rewind/regenerate hands back the projected
invocation, and re-running it verbatim would drop the skill. Unchanged when not resolvable."""
head, _, arg = (text or "").strip().partition(" ")
if not head.startswith("/"):
return text
try:
from agent.skill_commands import (
build_skill_invocation_message,
resolve_skill_command_key,
)
from agent.skill_commands import build_skill_invocation_message, resolve_skill_command_key
cmd_key = resolve_skill_command_key(head.lstrip("/"))
if cmd_key is None:
return text
return build_skill_invocation_message(cmd_key, arg.strip(), task_id=task_id) or text
except Exception:
# A skill that no longer resolves (renamed, disabled, external dir
# gone) must not break the rewind — replay the text as typed.
# A skill that no longer resolves must not break the rewind.
logger.debug("skill re-expansion failed for replay", exc_info=True)
return text
# Opening of the crash-recovery note synthesized by _auto_continue_note.
# Matched (not just built) so a row persisted before the display type was
# stamped at turn start still reads as a timeline event, and to recognize the
# messaging gateway's twin note.
# Opening of the crash-recovery note synthesized by _auto_continue_note; matched (not just built) for
# rows persisted before display typing existed and for the messaging gateway's twin note.
_AUTO_CONTINUE_NOTE_PREFIX = "[System note: Your previous turn was interrupted mid-run"
def _legacy_display_kind(role: str, text: str) -> str | None:
"""Infer the display type of a synthetic row persisted without one.
Turn-start typing (see ``persist_user_display_kind``) covers everything
written from here on. Sessions already on disk carry untyped rows — and a
turn killed mid-run never reached the post-turn stamp at all, which is
exactly the auto-continue case — so the raw recovery note would paint as a
user bubble forever. Sniffing the one fixed synthetic prefix is the
migration for those rows; it is not how new rows get typed.
"""
"""Infer the display type of a synthetic row persisted without one. New rows are typed at turn
start (``persist_user_display_kind``); this prefix sniff migrates untyped rows already on disk (a
turn killed mid-run never reached the stamp), which would otherwise paint as a user bubble."""
if role == "user" and text.lstrip().startswith(_AUTO_CONTINUE_NOTE_PREFIX):
return "auto_continue"
return None
_HISTORY_REASONING_KEYS = ("reasoning", "reasoning_content", "reasoning_details", "codex_reasoning_items")
def _history_to_messages(history: list[dict]) -> list[dict]:
messages = []
tool_call_args = {}
@@ -343,11 +230,7 @@ def _history_to_messages(history: list[dict]) -> list[dict]:
role = m.get("role")
if role not in {"user", "assistant", "tool", "system"}:
continue
# An explicit display_kind="hidden" row is model-facing scaffolding
# (compaction references, interrupted-turn checkpoints). The string
# sniff below only catches the "[System:" convention; honor the
# declared field too, or scaffolding reaches every surface that reads
# this projection.
# display_kind="hidden": model-facing scaffolding the "[System:" sniff does not catch.
if m.get("display_kind") == "hidden":
continue
content_text = _coerce_message_text(m.get("content"))
@@ -371,61 +254,34 @@ def _history_to_messages(history: list[dict]) -> list[dict]:
name = (tc_info[0] if tc_info else None) or m.get("tool_name") or "tool"
args = (tc_info[1] if tc_info else None) or {}
tool_msg = {"role": "tool", "name": name, "context": _tool_ctx(name, args)}
# This is the display projection, so keep it faithful. `context`
# is an 80-char preview for collapsed row titles. A renderer that
# shows the full call (the expanded `$` transcript in the desktop)
# rebuilds it from args. When only the preview shipped, that
# truncation was permanent.
# `context` is an 80-char preview; ship args so a full-call renderer isn't truncated.
if args:
tool_msg["args"] = args
messages.append(tool_msg)
continue
# An assistant turn may carry only reasoning/thinking content with no
# visible text (extended-thinking turns, thinking-only recovery
# responses). Such a turn is persisted with its reasoning fields and is
# recallable from the transcript, but dropping it here as "empty" makes
# it vanish from the resumed/reloaded session view while the desktop's
# reasoning disclosure has nothing to render. Keep it when it carries
# reasoning so the "Thinking…" block still shows. (#44022)
reasoning_keys = (
"reasoning",
"reasoning_content",
"reasoning_details",
"codex_reasoning_items",
)
has_reasoning = role == "assistant" and any(
m.get(key) for key in reasoning_keys
)
# A reasoning-only assistant turn is kept so "Thinking…" still shows after resume/reload.
has_reasoning = role == "assistant" and any(m.get(key) for key in _HISTORY_REASONING_KEYS)
if not content_text.strip() and not has_reasoning:
continue
msg = {"role": role, "text": content_text}
# Persisted authoring time (Unix seconds) for display.timestamps
# renderers (#41531). Display-only: never fed back into model context.
# Authoring time (Unix seconds) for display.timestamps; display-only.
ts = m.get("timestamp")
if isinstance(ts, (int, float)) and ts > 0:
msg["timestamp"] = float(ts)
# Durable row identity, stamped by _rows_to_conversation. The renderer's
# own message ids are ephemeral (timestamp+index derived, and a
# different shape for live vs rehydrated vs optimistic rows), so
# anything that addresses a specific persisted message later — message
# reactions — needs this instead.
# Durable row identity (_rows_to_conversation); reactions etc. address persisted messages by it.
if m.get("_row_id") is not None:
msg["row_id"] = m["_row_id"]
if role == "user":
invocation = _skill_scaffold_projection(content_text)
if invocation:
# Show the invocation, never the expanded skill body. The raw
# payload stays server-side: a rewind/regenerate re-sends the
# turn by ordinal, so no client needs it.
# The invocation, never the expanded body (rewind re-sends by ordinal).
msg["text"] = invocation
msg["display_kind"] = "skill_invocation"
if role == "assistant":
for key in reasoning_keys:
for key in _HISTORY_REASONING_KEYS:
if key in m and m.get(key) is not None:
msg[key] = m.get(key)
# Forward display-only timeline metadata so the TUI can render
# model switches and delegation completions as events instead of
# opaque user messages, and hide compaction handoffs entirely.
# Display-only timeline metadata (model switches, delegation events).
display_kind = m.get("display_kind") or _legacy_display_kind(role, content_text)
if display_kind:
msg["display_kind"] = display_kind
@@ -439,24 +295,19 @@ def _history_to_messages(history: list[dict]) -> list[dict]:
def _coerce_seed_history(value: Any) -> list[dict]:
if not isinstance(value, list):
return []
history = []
for item in value:
if not isinstance(item, dict):
continue
role = item.get("role")
if role not in ("user", "assistant", "system"):
continue
content = item.get("content")
if content is None:
content = item.get("text")
if not isinstance(content, str) or not content.strip():
continue
history.append({"role": role, "content": content})
return history
@@ -467,11 +318,7 @@ def _inflight_text(value: Any) -> str:
def _start_inflight_turn(session: dict, text: Any) -> None:
now = time.time()
session["inflight_turn"] = {
"assistant": "",
"started_at": now,
"streaming": True,
"updated_at": now,
"user": _inflight_text(text),
"assistant": "", "started_at": now, "streaming": True, "updated_at": now, "user": _inflight_text(text),
}
@@ -489,14 +336,8 @@ def _append_inflight_delta(session: dict, delta: Any) -> None:
def _record_inflight_correction(session: dict, text: Any) -> None:
"""Record an accepted mid-turn correction on the live turn.
The correction is appended, never written over ``user``: a resuming client
must be able to rebuild BOTH bubbles. Overwriting the slot erased the
prompt that started the turn from the only snapshot resume can read, so a
reconnect (or a dev hot-reload that wipes the renderer cache) repainted the
thread with the user's original message missing.
"""
"""Record an accepted mid-turn correction on the live turn — appended, never written over ``user``,
so a resuming client can rebuild BOTH bubbles."""
correction = _inflight_text(text)
if not correction:
return
@@ -504,16 +345,10 @@ def _record_inflight_correction(session: dict, text: Any) -> None:
if not isinstance(turn, dict):
return
turn = dict(turn)
corrections = list(turn.get("corrections") or [])
corrections.append(correction)
turn["corrections"] = corrections
# Arrival-order boundary: how much assistant text had already streamed
# when this correction was accepted. Resuming clients use it to place the
# correction bubble AFTER the output the user had already seen and BEFORE
# the output it redirected (#73793) instead of above the whole reply.
offsets = list(turn.get("correction_offsets") or [])
offsets.append(len(str(turn.get("assistant") or "")))
turn["correction_offsets"] = offsets
turn["corrections"] = [*(turn.get("corrections") or []), correction]
# Arrival-order boundary (assistant chars already streamed) so resuming clients place the bubble
# between the output seen and the output redirected.
turn["correction_offsets"] = [*(turn.get("correction_offsets") or []), len(str(turn.get("assistant") or ""))]
turn["updated_at"] = time.time()
session["inflight_turn"] = turn
@@ -522,22 +357,11 @@ def _clear_inflight_turn(session: dict) -> None:
session["inflight_turn"] = None
def _fail_inflight_turn(
session: dict, error: Any, error_surface: Optional[dict] = None
) -> None:
"""Mark the in-flight turn terminal-error but keep it replayable.
Normal completion clears ``inflight_turn`` because the response is now in
canonical history. Failures are different: the terminal frame can be lost
on a WS disconnect, and the failed turn may never have been committed.
Retaining a compact error snapshot lets ``session.resume`` replay the
user's prompt, any partial assistant text, and the error itself instead of
leaving the client stranded on a spinner or hydrating from stale DB state.
The snapshot lives until the next turn starts (``_start_inflight_turn``
overwrites it) or the session closes.
Caller must hold ``session["history_lock"]``.
"""
def _fail_inflight_turn(session: dict, error: Any, error_surface: Optional[dict] = None) -> None:
"""Mark the in-flight turn terminal-error but keep it replayable: a failure's terminal frame can be
lost on WS disconnect and the turn may never have been committed, so the snapshot lets
``session.resume`` replay prompt, partial text and error instead of stranding the client on a
spinner. Lives until the next turn starts or the session closes. Caller holds history_lock."""
message = str(error) if not isinstance(error, BaseException) else (str(error) or type(error).__name__)
now = time.time()
turn = session.get("inflight_turn")
@@ -549,9 +373,7 @@ def _fail_inflight_turn(
turn["status"] = "error"
turn["recoverable"] = True
if error_surface:
# Structured {layer, code, retryable} descriptor — replayed to
# resuming clients via the resume snapshot so a reconnect renders the
# same layered error card the live frame carried.
# {layer, code, retryable} so a reconnect renders the same layered error card.
turn["error_surface"] = dict(error_surface)
else:
turn.pop("error_surface", None)
@@ -561,37 +383,17 @@ def _fail_inflight_turn(
_TURN_FAILURE_DETAIL_LIMIT = 240
# Shortest run of the submitted prompt that counts as the provider quoting it
# back. Long enough that shared boilerplate ("Invalid request for model ") does
# not trip it, short enough to catch a quoted sentence.
# Shortest prompt run counting as a quote-back: above shared boilerplate, below a quoted sentence.
_TURN_PROMPT_ECHO_WINDOW = 24
# Ceiling on the prompt we shingle. An @-expanded prompt can carry a whole
# file; the failure path must stay cheap.
# Ceiling on the prompt we shingle (an @-expanded prompt can carry a whole file).
_TURN_PROMPT_ECHO_MAX_PROMPT = 65536
def _strip_prompt_echo(message: str, prompt: Any) -> str:
"""Blank runs of the submitted prompt that ``message`` quotes back.
Secret redaction and prompt omission are different contracts, and only the
first one is pattern-based. A provider 4xx that echoes the request carries
ordinary private prose -- a paragraph about a person, a pasted file from an
``@`` reference -- that matches no credential pattern and would otherwise
reach the log intact. This closes that path directly: anything the message
shares with the prompt for ``_TURN_PROMPT_ECHO_WINDOW`` characters or more
becomes ``<prompt>``.
Shingle-set matching, not a diff: cost is linear in both strings, which
matters because this runs on every failed turn and an ``@`` reference can
make the prompt arbitrarily long. The JSON-escaped form of the prompt is
shingled too, since a provider that hands back its own request body often
hands it back escaped.
Verbatim echo is what this stops. A paraphrase, a re-encoding (base64, a
different unicode normalization) or a summary of the prompt would survive,
so this is a floor and not a proof; the guarantee it does give is that the
prompt cannot reach the record by being quoted.
"""
"""Blank runs of the submitted prompt that ``message`` quotes back: secret redaction is pattern-based
and a provider 4xx echoing the request carries private prose matching no pattern. Any run of
``_TURN_PROMPT_ECHO_WINDOW``+ chars shared with the prompt (or its JSON-escaped form) becomes
``<prompt>``. Shingle-set matching keeps it linear. Only verbatim echo is stopped — a floor."""
if not message or not prompt:
return message
needle = " ".join(str(prompt).split())[:_TURN_PROMPT_ECHO_MAX_PROMPT]
@@ -604,9 +406,7 @@ def _strip_prompt_echo(message: str, prompt: Any) -> str:
except Exception:
escaped = ""
if escaped and escaped != needle:
shingles.update(
escaped[i:i + window] for i in range(len(escaped) - window + 1)
)
shingles.update(escaped[i:i + window] for i in range(len(escaped) - window + 1))
out: list[str] = []
i = 0
n = len(message)
@@ -625,34 +425,11 @@ def _strip_prompt_echo(message: str, prompt: Any) -> str:
def _turn_failure_detail(error: Any, reason: Any = None, prompt: Any = None) -> str:
"""Render why a turn failed, for the ``tui turn finished`` bookend.
Returns ``""`` when there is nothing to say, otherwise a fragment that
already carries its own leading space, so the caller can append it to the
record unconditionally.
#86865 added the bookend to trace compression rotations, so it logs
identities and a coarse ``status`` and deliberately logs no content.
#89117 is what the missing cause costs: a report consisting of two lines
reading ``status=error error_retained=True duration=0.9s`` with no way to
tell a provider 4xx from a budget wall from a crashed finalizer. The
returned-error path -- the one a 0.9 s failure almost always takes --
emits no other log line at all; only the exception path prints to stderr,
which is why the quiet failures are the ones that get filed.
Content discipline follows #86865's, and it takes two separate steps
because it is two separate contracts. ``redact_sensitive_text`` removes
credentials, which are pattern-shaped. It does nothing about a 4xx body
that quotes the request back, because ordinary private prose is not
pattern-shaped -- so ``_strip_prompt_echo`` removes that separately, using
the submitted ``prompt`` itself as the thing to look for. The invariant the
two of them keep is: this record may gain failure classification and
provider detail, and may not newly persist the user's own content.
``prompt`` is optional so the helper stays callable from a path that has no
prompt in scope, but the turn paths always pass it; without it, only the
secret contract is enforced.
"""
"""Why a turn failed, for the ``tui turn finished`` bookend: ``""`` when nothing to say, else a
fragment with its own leading space (distinguishes a provider 4xx from a budget wall or crashed
finalizer). Two content contracts: ``redact_sensitive_text`` removes credentials;
``_strip_prompt_echo`` removes a 4xx body quoting ``prompt`` back. Invariant: this record may gain
failure classification and provider detail, never the user's own content."""
reason_text = str(reason or "").strip()
message = str(error or "").strip()
if isinstance(error, BaseException):
@@ -664,13 +441,9 @@ def _turn_failure_detail(error: Any, reason: Any = None, prompt: Any = None) ->
message = redact_sensitive_text(message, force=True)
except Exception:
# A redactor that cannot run must not be able to leak the raw
# message into the log by failing open.
message = "<unredactable>"
message = "<unredactable>" # never fail open
message = " ".join(message.split())
# After the collapse, so both sides are compared in the same shape, and
# before the truncation, so a quote that starts inside the kept prefix
# cannot survive by being cut mid-run.
# After the collapse (same shape both sides), before truncation (a quote must not survive the cut).
message = _strip_prompt_echo(message, prompt)
if len(message) > _TURN_FAILURE_DETAIL_LIMIT:
message = message[:_TURN_FAILURE_DETAIL_LIMIT] + "\u2026"
File diff suppressed because it is too large Load Diff
+239 -456
View File
@@ -7,111 +7,92 @@ method_ctx.bind_module), so they reference server.py globals bare.
from __future__ import annotations
import contextlib
from .method_ctx import HandlerRegistry, bind_module
_registry = HandlerRegistry()
def _notif_locked_sessions(fn, default):
"""Run ``fn(_sessions)`` under ``_sessions_lock``; ``default`` if that fails (the poller
thread must never crash on a lock/enumeration failure)."""
try:
with _sessions_lock:
return fn(_sessions)
except Exception:
return default
def _notif_current_keys(sid: str, session: dict) -> set:
return {str(session.get("session_key") or ""), _session_lookup_key(session, fallback=sid)}
def _notif_session_matches(s: dict, keys) -> bool:
return str(s.get("session_key") or "") in keys or _session_lookup_key(s, fallback="") in keys
def _notif_resolve_event_key(evt_key: str) -> str:
"""Resolve a compression-rotated session key to its continuation tip (or itself)."""
try:
db = _get_db()
return (db.resolve_resume_session_id(evt_key) if db is not None else evt_key) or evt_key
except Exception:
return evt_key
def _notification_event_belongs_elsewhere(sid: str, session: dict, evt: dict) -> bool:
"""True if ``evt`` is owned by a *different* live session.
Background completions carry the ``session_key`` of the session that started
the work. Async delegation completions from the desktop also carry
``origin_ui_session_id``: the live TUI tab/window that commissioned them.
Since all desktop sessions share one process-wide completion queue, each
poller must skip events it doesn't own so a detached result surfaces in the
launching session, not whichever poller happened to dequeue first.
"""
Background completions carry the ``session_key`` of the session that started the work; async
delegation completions also carry ``origin_ui_session_id`` (the live TUI tab that commissioned
them). All desktop sessions share one process-wide completion queue, so each poller must skip
events it doesn't own or a detached result surfaces in whichever poller dequeued first."""
evt_ui_sid = str(evt.get("origin_ui_session_id") or "")
if evt_ui_sid:
if evt_ui_sid == str(sid or "") and not session.get("_finalized"):
return False
try:
with _sessions_lock:
owner_live = evt_ui_sid in _sessions and not _sessions[evt_ui_sid].get("_finalized")
except Exception:
owner_live = False
if owner_live:
if _notif_locked_sessions(lambda ss: evt_ui_sid in ss and not ss[evt_ui_sid].get("_finalized"), False):
return True
# If the exact UI tab is gone, fall through to durable session_key
# routing. That avoids wrong-session delivery while still allowing a
# resumed continuation with the same durable key/lineage to claim it.
# Exact UI tab gone: fall through to durable session_key routing so a
# resumed continuation with the same key/lineage can still claim it.
evt_key = str(evt.get("session_key") or "")
if not evt_key:
return False
current_keys = {
str(session.get("session_key") or ""),
_session_lookup_key(session, fallback=sid),
}
current_keys = _notif_current_keys(sid, session)
# Compression can rotate AIAgent.session_id while the detached child is
# still running. Resolve the event's original key to its continuation tip so
# an event captured before or after compression still maps to the same live
# desktop session instead of becoming an orphan that any poller may consume.
resolved_key = evt_key
try:
db = _get_db()
if db is not None:
resolved_key = db.resolve_resume_session_id(evt_key) or evt_key
except Exception:
resolved_key = evt_key
# If the key has a live continuation, prefer that continuation over the
# compressed parent. Otherwise a stale parent tab could consume the event
# before the real current conversation sees it.
# Compression can rotate AIAgent.session_id while the detached child is still running: map
# the event's original key to its continuation tip so it reaches the live session instead of
# becoming an orphan any poller may consume. A live continuation wins over the compressed
# parent, else a stale parent tab could consume the event before the current conversation.
resolved_key = _notif_resolve_event_key(evt_key)
if resolved_key != evt_key:
if resolved_key in current_keys:
return False
try:
with _sessions_lock:
continuation_live = any(
not s.get("_finalized")
and (
str(s.get("session_key") or "") == resolved_key
or _session_lookup_key(s, fallback="") == resolved_key
)
for s in _sessions.values()
)
except Exception:
continuation_live = False
if continuation_live:
if _notif_locked_sessions(
lambda ss: any(not s.get("_finalized") and _notif_session_matches(s, {resolved_key}) for s in ss.values()),
False,
):
return True
if evt_key in current_keys:
return False
try:
with _sessions_lock:
snapshot = list(_sessions.values())
except Exception:
# If we can't safely enumerate live sessions, fail open so we don't
# crash the poller thread or drop the event.
return False
snapshot = _notif_locked_sessions(lambda ss: list(ss.values()), None)
if snapshot is None:
return False # can't enumerate: fail open rather than drop the event
return any(
s is not session
and not s.get("_finalized")
and (
str(s.get("session_key") or "") in {evt_key, resolved_key}
or _session_lookup_key(s, fallback="") in {evt_key, resolved_key}
)
for s in snapshot
)
keys = {evt_key, resolved_key}
return any(s is not session and not s.get("_finalized") and _notif_session_matches(s, keys) for s in snapshot)
def _session_owns_notification_event(sid: str, session: dict, evt: dict) -> bool:
"""True iff *this* session PROVABLY owns ``evt``.
Positive ownership — the mirror of ``_notification_event_belongs_elsewhere``
minus its orphan-adoption fallback. An event owns-matches when its
``origin_ui_session_id`` is this live session, or its ``session_key``
(raw or resolved through the compression chain) matches this session's
key/lineage. Used as the fail-closed gate for every addressed notification:
"not provably elsewhere" is NOT good enough to inject a payload into this
chat (#55578).
"""
"""True iff *this* session PROVABLY owns ``evt``: positive mirror of
``_notification_event_belongs_elsewhere`` minus its orphan-adoption fallback (UI origin is
this live session, or ``session_key`` raw/compression-resolved matches this session). Fail-
closed gate for every addressed notification — "not provably elsewhere" is NOT enough."""
if session.get("_finalized"):
return False
if str(evt.get("origin_ui_session_id") or "") == str(sid or ""):
@@ -119,63 +100,33 @@ def _session_owns_notification_event(sid: str, session: dict, evt: dict) -> bool
evt_key = str(evt.get("session_key") or "")
if not evt_key:
return False
current_keys = {
str(session.get("session_key") or ""),
_session_lookup_key(session, fallback=sid),
}
current_keys = _notif_current_keys(sid, session)
if evt_key in current_keys:
return True
try:
db = _get_db()
resolved_key = (
db.resolve_resume_session_id(evt_key) if db is not None else evt_key
) or evt_key
except Exception:
resolved_key = evt_key
return resolved_key in current_keys
return _notif_resolve_event_key(evt_key) in current_keys
def _notification_event_requires_owner(evt: dict) -> bool:
"""Whether ``evt`` must be positively claimed before TUI delivery."""
return evt.get("type") == "async_delegation" or bool(
str(evt.get("origin_ui_session_id") or "")
or str(evt.get("session_key") or "")
str(evt.get("origin_ui_session_id") or "") or str(evt.get("session_key") or "")
)
def _notification_event_dedup_key(evt: dict) -> tuple:
"""Return the UI-emission identity for a process notification event.
Completion events are terminal notifications for a background process, so
they remain one-shot per process session. Watch-match events are not
terminal: a single background process can legitimately match the same or
different patterns many times, so include event-specific content to avoid
suppressing later distinct matches from the same process.
"""
"""UI-emission identity for a process notification event. Completions are terminal (one-shot
per process session); watch events are not — one process can match patterns many times, so
include event content to avoid suppressing later distinct matches."""
evt_type = evt.get("type", "completion")
evt_sid = evt.get("session_id", "")
if evt_type == "watch_match":
return (
evt_sid,
evt_type,
evt.get("command", ""),
evt.get("pattern", ""),
evt.get("output", ""),
evt.get("suppressed", 0),
evt.get("message_id", ""),
)
return (evt_sid, evt_type, evt.get("command", ""), evt.get("pattern", ""), evt.get("output", ""),
evt.get("suppressed", 0), evt.get("message_id", ""))
if evt_type.startswith("watch_overflow_") or evt_type == "watch_disabled":
return (
evt_sid,
evt_type,
evt.get("command", ""),
evt.get("message", ""),
evt.get("suppressed", 0),
)
return (evt_sid, evt_type, evt.get("command", ""), evt.get("message", ""), evt.get("suppressed", 0))
if evt_type == "async_delegation":
# Async-delegation completions have no process session_id; without
# this the fallthrough keys every one as ("", "async_delegation")
# and the second completion's status update is suppressed forever.
# No process session_id: without this every completion keys as
# ("", "async_delegation") and the second one is suppressed forever.
return (evt.get("delegation_id", ""), evt_type)
return (evt_sid, evt_type)
@@ -183,23 +134,25 @@ def _notification_event_dedup_key(evt: dict) -> tuple:
# Mirror gateway/kanban_watchers.py TERMINAL_KINDS: claim silent kinds too so
# the cursor advances past them and they can't wedge a later completed/blocked
# event behind an unclaimed row.
_KANBAN_NOTIFY_KINDS = (
"completed", "blocked", "gave_up", "crashed", "timed_out",
"status", "archived", "unblocked",
)
_KANBAN_NOTIFY_KINDS = ("completed", "blocked", "gave_up", "crashed", "timed_out", "status", "archived", "unblocked")
_KANBAN_SILENT_KINDS = frozenset({"archived", "unblocked"})
_KANBAN_POLL_SECONDS = 5.0
_LOOP_POLL_SECONDS = 5.0
def _maybe_fire_tui_loop_tick(sid: str, session: dict) -> None:
"""Fire a due /loop wakeup for an idle TUI/Desktop/dashboard session.
def _notif_release_turn(session: dict) -> None:
with session["history_lock"]:
session["running"] = False
Called from the per-session notification poller thread on a coarse
cadence. Claims the session under history_lock (running=True) before
dispatching so a racing user prompt wins cleanly. The post-turn hook
in the turn dispatcher completes the tick.
"""
def _notif_log_failure(what: str, exc: BaseException) -> None:
print(f"[tui_gateway] {what}: {type(exc).__name__}: {exc}", file=sys.stderr)
def _maybe_fire_tui_loop_tick(sid: str, session: dict) -> None:
"""Fire a due /loop wakeup for an idle TUI/Desktop/dashboard session (per-session poller,
coarse cadence). Claims the session under history_lock (running=True) before dispatching so
a racing user prompt wins cleanly; the turn dispatcher's post-turn hook completes the tick."""
try:
from hermes_cli.loops import LoopManager, goal_blocks_loop_tick
except Exception:
@@ -209,9 +162,7 @@ def _maybe_fire_tui_loop_tick(sid: str, session: dict) -> None:
if not sid_key:
return
mgr = LoopManager(session_id=sid_key)
if not mgr.is_due():
return
if goal_blocks_loop_tick(sid_key):
if not mgr.is_due() or goal_blocks_loop_tick(sid_key):
return
with session["history_lock"]:
@@ -221,41 +172,30 @@ def _maybe_fire_tui_loop_tick(sid: str, session: dict) -> None:
wakeup = mgr.fire_tick()
if not wakeup:
with session["history_lock"]:
session["running"] = False
_notif_release_turn(session)
return
tick_no = mgr.state.ticks_fired if mgr.state else "?"
rid = f"__loop__{int(time.time() * 1000)}"
try:
_emit(
"status.update",
sid,
{"kind": "loop", "text": f"↻ /loop wakeup #{tick_no} firing…"},
)
_emit("status.update", sid, {"kind": "loop", "text": f"↻ /loop wakeup #{tick_no} firing…"})
if wakeup.lstrip().startswith("/"):
# Slash-command loop: route through the slash pipeline instead of
# the model. No model reply to evaluate — complete immediately.
with session["history_lock"]:
session["running"] = False
# Slash-command loop: route through the slash pipeline, not the
# model. No model reply to evaluate — complete immediately.
_notif_release_turn(session)
try:
parts = wakeup.lstrip()[1:].split(None, 1)
resp = _methods["command.dispatch"](
rid,
{
"name": parts[0] if parts else "",
"arg": parts[1] if len(parts) > 1 else "",
"session_id": sid,
},
{"name": parts[0] if parts else "", "arg": parts[1] if len(parts) > 1 else "", "session_id": sid},
)
payload = (resp or {}).get("result") or {}
out = str(payload.get("output") or "").strip()
if out:
_emit("status.update", sid, {"kind": "loop", "text": out})
if payload.get("type") == "send" and payload.get("message"):
# The command resolves to a prompt (skill command etc.) —
# run it as a normal turn; the post-turn hook completes
# the tick.
# Command resolves to a prompt (skill command etc.) — run it
# as a normal turn; the post-turn hook completes the tick.
with session["history_lock"]:
if session.get("running"):
mgr.abandon_tick()
@@ -273,26 +213,15 @@ def _maybe_fire_tui_loop_tick(sid: str, session: dict) -> None:
_emit("message.start", sid)
_run_prompt_submit(rid, sid, session, wakeup)
except Exception as exc:
print(
f"[tui_gateway] loop wakeup dispatch failed: "
f"{type(exc).__name__}: {exc}",
file=sys.stderr,
)
with session["history_lock"]:
session["running"] = False
try:
_notif_log_failure("loop wakeup dispatch failed", exc)
_notif_release_turn(session)
with contextlib.suppress(Exception):
mgr.abandon_tick()
except Exception:
pass
def _format_kanban_event_text(sub: dict, task, ev, board_slug: str) -> Optional[str]:
"""Single-line notification text for one kanban event.
Wording mirrors the gateway notifier (gateway/kanban_watchers.py) so a
task completion reads the same in the TUI as it does on Telegram.
Returns None for kinds that are claimed but intentionally silent.
"""
"""Single-line notification text for one kanban event; wording mirrors
gateway/kanban_watchers.py so it reads the same as on Telegram. None for silent kinds."""
kind = getattr(ev, "kind", "")
if not kind or kind in _KANBAN_SILENT_KINDS:
return None
@@ -321,11 +250,10 @@ def _format_kanban_event_text(sub: dict, task, ev, board_slug: str) -> Optional[
if kind == "crashed":
return f"✖ {board_tag}{tag}Kanban {task_id} worker crashed (pid gone); dispatcher will retry"
if kind == "timed_out":
limit = 0
try:
limit = int(payload.get("limit_seconds") or 0)
except (TypeError, ValueError):
pass
limit = 0
return f"⏱ {board_tag}{tag}Kanban {task_id} timed out (max_runtime={limit}s); will retry"
if kind == "status":
return f"🔄 {board_tag}{tag}Kanban {task_id} → {payload.get('status') or ''}"
@@ -335,17 +263,11 @@ def _format_kanban_event_text(sub: dict, task, ev, board_slug: str) -> Optional[
def _collect_kanban_notifications(session: dict) -> list:
"""Claim unseen terminal kanban events for this TUI session's subscriptions.
``kanban_create`` auto-subscribes TUI/desktop sessions with
``platform="tui"`` and ``chat_id=HERMES_SESSION_KEY`` (see
tools/kanban_tools.py ``_maybe_auto_subscribe``). The gateway notifier
can't deliver those — there is no "tui" messaging adapter — so this
poller is the delivery path for them (issue #59890). Uses the same
atomic cursor-claim (``claim_unseen_events_for_sub``) as the gateway
notifier, so a subscription is delivered exactly once even if a gateway
and a TUI poll the same board DB.
Returns the list of formatted notification texts (may be empty).
"""
``kanban_create`` auto-subscribes TUI/desktop sessions with ``platform="tui"`` and
``chat_id=HERMES_SESSION_KEY``; there is no "tui" messaging adapter, so this poller is the
delivery path. Same atomic cursor-claim (``claim_unseen_events_for_sub``) as the gateway
notifier, so a sub is delivered exactly once even if a gateway and a TUI poll the same board
DB. Returns formatted notification texts (may be empty)."""
session_key = str(session.get("session_key") or "")
if not session_key or session.get("_finalized"):
return []
@@ -362,35 +284,25 @@ def _collect_kanban_notifications(session: dict) -> list:
except Exception:
return []
# Poll each resolved DB path once — multiple slugs can point at the same
# DB when HERMES_KANBAN_DB pins the board path (same guard as the gateway
# notifier).
# DB when HERMES_KANBAN_DB pins the board path (same guard as the gateway).
seen_db_paths: set = set()
for board_meta in boards:
slug = (board_meta or {}).get("slug") or _kb.DEFAULT_BOARD
db_path = (board_meta or {}).get("db_path")
try:
resolved = (
str(Path(db_path).expanduser().resolve())
if db_path else str(_kb.kanban_db_path(slug).resolve())
)
resolved = str(Path(db_path).expanduser().resolve() if db_path else _kb.kanban_db_path(slug).resolve())
except Exception:
resolved = f"slug:{slug}"
if resolved in seen_db_paths:
continue
seen_db_paths.add(resolved)
# A poller runs per live TUI/Desktop session. Avoid opening this board
# writable unless it has a subscription owned by this exact session;
# subscriptions for gateways or other sessions are not actionable here.
# One poller per live session: don't open this board writable unless it
# has a subscription owned by this exact session. If the read-only probe
# fails (locked/corrupt DB), preserve delivery and fall through.
try:
if _kb.count_notify_subs(
board=slug,
platform="tui",
chat_id=session_key,
) == 0:
if _kb.count_notify_subs(board=slug, platform="tui", chat_id=session_key) == 0:
continue
except Exception:
# Preserve delivery if the read-only probe cannot inspect a
# locked, corrupt, or otherwise unusual database.
pass
try:
conn = _kb.connect(board=slug)
@@ -402,18 +314,13 @@ def _collect_kanban_notifications(session: dict) -> list:
except Exception:
continue
for sub in subs:
if (sub.get("platform") or "").lower() != "tui":
if (sub.get("platform") or "").lower() != "tui" or sub.get("chat_id") != session_key:
continue
if sub.get("chat_id") != session_key:
continue
_old, _new, events = _kb.claim_unseen_events_for_sub(
conn,
task_id=sub["task_id"],
platform=sub["platform"],
chat_id=sub["chat_id"],
sub_ident = dict(
task_id=sub["task_id"], platform=sub["platform"], chat_id=sub["chat_id"],
thread_id=sub.get("thread_id") or "",
kinds=_KANBAN_NOTIFY_KINDS,
)
_old, _new, events = _kb.claim_unseen_events_for_sub(conn, kinds=_KANBAN_NOTIFY_KINDS, **sub_ident)
if not events:
continue
task = _kb.get_task(conn, sub["task_id"])
@@ -421,157 +328,142 @@ def _collect_kanban_notifications(session: dict) -> list:
text = _format_kanban_event_text(sub, task, ev, slug)
if text:
texts.append(text)
# Unsubscribe only on archive. ``done`` is reversible in
# review/controller flows, so retaining the subscription lets
# a later reopen notify the same originating TUI/Desktop
# session. The claimed cursor prevents historical replay.
# Unsubscribe only on archive: ``done`` is reversible in review/controller flows,
# so keeping the sub lets a later reopen notify the same session. The claimed
# cursor prevents replay.
if task and getattr(task, "status", "") == "archived":
try:
_kb.remove_notify_sub(
conn,
task_id=sub["task_id"],
platform=sub["platform"],
chat_id=sub["chat_id"],
thread_id=sub.get("thread_id") or "",
)
except Exception:
pass
with contextlib.suppress(Exception):
_kb.remove_notify_sub(conn, **sub_ident)
finally:
conn.close()
return texts
def _notification_poller_loop(
stop_event: threading.Event, sid: str, session: dict
) -> None:
"""Poll completion_queue and dispatch notifications autonomously.
def _notif_poll_kanban(sid: str, session: dict) -> None:
"""One kanban poll: emit new texts, buffer them, and run the buffered batch as a turn if idle.
Events are cursor-claimed (never re-queued), so they are buffered until the session is idle
instead of dropping the agent turn."""
try:
_kanban_texts = _collect_kanban_notifications(session)
except Exception as _kb_exc:
_notif_log_failure("kanban notification poll failed", _kb_exc)
_kanban_texts = []
if _kanban_texts:
for _kb_text in _kanban_texts:
_emit("status.update", sid, {"kind": "process", "text": _kb_text})
session.setdefault("_kanban_pending", []).extend(_kanban_texts)
_pending = session.get("_kanban_pending") or []
if not _pending:
return
_batch: list = []
with session["history_lock"]:
if not session.get("running"):
session["running"] = True
_batch = list(_pending)
session["_kanban_pending"] = []
if _batch:
rid = f"__notif__{int(time.time() * 1000)}"
try:
_emit("message.start", sid)
_run_prompt_submit(rid, sid, session, "\n".join(_batch))
except Exception as exc:
_notif_log_failure("kanban notification dispatch failed", exc)
_notif_release_turn(session)
Runs in a daemon thread started by _init_session(). Emits a
status.update (kind=process) for user visibility, then chains an
agent turn via _run_prompt_submit if the session is idle.
The completion_queue is process-global. In multi-session Desktop each
poller requeues events owned by another live session and drops addressed
events whose owner is gone; ownerless legacy notifications remain global.
def _notif_render_event(sid: str, evt: dict, emitted: set, process_registry, format_process_notification) -> Optional[str]:
"""Format ``evt`` and emit its status.update once; None means skip the event (consumed
completion or unformattable). Re-queued completions would otherwise re-emit every 0.5s while
the session is busy, while distinct watch_match events from one process must stay visible."""
if evt.get("type") == "completion" and process_registry.is_completion_consumed(evt.get("session_id", "")):
return None
text = format_process_notification(evt)
if not text:
return None
dedup_key = _notification_event_dedup_key(evt)
if dedup_key not in emitted:
_emit("status.update", sid, {"kind": "process", "text": text})
emitted.add(dedup_key)
return text
Also polls ``kanban_notify_subs`` every ``_KANBAN_POLL_SECONDS`` for this
session's TUI kanban subscriptions and delivers terminal task events the
same way (status.update + agent turn) — the delivery path
tools/kanban_tools.py documents for platform="tui" rows (issue #59890).
"""
def _notif_dispatch_event(sid: str, session: dict, evt: dict, text: str) -> None:
"""Run the claimed (running=True) agent turn for one notification event."""
from tools.async_delegation import claim_event_delivery, complete_event_delivery, release_event_delivery
rid = f"__notif__{int(time.time() * 1000)}"
claim = claim_event_delivery(evt, "tui-poller")
if claim is None:
return
try:
_emit("message.start", sid)
if evt.get("type") == "async_delegation":
_run_prompt_submit(
rid, sid, session, text, display_kind="async_delegation_complete",
display_metadata=_async_delegation_display_metadata(evt),
)
else:
_run_prompt_submit(rid, sid, session, text)
complete_event_delivery(evt, claim)
except Exception as exc:
release_event_delivery(evt, claim)
_notif_log_failure("notification poller dispatch failed", exc)
_notif_release_turn(session)
def _notification_poller_loop(stop_event: threading.Event, sid: str, session: dict) -> None:
"""Poll completion_queue and dispatch notifications autonomously (daemon thread started by
_init_session()): emit a status.update (kind=process), then chain an agent turn via
_run_prompt_submit if the session is idle. The queue is process-global: each poller requeues
events owned by another live session and drops addressed events whose owner is gone;
ownerless legacy notifications remain global. Also polls ``kanban_notify_subs`` every
``_KANBAN_POLL_SECONDS`` — the delivery path for platform="tui" rows."""
from tools.process_registry import process_registry, format_process_notification
_emitted = set() # dedup re-queued events so same completion isn't emitted 50 times while session is busy
_emitted = set() # dedup re-queued events so one completion isn't emitted 50 times while busy
_last_kanban_poll = 0.0
_last_loop_poll = 0.0
while not stop_event.is_set() and not session.get("_finalized"):
_now = time.monotonic()
# ── /loop wakeup driver ──────────────────────────────────────
# Fire a due /loop tick for THIS session while it's idle. Same
# claim-under-lock pattern as the kanban dispatch below. Active
# non-parked /goal owns the idle boundary and defers the tick.
# /loop wakeup driver: fire a due tick for THIS session while idle (same claim-under-lock
# as kanban dispatch). An active non-parked /goal owns the idle boundary and defers it.
if _now - _last_loop_poll >= _LOOP_POLL_SECONDS:
_last_loop_poll = _now
try:
_maybe_fire_tui_loop_tick(sid, session)
except Exception as _loop_exc:
print(
f"[tui_gateway] loop wakeup poll failed: "
f"{type(_loop_exc).__name__}: {_loop_exc}",
file=sys.stderr,
)
_notif_log_failure("loop wakeup poll failed", _loop_exc)
if _now - _last_kanban_poll >= _KANBAN_POLL_SECONDS:
_last_kanban_poll = _now
try:
_kanban_texts = _collect_kanban_notifications(session)
except Exception as _kb_exc:
print(
f"[tui_gateway] kanban notification poll failed: "
f"{type(_kb_exc).__name__}: {_kb_exc}",
file=sys.stderr,
)
_kanban_texts = []
if _kanban_texts:
for _kb_text in _kanban_texts:
_emit("status.update", sid, {"kind": "process", "text": _kb_text})
# Events are cursor-claimed (never re-queued), so buffer them
# until the session is idle instead of dropping the agent turn.
session.setdefault("_kanban_pending", []).extend(_kanban_texts)
_pending = session.get("_kanban_pending") or []
if _pending:
_batch: list = []
with session["history_lock"]:
if not session.get("running"):
session["running"] = True
_batch = list(_pending)
session["_kanban_pending"] = []
if _batch:
rid = f"__notif__{int(time.time() * 1000)}"
try:
_emit("message.start", sid)
_run_prompt_submit(rid, sid, session, "\n".join(_batch))
except Exception as exc:
print(
f"[tui_gateway] kanban notification dispatch failed: "
f"{type(exc).__name__}: {exc}",
file=sys.stderr,
)
with session["history_lock"]:
session["running"] = False
_notif_poll_kanban(sid, session)
try:
evt = process_registry.completion_queue.get(timeout=0.5)
except Exception:
continue
# Multiple desktop sessions share this one process-wide queue. Only
# consume events that belong to *this* session — otherwise a background
# process started in session A would surface its completion in whichever
# session's poller happened to wake first (Ben's "reported in a
# different session" bug). Leave foreign events for their owner.
# Leave foreign events for their owner — otherwise a process started in
# session A surfaces its completion in whichever poller wakes first.
if _notification_event_belongs_elsewhere(sid, session, evt):
process_registry.completion_queue.put(evt)
time.sleep(0.1)
continue
# What reaches here is not owned by another LIVE session. Addressed
# events still require positive proof before injection: exact UI origin,
# direct durable key, or compression lineage. If none proves ownership,
# the event is orphaned and must not be adopted by this chat. Truly
# ownerless ordinary notifications retain legacy global delivery.
requires_owner = _notification_event_requires_owner(evt)
if requires_owner and not _session_owns_notification_event(sid, session, evt):
log = (
logger.warning
if evt.get("type") == "async_delegation"
else logger.debug
)
# Not owned by another LIVE session, but addressed events still need positive proof
# (exact UI origin, direct durable key, or compression lineage) — an orphan must not be
# adopted by this chat. Truly ownerless ordinary notifications keep legacy global delivery.
if _notification_event_requires_owner(evt) and not _session_owns_notification_event(sid, session, evt):
log = logger.warning if evt.get("type") == "async_delegation" else logger.debug
log(
"Dropping unowned %s notification (origin=%r key=%r) instead "
"of delivering to session %s",
evt.get("type", "completion"),
str(evt.get("origin_ui_session_id") or ""),
str(evt.get("session_key") or ""),
sid,
"Dropping unowned %s notification (origin=%r key=%r) instead of delivering to session %s",
evt.get("type", "completion"), str(evt.get("origin_ui_session_id") or ""),
str(evt.get("session_key") or ""), sid,
)
continue
_evt_sid = evt.get("session_id", "")
if evt.get("type") == "completion" and process_registry.is_completion_consumed(_evt_sid):
continue
text = format_process_notification(evt)
text = _notif_render_event(sid, evt, _emitted, process_registry, format_process_notification)
if not text:
continue
# Only emit the same notification identity to TUI once — re-queued
# completions get re-emitted every 0.5s otherwise when session is busy,
# while distinct watch_match events from the same process must remain
# visible independently.
_dedup_key = _notification_event_dedup_key(evt)
if _dedup_key not in _emitted:
_emit("status.update", sid, {"kind": "process", "text": text})
_emitted.add(_dedup_key)
_requeued = False
with session["history_lock"]:
if session.get("running"):
@@ -580,47 +472,16 @@ def _notification_poller_loop(
else:
session["running"] = True
if _requeued:
# Back off before re-polling: the re-queued event keeps the queue
# non-empty, so without a sleep this loop spins at full speed
# (100% CPU, GIL churn) for as long as the session stays busy.
# Back off: the re-queued event keeps the queue non-empty, so
# without a sleep this loop spins at 100% CPU while busy.
time.sleep(0.25)
continue
rid = f"__notif__{int(time.time() * 1000)}"
from tools.async_delegation import (
claim_event_delivery, complete_event_delivery, release_event_delivery,
)
_claim = claim_event_delivery(evt, "tui-poller")
if _claim is None:
continue
try:
_emit("message.start", sid)
if evt.get("type") == "async_delegation":
_run_prompt_submit(
rid,
sid,
session,
text,
display_kind="async_delegation_complete",
display_metadata=_async_delegation_display_metadata(evt),
)
else:
_run_prompt_submit(rid, sid, session, text)
complete_event_delivery(evt, _claim)
except Exception as exc:
release_event_delivery(evt, _claim)
print(
f"[tui_gateway] notification poller dispatch failed: "
f"{type(exc).__name__}: {exc}",
file=sys.stderr,
)
with session["history_lock"]:
session["running"] = False
_notif_dispatch_event(sid, session, evt, text)
# Drain any remaining events after stop signal (process all pending
# before exiting so nothing is lost on shutdown). Events owned by other
# live sessions are set aside and re-queued so their poller still sees them.
# Orphaned events (owner gone) are dropped — same guard as the main loop.
# Drain remaining events after the stop signal so nothing is lost on shutdown. Other live
# sessions' events are set aside and re-queued; orphaned events (owner gone) are dropped —
# same guard as the main loop, except orphaned delegation payloads are deferred for a resume.
deferred: list = []
while not process_registry.completion_queue.empty():
try:
@@ -630,70 +491,27 @@ def _notification_poller_loop(
if _notification_event_belongs_elsewhere(sid, session, evt):
deferred.append(evt)
continue
# Same positive-proof rule as the live loop. Preserve the existing
# shutdown behavior for orphaned delegation payloads by deferring them
# for a later resume; ordinary addressed orphans are dropped.
requires_owner = _notification_event_requires_owner(evt)
if requires_owner and not _session_owns_notification_event(sid, session, evt):
if _notification_event_requires_owner(evt) and not _session_owns_notification_event(sid, session, evt):
if evt.get("type") == "async_delegation":
deferred.append(evt)
else:
logger.debug(
"Dropping unowned %s notification during shutdown drain "
"(origin=%r key=%r)",
evt.get("type", "completion"),
str(evt.get("origin_ui_session_id") or ""),
"Dropping unowned %s notification during shutdown drain (origin=%r key=%r)",
evt.get("type", "completion"), str(evt.get("origin_ui_session_id") or ""),
str(evt.get("session_key") or ""),
)
continue
_evt_sid = evt.get("session_id", "")
if evt.get("type") == "completion" and process_registry.is_completion_consumed(_evt_sid):
continue
text = format_process_notification(evt)
text = _notif_render_event(sid, evt, _emitted, process_registry, format_process_notification)
if not text:
continue
_dedup_key = _notification_event_dedup_key(evt)
if _dedup_key not in _emitted:
_emit("status.update", sid, {"kind": "process", "text": text})
_emitted.add(_dedup_key)
with session["history_lock"]:
if session.get("running"):
process_registry.completion_queue.put(evt)
break
session["running"] = True
rid = f"__notif__{int(time.time() * 1000)}"
from tools.async_delegation import (
claim_event_delivery, complete_event_delivery, release_event_delivery,
)
_claim = claim_event_delivery(evt, "tui-poller")
if _claim is None:
continue
try:
_emit("message.start", sid)
if evt.get("type") == "async_delegation":
_run_prompt_submit(
rid,
sid,
session,
text,
display_kind="async_delegation_complete",
display_metadata=_async_delegation_display_metadata(evt),
)
else:
_run_prompt_submit(rid, sid, session, text)
complete_event_delivery(evt, _claim)
except Exception as exc:
release_event_delivery(evt, _claim)
print(
f"[tui_gateway] notification poller dispatch failed: "
f"{type(exc).__name__}: {exc}",
file=sys.stderr,
)
with session["history_lock"]:
session["running"] = False
_notif_dispatch_event(sid, session, evt, text)
# Hand any other sessions' events back to the shared queue.
for evt in deferred:
@@ -703,23 +521,13 @@ def _notification_poller_loop(
def _async_delegation_display_metadata(evt: dict) -> dict:
"""Build display-only metadata before the completion event is formatted."""
raw_results = evt.get("results")
results: list[dict] = [
result for result in raw_results if isinstance(result, dict)
] if isinstance(raw_results, list) else []
results: list[dict] = [r for r in raw_results if isinstance(r, dict)] if isinstance(raw_results, list) else []
task_count = len(results) or 1
completed_count = sum(
1 for result in results
if result.get("status") in {"completed", "success"}
)
failed_count = sum(
1 for result in results
if result.get("status") in {"failed", "error"}
)
completed_count = sum(1 for r in results if r.get("status") in {"completed", "success"})
failed_count = sum(1 for r in results if r.get("status") in {"failed", "error"})
metadata = {
"delegation_id": str(evt.get("delegation_id") or ""),
"task_count": task_count,
"completed_count": completed_count or task_count - failed_count,
"failed_count": failed_count,
"delegation_id": str(evt.get("delegation_id") or ""), "task_count": task_count,
"completed_count": completed_count or task_count - failed_count, "failed_count": failed_count,
}
duration = evt.get("total_duration_seconds") or evt.get("duration_seconds")
if isinstance(duration, (int, float)):
@@ -728,14 +536,10 @@ def _async_delegation_display_metadata(evt: dict) -> dict:
def _wire_agent_terminal_output() -> None:
"""Idempotently route background-process output (and tab-close requests) to
the desktop, keyed by process id. Read-only agent terminal tabs stream
`agent.terminal.output` chunks live instead of polling the output tail, and
`process_registry.request_close_terminal` emits `terminal.close` so the agent
can drop a tab without killing the process. Events are routed to the window
that owns the process (its gateway session); `_emit`/`write_json` is
`_stdout_lock`-guarded, so calling it from the registry's reader threads is
safe."""
"""Idempotently route background-process output (`agent.terminal.output` chunks) and
`process_registry.request_close_terminal` (`terminal.close`, drops a tab without killing the
process) to the window owning the process (its gateway session), keyed by process id.
`_emit` is `_stdout_lock`-guarded, so the registry's reader threads may call it."""
from tools.process_registry import process_registry
has_output_sink = getattr(process_registry, "on_output", None) is not None
@@ -754,11 +558,7 @@ def _wire_agent_terminal_output() -> None:
return ""
def _emit_agent_terminal_output(session, chunk):
_emit(
"agent.terminal.output",
_owner_sid_for_process(session),
{"process_id": session.id, "chunk": chunk},
)
_emit("agent.terminal.output", _owner_sid_for_process(session), {"process_id": session.id, "chunk": chunk})
def _emit_agent_terminal_close(session, process_id):
# session may be None (process already finished/pruned) — the tab can
@@ -777,11 +577,8 @@ _desktop_ui_wired = False
def _wire_desktop_ui() -> None:
"""Bridge desktop-only tools (open_preview, close_preview, focus_pane) to renderer events.
Idempotent. The tool hands back the turn's ``HERMES_UI_SESSION_ID`` as
``sid`` so the event routes to the window that asked (``_emit`` /
``write_json`` is ``_stdout_lock``-guarded, so calling it from the tool's
thread is safe)."""
Idempotent. The tool hands back the turn's ``HERMES_UI_SESSION_ID`` as ``sid`` so the event
routes to the window that asked (``_emit`` is ``_stdout_lock``-guarded; tool thread may call it)."""
global _desktop_ui_wired
if _desktop_ui_wired:
return
@@ -794,9 +591,9 @@ def _wire_desktop_ui() -> None:
_desktop_ui_wired = True
# (stop_event, thread) for every poller ever started in this process.
# Pruned of dead threads on each spawn; consumed by test teardowns to reap
# leaked pollers (see _start_notification_poller).
# (stop_event, thread) for every poller started in this process, pruned of dead threads on each
# spawn. Test teardowns reap leaked pollers through it: an unjoined poller steals events off the
# process-global completion_queue mid-assertion in a LATER test.
_notification_pollers: list = []
@@ -805,21 +602,11 @@ def _start_notification_poller(sid: str, session: dict) -> threading.Event:
_wire_agent_terminal_output()
_wire_desktop_ui()
stop = threading.Event()
# Thread name is greppable for debuggers/test teardowns.
t = threading.Thread(
target=_notification_poller_loop,
args=(stop, sid, session),
daemon=True,
# Stable, greppable name for debuggers and test teardowns.
name=f"tui-notif-poller-{sid}",
target=_notification_poller_loop, args=(stop, sid, session), daemon=True, name=f"tui-notif-poller-{sid}"
)
# Registry of (stop, thread) pairs so test teardowns can reap pollers
# leaked by session.init/create tests — an unjoined poller steals
# events off the process-global completion_queue mid-assertion in a
# LATER test (flaky test_run_prompt_submit_requeues_all_unstarted_...).
# Bounded: entries for dead threads are pruned on each spawn.
_notification_pollers[:] = [
(s, th) for (s, th) in _notification_pollers if th.is_alive()
]
_notification_pollers[:] = [(s, th) for (s, th) in _notification_pollers if th.is_alive()]
_notification_pollers.append((stop, t))
t.start()
return stop
@@ -835,14 +622,10 @@ def _hud_surface_note(session: dict) -> str:
def _prepend_note(run_message: Any, note: str) -> Any:
"""Prefix a per-turn note onto the MODEL INPUT, leaving the prompt alone.
Everything the model needs to know about the turn but the user did not
type — an interrupted reply, reactions, the surface they typed into —
arrives this way. persist_user_message keeps the clean prompt, so no
scaffolding reaches the transcript, and annotating the NEW turn never
rewrites an already-sent message, so the cached prefix survives.
"""
"""Prefix a per-turn note onto the MODEL INPUT, leaving the prompt alone. Everything the model
must know about the turn that the user did not type (interrupted reply, reactions, surface)
arrives this way; persist_user_message keeps the clean prompt, so no scaffolding reaches the
transcript, and annotating the NEW turn never rewrites a sent message — cached prefix survives."""
if not note:
return run_message
if isinstance(run_message, str):
+123 -243
View File
@@ -6,6 +6,7 @@ method_ctx.bind_module), so they reference server.py globals bare.
from __future__ import annotations
import contextlib
import threading
from tui_gateway._env import env_float
@@ -15,31 +16,18 @@ from .method_ctx import HandlerRegistry, bind_module
_registry = HandlerRegistry()
# Knobs (_SESSION_TTL_S, _REAPER_SCAN_S, _EXIT_FLUSH_BUDGET_S,
# _INCREMENTAL_FLUSH_INTERVAL_S) live in server.py next to _start_idle_reaper.
# Knobs (_SESSION_TTL_S, _REAPER_SCAN_S, _EXIT_FLUSH_BUDGET_S, _INCREMENTAL_FLUSH_INTERVAL_S) live in server.py.
# ── Flush-on-kill + periodic incremental flush (#94724 item 2) ───────────
# A `hermes serve` killed mid-update used to lose every un-flushed in-memory
# session: the next RPC failed with "session-scoped RPC rejected: not in
# memory (detached/reaped runtime)" and NO store held the transcript. #95576
# made serves survive *future* updates; this closes the kill path itself:
# (a) SIGTERM/SIGINT run a bounded, best-effort flush of in-memory session
# transcripts to state.db BEFORE the normal shutdown path, chained to
# whatever handler was installed before (uvicorn's included);
# (b) the idle-reaper scan piggybacks a periodic incremental flush so even
# a SIGKILL loses at most one flush interval.
# ── Flush-on-kill + periodic incremental flush ───────────────────────────
# (a) SIGTERM/SIGINT run a bounded flush to state.db BEFORE normal shutdown, chained to the prior
# handler; (b) the idle-reaper scan piggybacks an incremental flush so a SIGKILL loses at most one interval.
def _flush_session_messages(session: dict | None) -> bool:
"""Best-effort durable flush of one session's in-memory transcript.
Rides ``agent._persist_session`` — the same marker-deduped persist
contract ``_finalize_session`` uses (#13121) — so repeated calls only
write genuinely-unflushed messages and never duplicate durable rows.
"""
if not session:
return False
agent = session.get("agent")
"""Best-effort durable flush of one session's transcript via ``agent._persist_session``
(same marker-deduped contract as ``_finalize_session``): repeated calls only write
genuinely-unflushed messages, never duplicate rows."""
agent = session.get("agent") if session else None
if agent is None or not hasattr(agent, "_persist_session"):
return False
snapshot = getattr(agent, "_session_messages", None)
@@ -53,25 +41,22 @@ def _flush_session_messages(session: dict | None) -> bool:
return False
def _flush_dirty_sessions(now: float | None = None) -> int:
"""Periodic incremental flush, driven by the idle-reaper scan.
def _reaper_session_snapshot() -> list:
with _sessions_lock:
return list(_sessions.values())
Skips ``running`` sessions: the turn thread owns mid-turn persistence
(it already flushes at every persist point) and
``_drop_trailing_empty_response_scaffolding`` mutates the live message
list, so racing an in-flight turn from the reaper thread is never safe.
Idle/detached sessions — precisely the ones a kill strands — are flushed
at most once per ``_INCREMENTAL_FLUSH_INTERVAL_S``. ``now`` is injectable
for tests (monotonic clock).
"""
def _flush_dirty_sessions(now: float | None = None) -> int:
"""Periodic incremental flush, driven by the idle-reaper scan. Skips ``running``
sessions: the turn thread owns mid-turn persistence and mutates the live message list,
so racing it from the reaper thread is never safe. Idle sessions flush at most once per
``_INCREMENTAL_FLUSH_INTERVAL_S``; ``now`` (monotonic) is injectable for tests."""
if _INCREMENTAL_FLUSH_INTERVAL_S <= 0:
return 0
if now is None:
now = time.monotonic()
with _sessions_lock:
sessions = list(_sessions.values())
flushed = 0
for session in sessions:
for session in _reaper_session_snapshot():
if not isinstance(session, dict) or session.get("running"):
continue
last = float(session.get("_last_incremental_flush") or 0.0)
@@ -84,13 +69,10 @@ def _flush_dirty_sessions(now: float | None = None) -> int:
def _flush_sessions_before_exit(budget_s: float | None = None) -> int:
"""Bounded flush of ALL in-memory sessions on the way out.
Runs on a daemon worker joined with the budget so a hung SQLite write
can never block exit longer than ``HERMES_TUI_EXIT_FLUSH_BUDGET_S``
(default 5s). Running sessions are included — the process is dying, so
a best-effort partial transcript beats guaranteed loss.
"""
"""Bounded flush of ALL in-memory sessions on the way out. Runs on a daemon worker
joined with the budget so a hung SQLite write can't block exit past
``HERMES_TUI_EXIT_FLUSH_BUDGET_S`` (default 5s). Running sessions are included — the
process is dying, so a partial transcript beats guaranteed loss."""
budget = _EXIT_FLUSH_BUDGET_S if budget_s is None else max(0.0, budget_s)
if budget <= 0:
return 0
@@ -98,9 +80,7 @@ def _flush_sessions_before_exit(budget_s: float | None = None) -> int:
def _run() -> None:
deadline = time.monotonic() + budget
with _sessions_lock:
sessions = list(_sessions.values())
for session in sessions:
for session in _reaper_session_snapshot():
if time.monotonic() >= deadline:
break
if _flush_session_messages(session):
@@ -117,16 +97,11 @@ _exit_flush_handlers_installed = False
def _handle_exit_flush_signal(signum, frame) -> None:
"""Flush in-memory sessions, then hand off to the prior handler.
Chaining preserves the pre-existing signal story (uvicorn's graceful
shutdown, a supervisor's handler, or the default terminate disposition)
— this handler only *prepends* a bounded durable flush.
"""
try:
"""Flush in-memory sessions, then hand off to the prior handler (uvicorn's graceful
shutdown, a supervisor's handler, or the default disposition) — this only *prepends*
a bounded durable flush."""
with contextlib.suppress(Exception):
_flush_sessions_before_exit()
except Exception:
pass
import signal as _signal
prev = _exit_flush_prev_handlers.get(signum)
@@ -135,8 +110,8 @@ def _handle_exit_flush_signal(signum, frame) -> None:
return
if prev is _signal.SIG_IGN:
return
# Default disposition: restore it and re-raise so the process still dies
# with the correct signal (exit status visible to supervisors).
# Default disposition: restore it and re-raise so the process dies with the correct
# signal (exit status visible to supervisors).
try:
_signal.signal(signum, _signal.SIG_DFL)
os.kill(os.getpid(), signum)
@@ -145,14 +120,10 @@ def _handle_exit_flush_signal(signum, frame) -> None:
def install_exit_flush_signal_handlers() -> bool:
"""Install chaining SIGTERM/SIGINT flush handlers (main thread only).
Called by ``hermes serve`` / dashboard startup before uvicorn takes over
signals: uvicorn's ``capture_signals()`` saves these as the "original"
handlers and restores + re-raises into them after its graceful shutdown,
so the flush also covers terminations outside uvicorn's serve window.
Idempotent; returns False off the main thread or when installation fails.
"""
"""Install chaining SIGTERM/SIGINT flush handlers (main thread only). Called before
uvicorn takes over signals: its ``capture_signals()`` saves these as the "original"
handlers and re-raises into them after graceful shutdown, so the flush also covers
terminations outside uvicorn's serve window. Idempotent; False off-main-thread/on failure."""
global _exit_flush_handlers_installed
if _exit_flush_handlers_installed:
return True
@@ -174,26 +145,25 @@ def install_exit_flush_signal_handlers() -> bool:
def _transport_is_dead(transport) -> bool:
# _detached_ws_transport is the post-WS-disconnect drop sentinel; a session
# parked on it has no live client. _stdio_transport is the REAL transport
# for a standalone `hermes --tui`, so it must NOT count as dead here (doing
# so let the idle reaper evict healthy standalone TUI sessions).
if transport is _detached_ws_transport:
return True
return getattr(transport, "_closed", None) is True
# _detached_ws_transport is the post-disconnect drop sentinel. _stdio_transport is the
# REAL transport for standalone `hermes --tui` and must NOT count as dead.
return transport is _detached_ws_transport or getattr(transport, "_closed", None) is True
def _reaper_session_is_detached_idle(sid: str, session: dict) -> bool:
"""Shared hard exemptions for both reapers: never evict a session mid-turn, awaiting
input, still building, owning live delegated work, or on a live transport. Lazy watch
sessions never start a build, so their unset agent_ready must not make them immortal."""
if session.get("running") or _session_pending_kind(sid) or _session_has_active_delegations(sid, session):
return False
ready = session.get("agent_ready")
if ready is not None and not ready.is_set() and not session.get("lazy"):
return False
return _transport_is_dead(session.get("transport"))
def _session_is_evictable(sid: str, session: dict, now: float) -> bool:
if session.get("running") or _session_pending_kind(sid):
return False
if _session_has_active_delegations(sid, session):
return False
ready = session.get("agent_ready")
# Lazy watch sessions (subagent spectator windows) never start a build,
# so their forever-unset agent_ready must not make them immortal.
if ready is not None and not ready.is_set() and not session.get("lazy"):
return False
if not _transport_is_dead(session.get("transport")):
if not _reaper_session_is_detached_idle(sid, session):
return False
last_active = float(session.get("last_active") or 0.0)
created_at = float(session.get("created_at") or 0.0)
@@ -202,10 +172,7 @@ def _session_is_evictable(sid: str, session: dict, now: float) -> bool:
def _reap_idle_sessions() -> None:
now = time.time()
# Piggyback the periodic incremental flush on the existing reaper tick
# (#94724 item 2) — no new timer subsystem. Even a SIGKILL then loses at
# most one flush interval of un-persisted messages.
try:
try: # piggyback the incremental flush on the reaper tick — no new timer subsystem
_flush_dirty_sessions()
except Exception:
logger.debug("periodic incremental session flush failed", exc_info=True)
@@ -215,27 +182,19 @@ def _reap_idle_sessions() -> None:
_close_session_by_id(
sid,
end_reason="idle_timeout",
predicate=lambda session, victim_sid=sid: _session_is_evictable(
victim_sid, session, time.time()
),
predicate=lambda session, vs=sid: _session_is_evictable(vs, session, time.time()),
)
_enforce_session_cap()
_reclaim_orphaned_leases()
# Periodic heap release for long-lived gateway processes. Even when no
# session is reaped, Python's generational GC rarely runs gen2 collection
# under steady-state allocation, and glibc retains freed pages as RSS.
# Calling trim_memory here ensures every reaper scan (default every 5 min)
# returns releasable pages, preventing unbounded RSS growth over days/weeks.
# Long-lived processes: gen2 GC rarely runs at steady state and glibc retains freed
# pages as RSS, so trim every scan to prevent unbounded RSS growth over days/weeks.
try:
from hermes_cli.mem_trim import trim_memory
trim_memory(reason="idle reaper periodic trim")
except Exception as exc:
# debug, not warning — persistent failure would repeat every reaper
# scan (300s) forever; sibling failure branches log at debug.
logger.debug(
"idle reaper memory trim failed: %s: %s", type(exc).__name__, exc
)
# debug, not warning — a persistent failure would repeat every scan.
logger.debug("idle reaper memory trim failed: %s: %s", type(exc).__name__, exc)
def _reclaim_orphaned_leases() -> None:
@@ -255,14 +214,10 @@ def _reclaim_orphaned_leases() -> None:
logger.debug("orphaned lease reclaim failed", exc_info=True)
# Soft LRU cap on in-memory sessions. The 6h TTL reaper above only frees
# sessions that have been idle for hours; a heavy user who reconnects often
# accumulates detached sessions (the report's ``detached_sessions=5``) whose
# agents sit resident for the full TTL. The cap evicts the least-recently-active
# DETACHED sessions sooner so live agents don't pile up under memory pressure.
# Default-on but provably safe: it only touches sessions with no live client
# (reopening re-resumes them from the DB) and never a running / pending /
# mid-build / live-transport one. 0/null disables.
# Soft LRU cap on in-memory sessions: the TTL reaper only frees sessions idle for hours,
# so a heavy reconnecting user accumulates resident detached agents. The cap evicts the
# least-recently-active DETACHED sessions sooner — never a running / pending / mid-build /
# live-transport one (reopening re-resumes from the DB). 0/null disables.
def _max_live_sessions() -> int:
try:
from hermes_cli.active_sessions import coerce_max_concurrent_sessions
@@ -280,18 +235,8 @@ def _max_live_sessions() -> int:
def _session_is_lru_evictable(sid: str, session: dict) -> bool:
# Same hard exemptions as the TTL reaper (never evict a session mid-turn,
# awaiting input, still building, or owning active delegated work), but
# WITHOUT the hours-scale age gate: a detached session is eligible the
# moment it loses its client.
if session.get("running") or _session_pending_kind(sid):
return False
if _session_has_active_delegations(sid, session):
return False
ready = session.get("agent_ready")
if ready is not None and not ready.is_set() and not session.get("lazy"):
return False
return _transport_is_dead(session.get("transport"))
# TTL-reaper exemptions WITHOUT the age gate: eligible the moment it loses its client.
return _reaper_session_is_detached_idle(sid, session)
def _enforce_session_cap() -> None:
@@ -299,14 +244,10 @@ def _enforce_session_cap() -> None:
if cap <= 0:
return
with _sessions_lock:
total = len(_sessions)
if total <= cap:
if len(_sessions) <= cap:
return
evictable = [
(sid, s) for sid, s in _sessions.items() if _session_is_lru_evictable(sid, s)
]
# Oldest-touched first; only evict down to the cap (live/focused sessions on
# a live transport are never eligible, so we may stop short of the cap).
evictable = [(sid, s) for sid, s in _sessions.items() if _session_is_lru_evictable(sid, s)]
# Oldest-touched first; evict only down to the cap (may stop short: live sessions are never eligible).
evictable.sort(key=lambda kv: float(kv[1].get("last_active") or 0.0))
for sid, _s in evictable:
with _sessions_lock:
@@ -315,12 +256,16 @@ def _enforce_session_cap() -> None:
_close_session_by_id(
sid,
end_reason="lru_evict",
predicate=lambda session, victim_sid=sid: _session_is_lru_evictable(
victim_sid, session
),
predicate=lambda session, vs=sid: _session_is_lru_evictable(vs, session),
)
def _reaper_daemon_timer(delay: float, fn) -> None:
timer = threading.Timer(delay, fn)
timer.daemon = True
timer.start()
def _schedule_session_cap_enforcement() -> None:
"""Run the LRU sweep off the response path (eviction can call agent.close)."""
@@ -330,38 +275,26 @@ def _schedule_session_cap_enforcement() -> None:
except Exception:
logger.debug("session cap enforcement failed", exc_info=True)
timer = threading.Timer(0.1, _run)
timer.daemon = True
timer.start()
_reaper_daemon_timer(0.1, _run)
# ── Startup sweep for orphaned session rows (#65194) ─────────────────────
# The WS-orphan reaper above is an in-process threading.Timer: a gateway
# restart (update, crash, systemd) kills it before it fires, leaving the
# session row `ended_at IS NULL` forever. This is the startup complement
# every other resource type already has (docker_orphan_reaper, compression
# orphans). Scheduled once per process from both gateway entry points
# (stdio `entry.main` and the WS sidecar's `handle_ws`) — desktop/dashboard
# never run `entry.main()`. state.db is shared by sibling processes on the
# same profile, so eligibility is conservative. Disable via
# `dashboard.startup_orphan_sweep: false` (default on).
# ── Startup sweep for orphaned session rows ──────────────────────────────
# The WS-orphan reaper is an in-process Timer: a gateway restart kills it before it fires, leaving
# the row `ended_at IS NULL` forever. Scheduled once per process from both gateway entry points
# (stdio `entry.main`, WS sidecar `handle_ws`). state.db is shared by sibling processes on the same
# profile, so eligibility is conservative. Disable via `dashboard.startup_orphan_sweep: false`.
_ORPHAN_SWEEP_SOURCES = ("tui", "desktop", "subagent")
_startup_orphan_sweep_ran = False
_startup_orphan_sweep_lock = threading.Lock()
def _session_orphan_reaper_enabled() -> bool:
"""``dashboard.startup_orphan_sweep`` (default on). Fail-open on errors."""
"""``dashboard.startup_orphan_sweep`` (default on). Fail-open on errors and
on a missing key (raw yaml, no DEFAULT_CONFIG merge on this loader)."""
try:
dashboard_cfg = (_load_cfg() or {}).get("dashboard") or {}
if isinstance(dashboard_cfg, dict) and "startup_orphan_sweep" in dashboard_cfg:
return is_truthy_value(
dashboard_cfg.get("startup_orphan_sweep"), default=True
)
# Fail-open: a missing key (raw yaml, no DEFAULT_CONFIG merge on
# this loader) must keep the sweep on.
return is_truthy_value(dashboard_cfg.get("startup_orphan_sweep"), default=True)
return True
except Exception:
return True
@@ -374,11 +307,9 @@ def _live_session_ids() -> list[str]:
for sid, session in _sessions.items():
if sid:
ids.add(str(sid))
agent = session.get("agent") if isinstance(session, dict) else None
for candidate in (
getattr(agent, "session_id", None),
session.get("session_key") if isinstance(session, dict) else None,
):
if not isinstance(session, dict):
continue
for candidate in (getattr(session.get("agent"), "session_id", None), session.get("session_key")):
if candidate:
ids.add(str(candidate))
return sorted(ids)
@@ -387,56 +318,33 @@ def _live_session_ids() -> list[str]:
def _sweep_orphaned_session_rows() -> list[str]:
"""End orphaned tui/desktop/subagent rows left by a dead process.
"Provably orphaned" is inferred conservatively from inactivity — the
row must have been created AND last messaged at least the session TTL
ago (``HERMES_TUI_SESSION_TTL_S``). A freshly created row that copied
an old transcript is protected by its own ``started_at``. Rows this
process still holds in memory (e.g. a ``session.resume`` during the
startup grace window) are excluded so the sweep never races a
mid-reconnect client.
Cross-backend liveness (#94895): when one ``state.db`` is shared by
N serve / gateway processes, each registered a heartbeat row in
``gateway_heartbeats``. The sweep refuses to close a row that any
live backend (heartbeat refreshed within ``2 * TTL``) could
plausibly own — see ``SessionDB.sweep_orphaned_sessions`` for the
exact predicate.
"Provably orphaned" is inferred conservatively: the row must have been created AND last
messaged at least the session TTL ago (a fresh row that copied an old transcript is
protected by its own ``started_at``). Rows held in memory (e.g. a ``session.resume`` in
the startup grace window) are excluded. Cross-backend: the sweep refuses to close a row
any live backend (heartbeat within ``2 * TTL``) could own — see
``SessionDB.sweep_orphaned_sessions``.
"""
db = _get_db()
if db is None:
return []
ttl = _SESSION_TTL_S
if ttl <= 0:
if db is None or ttl <= 0:
return []
swept = db.sweep_orphaned_sessions(
max_idle_seconds=ttl,
sources=_ORPHAN_SWEEP_SOURCES,
exclude_ids=tuple(_live_session_ids()),
max_idle_seconds=ttl, sources=_ORPHAN_SWEEP_SOURCES, exclude_ids=tuple(_live_session_ids())
)
if swept:
logger.info(
"Closed %d orphaned session row(s) from a previous gateway "
"process (startup_orphan_reap): %s",
len(swept),
", ".join(swept),
"Closed %d orphaned session row(s) from a previous gateway process (startup_orphan_reap): %s",
len(swept), ", ".join(swept),
)
return swept
# ── Cross-backend heartbeat (#94895) ───────────────────────────────────
# Each serve / gateway process registers a heartbeat row in
# ``gateway_heartbeats`` so the startup orphan sweep can tell "row owned
# by a live but idle backend" from "row truly orphaned". Without this,
# the first process to restart in a multi-backend topology reaped every
# inactive row — including those held by the other N−1 still-running
# processes (the #94895 reporter saw 473 sessions disappear in one shot).
#
# Refresh cadence: every HEARTBEAT_REFRESH_S (default 60s — much shorter
# than the default 6h session TTL so a refresh always lands inside the
# staleness window). The heartbeat is removed at process exit so a
# graceful shutdown doesn't leave a stale row behind. A crashed process
# leaves its row until the heartbeat ages out of the staleness window,
# at which point the sweep treats it as dead.
# ── Cross-backend heartbeat ──────────────────────────────────────────────
# Each serve / gateway process registers a heartbeat row in ``gateway_heartbeats`` so the startup
# sweep can tell "owned by a live but idle backend" from "truly orphaned" (else the first process to
# restart reaped every inactive row of the other N−1). Refresh 60s default — far shorter than the
# 6h TTL so a refresh always lands inside the staleness window. Removed at exit; a crashed row ages out.
_HEARTBEAT_REFRESH_S = max(0.0, env_float("HERMES_GATEWAY_HEARTBEAT_REFRESH_S", 60.0))
@@ -444,13 +352,13 @@ _heartbeat_refresher_started = False
_heartbeat_refresher_lock = threading.Lock()
def _backend_id_for_this_process() -> str:
"""Stable identity for this process's heartbeat row (#94895).
def _reaper_hostname() -> str:
return os.uname().nodename if hasattr(os, "uname") else "host"
Includes pid AND a startup-time nonce so a PID-reuse respawn cannot
inherit the dead predecessor's heartbeat and protect truly orphaned
sessions. The pid is kept for human readability in diagnostics.
"""
def _backend_id_for_this_process() -> str:
"""Stable identity for this process's heartbeat row: pid (readability) AND a startup
nonce so a PID-reuse respawn cannot inherit the dead predecessor's heartbeat."""
nonce = getattr(_backend_id_for_this_process, "_nonce", None)
if nonce is None:
import secrets as _secrets
@@ -460,11 +368,11 @@ def _backend_id_for_this_process() -> str:
setattr(_backend_id_for_this_process, "_nonce", nonce)
except AttributeError: # pragma: no cover - defensive
pass
return f"{_current_profile_name()}@{os.uname().nodename if hasattr(os, 'uname') else 'host'}:{os.getpid()}:{nonce}"
return f"{_current_profile_name()}@{_reaper_hostname()}:{os.getpid()}:{nonce}"
def _refresh_backend_heartbeat() -> None:
"""Refresh this backend's heartbeat row (#94895). No-op when DB unavailable."""
"""Refresh this backend's heartbeat row. No-op when DB unavailable."""
db = _get_db()
if db is None:
return
@@ -474,17 +382,15 @@ def _refresh_backend_heartbeat() -> None:
pid=os.getpid(),
started_at=_gateway_started_at(),
profile=_current_profile_name(),
host=(os.uname().nodename if hasattr(os, "uname") else "host"),
host=_reaper_hostname(),
)
except Exception:
logger.debug("backend heartbeat refresh failed", exc_info=True)
def _gateway_started_at() -> float:
"""Wall-clock time when this process started. Module-import time is
a good-enough proxy: the heartbeat refresher runs after the gateway
is fully wired up.
"""
"""Wall-clock time this process started (first-call time is a good-enough
proxy: the heartbeat refresher runs after the gateway is fully wired up)."""
started = getattr(_gateway_started_at, "_t", None)
if started is None:
started = time.time()
@@ -506,25 +412,14 @@ def _heartbeat_refresher_loop(stop_event: threading.Event) -> None:
def _start_backend_heartbeat_refresher() -> None:
"""Register this backend and start the refresher thread (#94895).
Called once per process from both gateway entry points. The first
refresh writes the row immediately so even a very fast crash leaves
a fresh-enough row that other backends can see. Repeat calls are
no-ops. The refresher thread is only spawned when
``_HEARTBEAT_REFRESH_S > 0`` — a refresh interval of zero means
"register the row once, never refresh" (the row ages out naturally
after the heartbeat staleness window).
"""
"""Register this backend and start the refresher thread (once per process). The first
refresh writes the row synchronously so this process's own sweep sees itself in the
heartbeat table. ``_HEARTBEAT_REFRESH_S <= 0`` means "register once, never refresh"."""
global _heartbeat_refresher_started
with _heartbeat_refresher_lock:
if _heartbeat_refresher_started:
return
_heartbeat_refresher_started = True
# Write a row synchronously so the sweep run later in this same
# process can see ourselves in the heartbeat table too. Without
# this, exclude_ids would have to cover every local session — a
# regression in the strict-ownership case the heartbeat exists to fix.
try:
_refresh_backend_heartbeat()
except Exception:
@@ -535,37 +430,24 @@ def _start_backend_heartbeat_refresher() -> None:
def _atexit_clear():
stop_event.set()
try:
with contextlib.suppress(Exception):
db = _get_db()
if db is not None:
db.clear_backend_heartbeat(_backend_id_for_this_process())
except Exception:
pass
atexit.register(_atexit_clear)
thread = threading.Thread(
target=_heartbeat_refresher_loop,
args=(stop_event,),
name="hermes-gateway-heartbeat",
daemon=True,
)
thread.start()
threading.Thread(
target=_heartbeat_refresher_loop, args=(stop_event,), name="hermes-gateway-heartbeat", daemon=True
).start()
def _schedule_startup_orphan_sweep() -> None:
"""Schedule the once-per-process startup orphan sweep (#65194).
Called from both gateway entry points. Repeat calls are no-ops. The
sweep is delayed by the WS-orphan grace window so a client reconnecting
right after a restart can ``session.resume`` its row before the sweep
reads the DB. ``HERMES_TUI_WS_ORPHAN_REAP_GRACE_S=0`` (park forever)
and ``HERMES_TUI_SESSION_TTL_S=0`` both suppress the sweep; so does
``dashboard.startup_orphan_sweep: false``.
"""
"""Schedule the once-per-process startup orphan sweep, delayed by the WS-orphan grace
window so a client reconnecting right after a restart can ``session.resume`` its row
first. Grace 0 (park forever), TTL 0 and ``dashboard.startup_orphan_sweep: false``
all suppress the sweep."""
global _startup_orphan_sweep_ran
if _WS_ORPHAN_REAP_GRACE_S <= 0 or _SESSION_TTL_S <= 0:
return
if not _session_orphan_reaper_enabled():
if _WS_ORPHAN_REAP_GRACE_S <= 0 or _SESSION_TTL_S <= 0 or not _session_orphan_reaper_enabled():
return
if _startup_orphan_sweep_ran:
return
@@ -580,9 +462,7 @@ def _schedule_startup_orphan_sweep() -> None:
except Exception:
logger.warning("startup orphan session sweep failed", exc_info=True)
timer = threading.Timer(_WS_ORPHAN_REAP_GRACE_S, _run)
timer.daemon = True
timer.start()
_reaper_daemon_timer(_WS_ORPHAN_REAP_GRACE_S, _run)
def register(server) -> None:
+221 -466
View File
@@ -18,12 +18,7 @@ def _normalize_completion_path(path_part: str) -> str:
expanded = os.path.expanduser(path_part)
if os.name != "nt":
normalized = expanded.replace("\\", "/")
if (
len(normalized) >= 3
and normalized[1] == ":"
and normalized[2] == "/"
and normalized[0].isalpha()
):
if len(normalized) >= 3 and normalized[1] == ":" and normalized[2] == "/" and normalized[0].isalpha():
return f"/mnt/{normalized[0].lower()}/{normalized[3:]}"
return expanded
@@ -36,10 +31,8 @@ def _completion_cwd(params: dict | None = None) -> str:
# A session bound to another profile resolves its workspace from THAT
# profile's config before falling back to the launch profile's env var.
or _profile_configured_cwd(_profile_home(params.get("profile")))
# The launch profile's dashboard /chat attaches to the dashboard's
# in-memory gateway, which does NOT inherit the PTY child's bridged
# TERMINAL_CWD. Read the launch profile's config.yaml directly so a
# configured terminal.cwd wins over a stale process env / launch dir.
# The dashboard's in-memory gateway does NOT inherit the PTY child's
# bridged TERMINAL_CWD, so a configured terminal.cwd is read directly.
or _launch_configured_cwd()
or os.environ.get("TERMINAL_CWD")
or os.getcwd()
@@ -53,63 +46,35 @@ def _completion_cwd(params: dict | None = None) -> str:
return os.getcwd()
def _workdir_terminal_cfg(key: str) -> str:
"""Stripped ``terminal.<key>`` from config, or "" when unset/unreadable."""
try:
terminal_cfg = _load_cfg().get("terminal", {})
if isinstance(terminal_cfg, dict):
return str(terminal_cfg.get(key) or "").strip()
except Exception:
pass
return ""
def _terminal_task_cwd(session: dict | None) -> str:
"""Return the cwd that terminal_tool should use for this TUI session.
``_completion_cwd`` validates paths on the host so file completion does not
point at nonsense. Non-local terminal backends are different: their cwd is
inside the target environment, so an SSH path like /home/user/workspace may
not exist on the local macOS host but is still the correct execution cwd.
When ``TERMINAL_ENV`` is unset (dashboard/TUI process) the config's
``terminal.backend`` is consulted as a fallback so the non-local cwd
resolution path is taken even when the dashboard entrypoint did not call
``apply_terminal_config_to_env`` on its own ``os.environ``.
"""
"""The cwd terminal_tool should use for this TUI session. Unlike
``_completion_cwd`` it is NOT validated on the host: a non-local backend's
cwd lives inside the target environment."""
return _terminal_task_cwd_with_source(session)[0]
def _terminal_task_cwd_with_source(session: dict | None) -> tuple[str, str]:
"""Like :func:`_terminal_task_cwd` but also names the value's ORIGIN.
Returns ``(cwd, source)`` where source is:
* ``"session"`` — the workspace the user attached to THIS session
(``explicit_cwd``), or this session's own tracked directory.
* ``"process"`` — the process-global ``TERMINAL_CWD`` env var / config
``terminal.cwd`` fallback. On a shared-container backend this is the
normal seed; under per-session docker isolation it is a launch
artifact from a PREVIOUS session (the workspace picker persists it
process-wide) and must never become a fresh session's bind mount —
terminal_tool refuses ``cwd_source: "process"`` as a mount source.
"""
backend = (os.environ.get("TERMINAL_ENV") or "").strip().lower()
if not backend or backend == "local":
# Fall back to config when TERMINAL_ENV is unset (dashboard/TUI process
# never calls apply_terminal_config_to_env on os.environ).
try:
terminal_cfg = _load_cfg().get("terminal", {})
if isinstance(terminal_cfg, dict):
cfg_backend = str(terminal_cfg.get("backend") or "").strip().lower()
if cfg_backend and cfg_backend != "local":
backend = cfg_backend
except Exception:
pass
if backend and backend != "local":
# A workspace the user explicitly attached to THIS session wins over
# the process-global env var — the env var is whatever the LAST
# session's picker wrote, not this session's choice.
"""Like :func:`_terminal_task_cwd` but returns ``(cwd, source)``: ``"session"`` for THIS
session's workspace (``explicit_cwd``/tracked dir), ``"process"`` for the process-global
``TERMINAL_CWD`` / ``terminal.cwd`` fallback — under per-session docker isolation that is a
launch artifact of a PREVIOUS session, so terminal_tool refuses it as a bind-mount source."""
backend = _effective_terminal_backend()
if backend != "local":
# THIS session's explicit workspace beats the LAST session's env var.
if session and session.get("explicit_cwd") and session.get("cwd"):
return str(session["cwd"]), "session"
raw = os.environ.get("TERMINAL_CWD", "").strip()
if not raw:
try:
terminal_cfg = _load_cfg().get("terminal", {})
if isinstance(terminal_cfg, dict):
raw = str(terminal_cfg.get("cwd") or "").strip()
except Exception:
raw = ""
raw = os.environ.get("TERMINAL_CWD", "").strip() or _workdir_terminal_cfg("cwd")
if raw and raw not in {".", "auto", "cwd"}:
return raw, "process"
if backend == "ssh":
@@ -120,9 +85,7 @@ def _terminal_task_cwd_with_source(session: dict | None) -> tuple[str, str]:
return _completion_cwd(), "process"
# Git working-tree probing (run git, resolve roots, fold worktrees) lives in a
# focused, single-flight-cached module; these stay as the in-server names every
# call site already uses.
# Git probing lives in git_probe; these keep the in-server names call sites use.
_git = git_probe.run_git
_git_branch_for_cwd = git_probe.branch
_git_repo_root_for_cwd = git_probe.repo_root
@@ -137,8 +100,7 @@ def _session_cwd(session: dict | None) -> str:
# Sources whose launch directory is an artifact of how the app was started, not
# a workspace the user picked. Everything else is terminal-started: the process
# runs in a directory the user deliberately cd'd into.
# a workspace the user picked (everything else is a directory the user cd'd into).
_LAUNCH_CWD_NOT_A_WORKSPACE = {"desktop"}
@@ -152,41 +114,26 @@ def _context_cwd_is_launch_artifact(session: dict | None) -> bool:
def _persisted_session_cwd(session: dict) -> str | None:
"""The cwd to stamp on the session's DB row, or None to leave it unset.
See :func:`_ensure_session_db_row` for why the launch directory counts as a
workspace for terminal sessions but not for the desktop.
"""
"""The cwd to stamp on the session's DB row, or None to leave it unset (see
:func:`_ensure_session_db_row` for the desktop vs terminal launch-dir rule)."""
if session.get("explicit_cwd"):
return _session_cwd(session)
if _session_source(session) in _LAUNCH_CWD_NOT_A_WORKSPACE:
return None
# Only the session's OWN directory. `_session_cwd` falls back to the
# gateway-wide completion cwd, which belongs to no session in particular —
# stamping that would invent a workspace for a session that never had one.
# Only the session's OWN directory, never `_session_cwd`'s gateway-wide fallback.
return str(session.get("cwd") or "") or None
def _heal_dead_cwd(cwd: str) -> str:
"""Resolve a session cwd that points at a now-deleted directory.
A session anchored to a linked worktree (``<repo>/.worktrees/<name>``) keeps
that path after the worktree is removed (branch merged, `git worktree
remove`, etc). The literal dir is gone, so a probe of it returns nothing and
the composer shows no branch — while the sidebar still folds the path up to
the repo's main lane. Heal the mismatch: walk up to the first existing
ancestor, then resolve its common git root, so a dead-worktree cwd collapses
to the live repo root (and its real current branch).
Only meaningful for local backends; a remote/SSH cwd may legitimately not
exist on the host, so callers must skip healing there.
"""
"""Resolve a session cwd inside a now-deleted directory (e.g. a removed linked worktree,
which probes to no branch while the sidebar folds it to the main lane): walk up to the first
existing ancestor and take its common git root. Local backends only — a remote/SSH cwd may
legitimately not exist on the host, so callers skip healing there."""
raw = (cwd or "").strip()
if not raw or os.path.isdir(raw):
return raw
probe = raw
# Climb to the first ancestor that still exists on disk.
for _ in range(64):
parent = os.path.dirname(probe)
if not parent or parent == probe:
@@ -212,33 +159,21 @@ def _is_local_terminal_backend() -> bool:
def _effective_terminal_backend() -> str:
"""Active terminal backend name (``local``, ``docker``, ``ssh``, ...).
``TERMINAL_ENV`` is authoritative when set (launchers bridge
``terminal.backend`` into env at startup). Desktop/TUI in-process gateways
skip that bridge, so fall back to the ``terminal.backend`` config key —
the same rule ``_terminal_task_cwd`` uses.
"""
"""Active terminal backend name (``local``, ``docker``, ``ssh``, ...):
``TERMINAL_ENV`` when set (launchers bridge ``terminal.backend`` into env),
else the ``terminal.backend`` config key (desktop/TUI in-process gateways
skip that bridge)."""
backend = (os.environ.get("TERMINAL_ENV") or "").strip().lower()
if not backend or backend == "local":
try:
terminal_cfg = _load_cfg().get("terminal", {})
if isinstance(terminal_cfg, dict):
cfg_backend = str(terminal_cfg.get("backend") or "").strip().lower()
if cfg_backend and cfg_backend != "local":
backend = cfg_backend
except Exception:
pass
cfg_backend = _workdir_terminal_cfg("backend").lower()
if cfg_backend and cfg_backend != "local":
backend = cfg_backend
return backend or "local"
def _display_session_cwd(session: dict | None) -> str:
"""Session cwd for display/probe surfaces, healed past deleted worktrees.
Persists the healed value back to the session row (best-effort, local only)
so the next load is already coherent and the sidebar lane stops showing a
session pinned to a vanished path.
"""
"""Session cwd for display/probe surfaces, healed past deleted worktrees;
the healed value is persisted back (best-effort, local only)."""
cwd = _session_cwd(session)
if not _is_local_terminal_backend():
return cwd
@@ -252,33 +187,18 @@ def _display_session_cwd(session: dict | None) -> str:
def _reconcile_session_cwd_from_terminal(session: dict | None) -> bool:
"""Re-anchor a session that SETTLED in another git checkout. Returns moved.
"""Re-anchor a session that SETTLED in another worktree of the SAME repo. Returns moved.
An agent told to work in a fresh worktree does exactly that — `git worktree
add`, `cd` into it, and every later command runs there — but the session
stayed pinned to wherever it started, so the desktop kept labelling the chat
with the primary checkout's branch while all the work landed elsewhere.
A plain `cd` is deliberately NOT a workspace move (see
``_apply_project_workspace``): browsing to /tmp to read a log must not
re-home the chat. What we adopt here is narrower — the session's recorded
cwd is in a DIFFERENT working tree of the SAME repository (the shape
``git worktree add`` produces). Everything else — a non-git workspace
stepping into a repo, or a git workspace visiting an unrelated repo — is
a browsing visit, and a user's explicitly chosen workspace is never
overridden at all.
Local backends only: a remote/SSH cwd names a path on the host, which this
gateway can neither stat nor probe with git.
"""
An agent told to work in a fresh worktree `git worktree add`s and `cd`s in while the session
stays pinned (labelled with the primary checkout's branch). A plain `cd` is deliberately NOT
a workspace move (see ``_apply_project_workspace``): a non-git workspace stepping into a repo
or a visit to an unrelated repo is browsing, and an explicitly chosen workspace is never
overridden. Local backends only (a remote cwd cannot be stat'ed or git-probed here)."""
if not session or not _is_local_terminal_backend():
return False
# A workspace the user (or GUI) explicitly chose is never overridden by
# where the agent's terminal happened to settle — only another explicit
# action (`_set_session_cwd`, a project switch) moves it. A cwd this very
# function adopted is marked `cwd_from_settle` so a session can keep
# following the agent through successive worktrees.
# An explicit choice only moves by another explicit action; a cwd adopted
# HERE is marked `cwd_from_settle` so successive settles keep following.
if session.get("explicit_cwd") and not session.get("cwd_from_settle"):
return False
@@ -297,34 +217,20 @@ def _reconcile_session_cwd_from_terminal(session: dict | None) -> bool:
if resolved == current or not os.path.isdir(resolved):
return False
# The worktree ROOT, not the common repo root: folding worktrees together
# here is exactly what hides the move we're looking for.
# Worktree ROOTS (folding to the common root would hide the move), both in a git
# tree, different from each other, sharing the SAME common .git dir.
landed = _git_repo_root_for_cwd(resolved)
current_root = _git_repo_root_for_cwd(current)
# A relocation is a move between two DIFFERENT git working trees. When the
# session's own workspace is not in a git repo, the agent stepping into one
# to read a file or run a command is a browsing visit, not a re-home:
# adopting it would hijack a non-git workspace onto whatever repo a tool
# call touched first (e.g. a home-directory session pinned to the checkout
# it read a file from).
if not landed or not current_root or landed == current_root:
return False
# And only between checkouts of the SAME repository — the shape a real
# `git worktree add` produces (linked worktrees share the common .git
# dir). Settling in an UNRELATED repo (`cd ~/other-project && git log`)
# is likewise a visit: adopting it would re-home the chat onto whatever
# foreign repo the terminal last touched.
landed_common = _git_common_repo_root_for_cwd(resolved)
current_common = _git_common_repo_root_for_cwd(current)
if not landed_common or landed_common != current_common:
return False
session["cwd"] = resolved
# The session works here now, so this is its workspace — a desktop chat
# whose cwd was an unpersisted launch artifact earns a real row. The
# settle marker keeps this adoption overridable by the NEXT settle while
# still yielding to a user's explicit choice (see the guard above).
# This is the session's workspace now (a desktop launch-artifact cwd earns
# a real row); the settle marker keeps it overridable by the NEXT settle.
session["explicit_cwd"] = True
session["cwd_from_settle"] = True
_register_session_cwd(session)
@@ -334,14 +240,8 @@ def _reconcile_session_cwd_from_terminal(session: dict | None) -> bool:
def _emit_settled_session_info(sid: str, session: dict, agent) -> None:
"""Emit end-of-turn ``session.info``, reconciling a settled cwd first.
The turn is over, so the agent has stopped moving: this is the one moment
where its recorded cwd is a stable answer to "where does this session
work". Reconciling before building the payload means the same event that
already tells the desktop the turn ended also carries the new cwd/branch —
the client follows it with no new event type and no extra round trip.
"""
"""Emit end-of-turn ``session.info``, reconciling a settled cwd first: the agent has stopped
moving, and riding the reconcile on the turn-end event needs no new event type/round trip."""
try:
_reconcile_session_cwd_from_terminal(session)
except Exception:
@@ -364,96 +264,28 @@ def _register_session_cwd(session: dict | None) -> None:
from tools.terminal_tool import register_task_env_overrides
cwd, cwd_source = _terminal_task_cwd_with_source(session)
register_task_env_overrides(
session["session_key"], {"cwd": cwd, "cwd_source": cwd_source}
)
register_task_env_overrides(session["session_key"], {"cwd": cwd, "cwd_source": cwd_source})
except Exception:
pass
def _ensure_session_db_row(session: dict) -> bool:
"""Idempotently persist the session's DB row on first real activity.
def _workdir_row_model_config(session: dict) -> tuple[str, dict]:
"""``(model, model_config)`` for a fresh session row.
Called from prompt.submit so a row only exists once the user actually sends
a message — abandoned drafts never leave an empty "Untitled" session behind.
Uses INSERT OR IGNORE under the hood, so re-calls (and the AIAgent's own
lazy create) are no-ops.
Returns False only when the store is unavailable (no openable state.db);
prompt.submit turns that into an RPC error so a send fails loudly with a
toast instead of streaming into a store that will never save it (#98924).
Every other outcome — no key, best-effort attempt, success — is True.
A cwd the user *chose* is always persisted. When they made no explicit
choice the launch directory stands in, and whether that is meaningful
depends on how the session was started:
* The desktop launches from wherever the app bundle was opened (often ``/``
or the user's home), so stamping that would file every unpicked chat under
a folder the user never chose. Those stay null and group under "No
workspace", which is the desired default.
* A terminal session (``hermes`` / ``hermes --tui`` / CLI) is started from a
directory the user deliberately ``cd``'d into — that IS the workspace, and
it is also where the agent's terminal actually runs. Dropping it stranded
the session with no cwd AND no git_repo_root, so the sidebar could never
place it under its project.
"""
key = session.get("session_key")
if not key:
return
# Persist into the session's own profile db (global remote mode), not the
# launch profile's — otherwise the row lands in the wrong state.db, the
# unified list mis-tags it, and resume 404s ("session not found").
profile_home = session.get("profile_home")
if profile_home:
from hermes_state import SessionDB
try:
from hermes_state import get_shared_session_db
db = get_shared_session_db(Path(profile_home) / "state.db")
except Exception:
logger.debug("failed to open profile db for session row", exc_info=True)
return False
close_db = True
else:
db = _get_db()
close_db = False
if db is None:
# Fail loud ONLY when the store actually failed to open (#98924):
# _db_error records the SessionDB open exception. A None db with no
# recorded error means "no store in this context" (degraded harness,
# store deliberately absent) — that keeps the pinned best-effort
# contract and stays True.
return _db_error is None
# The session's own model/effort/fast pick — the composer override shipped on
# session.create, or a restored /model switch — must own the row's model +
# model_config. The agent isn't built yet at first prompt.submit, so derive
# the row from the live override dict; fall back to the global resolved model
# only when this chat made no explicit pick. Writing the global default here
# used to win the INSERT-OR-IGNORE race against the agent's own correct
# lazy-create, so a reconnect/resume rebuilt from the global model and
# silently reverted the chat (e.g. picked gpt-5.5, reconnect snapped back to
# the profile default). model_config carries provider/reasoning/service_tier
# so resume restores effort + fast too, not just the model name.
The session's own model/effort/fast pick (composer override or restored /model switch) must
own the row: the agent isn't built yet at first prompt.submit, and writing the global default
here wins the INSERT-OR-IGNORE race, so a reconnect silently reverts to the profile default.
model_config carries provider/reasoning/service_tier so resume restores effort + fast too."""
override = session.get("model_override")
override = override if isinstance(override, dict) else {}
row_model = str(override.get("model") or "").strip() or _resolve_model()
model_config: dict = {}
for src_key, cfg_key in (
("model", "model"),
("provider", "provider"),
("base_url", "base_url"),
("api_mode", "api_mode"),
):
if val := override.get(src_key):
for cfg_key in ("model", "provider", "base_url", "api_mode"):
if val := override.get(cfg_key):
model_config[cfg_key] = str(val)
# The composer override may carry the RESOLVED provider "custom" for a named
# ``providers:`` / ``custom_providers:`` entry. Persisting bare "custom" here
# (the very first DB write for a fresh desktop session, before the agent is
# built) is the origin of the recurring "No LLM provider configured" rows:
# on the next resume bare "custom" routes to OpenRouter with no key. Recover
# the durable ``custom:<name>`` identity from the override's base_url, else
# the configured provider, so a routable identity is persisted from the
# start (matches _runtime_model_config's normalization).
# A RESOLVED provider "custom" (named ``providers:``/``custom_providers:`` entry) persisted
# bare here is the origin of "No LLM provider configured" rows (resume routes to OpenRouter
# with no key). Recover the durable ``custom:<name>`` identity (matches _runtime_model_config).
if str(model_config.get("provider") or "").strip().lower() == "custom":
try:
from hermes_cli.runtime_provider import canonical_custom_identity
@@ -465,96 +297,100 @@ def _ensure_session_db_row(session: dict) -> bool:
if healed:
model_config["provider"] = healed
except Exception:
logger.debug(
"custom provider identity recovery failed (db row)", exc_info=True
)
logger.debug("custom provider identity recovery failed (db row)", exc_info=True)
if (reasoning := session.get("create_reasoning_override")) is not None:
model_config["reasoning_config"] = reasoning
create_service_tier_override = session.get("create_service_tier_override")
if create_service_tier_override is not None:
# Empty string is the in-memory sentinel for an explicit normal tier:
# it bypasses _make_agent's profile fallback without sending a bogus
# service_tier value to the provider. Persist a durable marker so resume
# can distinguish that choice from an omitted/inherited tier.
# "" is the in-memory sentinel for an explicit normal tier (bypasses _make_agent's profile
# fallback); persist a durable marker so resume can tell it from an inherited tier.
model_config["service_tier"] = create_service_tier_override or "normal"
# Branch lineage: stamp the same ``_branched_from`` marker the TUI /branch
# uses so list_sessions_rich keeps the branch listed and the desktop sidebar
# can nest it under its parent.
parent_session_id = session.get("parent_session_id") or None
if parent_session_id:
# Same ``_branched_from`` marker the TUI /branch uses (list_sessions_rich + sidebar nesting).
if parent_session_id := session.get("parent_session_id"):
model_config["_branched_from"] = parent_session_id
# Bot-Mode room plumbing sessions are per-member scratch conversations
# inside a group chat: their runtime must ALWAYS follow the member profile's
# CURRENT config, never the provider that was pinned when the row was first
# written. Persist that contract explicitly so resume can distinguish room
# plumbing from a normal user chat (whose stored model/provider must be
# restored verbatim). See _stored_session_runtime_overrides.
if session.get("room_plumbing"):
model_config["room_plumbing"] = True
# Bot-Mode canonical chats (the ONE forever DM per bot) and room plumbing
# sessions are plugin-owned scratch conversations: their runtime must ALWAYS
# follow the member profile's CURRENT config, never the model/provider that
# was pinned when the row was first written. Persist that contract explicitly
# so resume can distinguish them from a normal user chat (whose stored
# model/provider must be restored verbatim). See
# _stored_session_runtime_overrides.
if session.get("follow_profile_config"):
model_config["follow_profile_config"] = True
try:
db.create_session(
key,
source=_session_source(session),
model=row_model,
model_config=model_config or None,
parent_session_id=parent_session_id,
cwd=_persisted_session_cwd(session),
# Self-describing rows: aggregators that merge multiple profile DBs
# into one list can't rely on which file a row came from alone.
# Stamp the launch profile explicitly instead of leaving NULL —
# NULL is exactly what the #94724 legacy-owner backfill exists to
# repair, and rows minted AFTER that one-shot backfill ran stayed
# NULL forever: profile-keyed matching then drops them from the
# sidebar and deep links can't resolve them (#99222).
profile_name=(
Path(profile_home).name if profile_home else _current_profile_name()
),
)
# A session can be born hidden (session.create hidden=true, or a
# session.set_hidden that arrived before the row existed): apply the
# deferred intent now that the row exists, mirroring pending_title.
if session.get("pending_hidden"):
try:
db.set_session_hidden(key, True)
except Exception:
logger.debug("failed to apply pending hidden flag", exc_info=True)
except Exception as exc:
# Disk-full is not a soft failure: if we swallow it here, prompt.submit
# returns {"status":"streaming"} and the user's message vanishes with
# no toast. Re-raise so the submit handler can return a real RPC error.
from hermes_state import is_disk_full_error
# Bot-Mode canonical chats / room plumbing are plugin-owned scratch conversations whose runtime
# must ALWAYS follow the member profile's CURRENT config, never the provider pinned at first
# write; persist that contract for resume (see _stored_session_runtime_overrides).
for flag in ("room_plumbing", "follow_profile_config"):
if session.get(flag):
model_config[flag] = True
return row_model, model_config
if is_disk_full_error(exc):
raise
logger.debug("failed to persist desktop session row", exc_info=True)
finally:
if close_db:
try:
from hermes_state import release_or_close
release_or_close(db)
except Exception:
pass
def _ensure_session_db_row(session: dict) -> bool:
"""Idempotently persist the session's DB row on first real activity (prompt.submit), so
abandoned drafts never leave an empty "Untitled" session. INSERT OR IGNORE: re-calls and the
AIAgent's lazy create are no-ops. Returns False only when the store is unavailable (no
openable state.db) — prompt.submit fails the send loudly instead of streaming into a store
that will never save it; no key / best-effort / success are all True.
A cwd the user *chose* is always persisted. Otherwise the launch directory stands in only for
terminal sessions (the user deliberately ``cd``'d there; dropping it left the sidebar with no
cwd AND no git_repo_root); desktop launch dirs (``/``, home) stay null -> "No workspace"."""
key = session.get("session_key")
if not key:
return
# Persist into the session's own profile db (global remote mode), not the launch profile's —
# otherwise the unified list mis-tags the row and resume 404s ("session not found").
profile_home = session.get("profile_home")
with _workdir_owner_db(session, "failed to open profile db for session row") as db:
if db is _WORKDIR_DB_OPEN_FAILED:
return False
if db is None:
# Fail loud ONLY when the store failed to open (_db_error records the SessionDB open
# exception); None with no recorded error means "no store in this context" -> True.
return _db_error is None
row_model, model_config = _workdir_row_model_config(session)
try:
db.create_session(
key,
source=_session_source(session),
model=row_model,
model_config=model_config or None,
parent_session_id=session.get("parent_session_id") or None,
cwd=_persisted_session_cwd(session),
# Self-describing rows: aggregators merging several profile DBs can't rely on
# which file a row came from; a NULL is only repaired by the one-shot backfill.
profile_name=Path(profile_home).name if profile_home else _current_profile_name(),
)
# Born hidden (session.create hidden=true, or set_hidden before the
# row existed): apply the deferred intent now, like pending_title.
if session.get("pending_hidden"):
try:
db.set_session_hidden(key, True)
except Exception:
logger.debug("failed to apply pending hidden flag", exc_info=True)
except Exception as exc:
# Disk-full is not a soft failure: swallowed here, prompt.submit
# returns {"status":"streaming"} and the message vanishes silently.
_workdir_reraise_disk_full(exc, "failed to persist desktop session row")
return True
def _persist_branch_seed(session: dict) -> None:
"""First-turn persist of a branch's copied transcript.
def _workdir_reraise_disk_full(exc: BaseException, log_msg: str) -> None:
"""Re-raise a disk-full write error (the caller must surface it); debug-log the rest."""
from hermes_state import is_disk_full_error
A branch is a draft until its first submit: the parent's messages live only
in ``session["history"]`` (they ride into the agent as ``conversation_history``,
which ``_flush_messages_to_session_db`` skips by identity). Without this the
branch row would resume missing its pre-branch context. Runs once; the row +
parent link are written by ``_ensure_session_db_row`` just before this.
"""
if is_disk_full_error(exc):
raise exc
logger.debug(log_msg, exc_info=True)
# Seed row fields copied from the parent transcript. display_kind/metadata: timeline markers
# ride as role=user, dropping the tag re-plants them as bare user turns after a restart and
# corrupts the truncate ordinal address space. timestamp: parent's original, not "now".
_WORKDIR_SEED_FIELDS = (
"content", "reasoning", "reasoning_content", "reasoning_details", "codex_reasoning_items",
"codex_message_items", "display_kind", "display_metadata", "timestamp",
)
def _persist_branch_seed(session: dict) -> None:
"""First-turn persist of a branch's copied transcript. A branch is a draft until its first
submit: the parent's messages live only in ``session["history"]`` (ridden into the agent as
``conversation_history``, which ``_flush_messages_to_session_db`` skips by identity), so the
row would otherwise resume missing its pre-branch context. Runs once, after
``_ensure_session_db_row`` wrote the row + parent link."""
if not session.get("parent_session_id") or session.get("_branch_seed_persisted"):
return
key = session.get("session_key")
@@ -568,66 +404,39 @@ def _persist_branch_seed(session: dict) -> None:
if db is None:
return
try:
# Bounded-chunk transactions (see #23254): a branch seed can be
# hundreds of rows; chunking keeps each BEGIN IMMEDIATE short so
# concurrent writers aren't starved. Recovery semantics match the
# old per-row loop (mid-copy failure leaves a partial seed with
# _branch_seed_persisted unset).
# Chunked so each BEGIN IMMEDIATE stays short (a seed can be hundreds of rows); a
# mid-copy failure leaves a partial seed with _branch_seed_persisted unset.
db.append_messages_batch(
key,
[
{
"role": msg.get("role", "user"),
"content": msg.get("content"),
"reasoning": msg.get("reasoning"),
"reasoning_content": msg.get("reasoning_content"),
"reasoning_details": msg.get("reasoning_details"),
"codex_reasoning_items": msg.get("codex_reasoning_items"),
"codex_message_items": msg.get("codex_message_items"),
# Timeline markers (model_switch, personality_switch,
# auto_continue, …) ride as role=user; dropping the tag
# here re-planted them as bare user turns after a
# restart, corrupting the truncate ordinal address
# space the same way #82756 did.
"display_kind": msg.get("display_kind"),
"display_metadata": msg.get("display_metadata"),
# Preserve the parent's original message timestamps —
# append_message would otherwise stamp time.time() and the
# branch's copied history would all appear authored "now".
"timestamp": msg.get("timestamp"),
}
{"role": msg.get("role", "user"), **{f: msg.get(f) for f in _WORKDIR_SEED_FIELDS}}
for msg in seed
],
chunk_rows=500,
)
session["_branch_seed_persisted"] = True
except Exception as exc:
from hermes_state import is_disk_full_error
_workdir_reraise_disk_full(exc, "branch seed persist failed")
if is_disk_full_error(exc):
raise
logger.debug("branch seed persist failed", exc_info=True)
# Yielded by _workdir_owner_db when the profile db failed to OPEN (as opposed
# to "no store in this context"); _ensure_session_db_row fails loud on it.
_WORKDIR_DB_OPEN_FAILED = object()
@contextlib.contextmanager
def _session_db(session: dict):
"""Yield the SessionDB that owns this session's row (profile-aware).
Mirrors :func:`_ensure_session_db_row`: a remote/profile session persists
into its own profile's ``state.db`` (a fresh handle we close on exit);
everything else borrows the shared ``_get_db()`` handle (left open). Yields
None when the db is unavailable.
"""
def _workdir_owner_db(session: dict, fail_log: str):
"""Body of :func:`_session_db`; also used directly by ``_ensure_session_db_row``
so a test-patched ``_session_db`` does not change row creation."""
db, close_db = None, False
profile_home = session.get("profile_home")
if profile_home:
from hermes_state import SessionDB
try:
from hermes_state import get_shared_session_db
db, close_db = get_shared_session_db(Path(profile_home) / "state.db"), True
except Exception:
logger.debug("failed to open profile db for session", exc_info=True)
logger.debug(fail_log, exc_info=True)
db = _WORKDIR_DB_OPEN_FAILED
else:
db = _get_db()
try:
@@ -639,20 +448,24 @@ def _session_db(session: dict):
release_or_close(db)
@contextlib.contextmanager
def _session_db(session: dict):
"""Yield the SessionDB that owns this session's row (profile-aware): a remote/profile session
persists into its own profile's ``state.db`` (fresh handle, closed on exit); everything else
borrows the shared ``_get_db()`` handle (left open). Yields None when unavailable."""
with _workdir_owner_db(session, "failed to open profile db for session") as db:
yield None if db is _WORKDIR_DB_OPEN_FAILED else db
def _rewind_active_session_history(
session: dict,
user_ordinal: int,
*,
require_retryable: bool = False,
session: dict, user_ordinal: int, *, require_retryable: bool = False
) -> tuple[list[dict], dict, int]:
"""Rewind one canonical user turn while retaining carrier scaffolding.
The caller holds ``history_lock``. Persistent sessions archive the target
and tail; a composite carrier's own hidden handoff is inserted in that same
transaction. Memory is installed only after the durable commit and is
built from the already-validated prefix plus the returned scaffold row id,
so there is no fallible post-commit reload.
"""
Caller holds ``history_lock``. Persistent sessions archive the target and tail, inserting a
composite carrier's hidden handoff in the same transaction; memory is installed only after
the durable commit, from the already-validated prefix plus the returned scaffold row id
(no fallible post-commit reload)."""
from agent.context_compressor import (
history_before_user_originated_turn,
retryable_user_text,
@@ -660,10 +473,7 @@ def _rewind_active_session_history(
user_originated_turn_view,
)
from agent.memory_manager import sanitize_context
from agent.tool_dispatch_helpers import (
_is_multimodal_tool_result,
_multimodal_text_summary,
)
from agent.tool_dispatch_helpers import _is_multimodal_tool_result, _multimodal_text_summary
def _comparison_content(message: dict) -> Any:
content = message.get("content")
@@ -672,24 +482,22 @@ def _rewind_active_session_history(
elif isinstance(content, list):
text_parts = []
for part in content:
if isinstance(part, dict) and part.get("type") == "text":
if not isinstance(part, dict):
continue
if part.get("type") == "text":
text_parts.append(str(part.get("text", "")))
elif (
isinstance(part, dict)
and part.get("type") in {"image", "image_url", "input_image"}
):
elif part.get("type") in {"image", "image_url", "input_image"}:
text_parts.append("[screenshot]")
content = "\n".join(text_parts) if text_parts else None
if message.get("role") in {"user", "assistant"} and isinstance(content, str):
return sanitize_context(content).strip()
return content
def _user_indices(messages: list[dict]) -> list[int]:
return [i for i, m in enumerate(messages) if user_originated_turn_view(m) is not None]
history = _history_without_ephemeral_scaffolding(session.get("history", []))
user_indices = [
index
for index, message in enumerate(history)
if user_originated_turn_view(message) is not None
]
user_indices = _user_indices(history)
if user_ordinal < 0 or user_ordinal >= len(user_indices):
raise ValueError("target user message is no longer in session history")
target_index = user_indices[user_ordinal]
@@ -703,28 +511,17 @@ def _rewind_active_session_history(
if db is None:
raise RuntimeError("session database is unavailable")
expected_active_ids = db.get_active_message_ids(session_key)
durable = db.get_messages_as_conversation(
session_key,
include_row_ids=True,
)
durable_user_indices = [
index
for index, message in enumerate(durable)
if user_originated_turn_view(message) is not None
]
durable = db.get_messages_as_conversation(session_key, include_row_ids=True)
durable_user_indices = _user_indices(durable)
if len(durable_user_indices) != len(user_indices):
raise RuntimeError(
"session history changed before the rewind could be persisted"
)
raise RuntimeError("session history changed before the rewind could be persisted")
durable_target_index = durable_user_indices[user_ordinal]
durable_target = durable[durable_target_index]
durable_prefix, durable_live_view = history_before_user_originated_turn(
durable, durable_target_index
)
if _comparison_content(durable_live_view) != _comparison_content(live_view):
raise RuntimeError(
"session history changed before the rewind could be persisted"
)
raise RuntimeError("session history changed before the rewind could be persisted")
target_row_id = durable_target.get("_row_id")
if not isinstance(target_row_id, int):
raise RuntimeError("rewind target has no durable row identity")
@@ -741,21 +538,16 @@ def _rewind_active_session_history(
if scaffold is not None:
replacement_id = result.get("replacement_message_id")
if not isinstance(replacement_id, int):
raise RuntimeError(
"rewind commit did not return the replacement scaffold id"
)
raise RuntimeError("rewind commit did not return the replacement scaffold id")
durable_prefix[-1]["_row_id"] = replacement_id
durable_prefix[-1]["_db_persisted"] = True
installed[-1] = durable_prefix[-1]
# Current clients address destructive follow-ups by durable row id.
# Preserve the richer warm content (for example image parts), but
# copy row identities when the retained warm/durable shapes align.
# Clients address follow-ups by durable row id: keep the richer warm
# content but copy row identities when the shapes align.
if len(installed) == len(durable_prefix) and all(
warm.get("role") == durable_message.get("role")
and bool(warm.get("display_kind"))
== bool(durable_message.get("display_kind"))
and _comparison_content(warm)
== _comparison_content(durable_message)
and bool(warm.get("display_kind")) == bool(durable_message.get("display_kind"))
and _comparison_content(warm) == _comparison_content(durable_message)
for warm, durable_message in zip(installed, durable_prefix)
):
for warm, durable_message in zip(installed, durable_prefix):
@@ -785,37 +577,23 @@ def _history_without_ephemeral_scaffolding(history: list[dict]) -> list[dict]:
"""Return the durable transcript shape without transient recovery rows."""
from run_agent import _is_ephemeral_scaffolding
return [
message.copy()
for message in history
if not _is_ephemeral_scaffolding(message)
]
return [message.copy() for message in history if not _is_ephemeral_scaffolding(message)]
def _workdir_valid_generation(generation) -> bool:
"""A claimed DB probe generation: a positive int (bool excluded)."""
return not isinstance(generation, bool) and isinstance(generation, int) and generation >= 1
def _persist_session_git_meta(session: dict, cwd: str, generation: int) -> None:
"""Resolve + persist a session's git branch / repo root WITHOUT blocking.
Branch and root come from ``git`` subprocess probes; running them inline on
the session-init / cwd-set path would stall startup whenever ``cwd`` is slow
or on an unreachable mount. Run them on a short-lived daemon thread instead
and persist via the same profile-aware db the caller writes ``cwd`` to.
Best-effort: ``cwd`` itself is persisted synchronously by the caller, so a
probe failure just leaves these enrichment columns unset (the project tree
falls back to its live resolver / lazy backfill). Daemon, so a mid-flight
probe never delays gateway shutdown.
"""
"""Resolve + persist a session's git branch / repo root on a daemon thread: inline ``git``
probes on the session-init / cwd-set path would stall startup on a slow or unreachable
``cwd``. Persists via the same profile-aware db the caller wrote ``cwd`` to. Best-effort: a
probe failure leaves the enrichment columns unset (project tree uses its live resolver)."""
session_key = session.get("session_key", "")
if (
not session_key
or not cwd
or isinstance(generation, bool)
or not isinstance(generation, int)
or generation < 1
):
if not session_key or not cwd or not _workdir_valid_generation(generation):
return
# Snapshot the routing fields now; the live session dict may be gone by the
# time the thread runs. `_session_db` reopens the profile-correct db inside.
# Snapshot routing fields; the live session dict may be gone when the thread runs.
db_session = {"session_key": session_key, "profile_home": session.get("profile_home")}
def _run() -> None:
@@ -826,47 +604,26 @@ def _persist_session_git_meta(session: dict, cwd: str, generation: int) -> None:
return
with _session_db(db_session) as db:
if db is not None:
db.publish_session_git_metadata(
session_key,
cwd,
generation,
branch,
root,
)
db.publish_session_git_metadata(session_key, cwd, generation, branch, root)
except Exception:
logger.debug("failed to persist session git metadata", exc_info=True)
threading.Thread(target=_run, name="git-meta", daemon=True).start()
def _persist_session_cwd_and_schedule_git_meta(
session: dict,
cwd: str,
*,
db=None,
) -> int | None:
def _persist_session_cwd_and_schedule_git_meta(session: dict, cwd: str, *, db=None) -> int | None:
"""Claim a DB-backed probe generation, then start Git enrichment."""
try:
if db is not None:
generation = db.update_session_cwd(
session.get("session_key", ""), cwd
)
else:
with _session_db(session) as owner_db:
if owner_db is None:
return None
generation = owner_db.update_session_cwd(
session.get("session_key", ""), cwd
)
owner = contextlib.nullcontext(db) if db is not None else _session_db(session)
with owner as owner_db:
if owner_db is None:
return None
generation = owner_db.update_session_cwd(session.get("session_key", ""), cwd)
except Exception:
logger.debug("failed to persist session cwd", exc_info=True)
return None
if (
isinstance(generation, bool)
or not isinstance(generation, int)
or generation < 1
):
if not _workdir_valid_generation(generation):
return None
_persist_session_git_meta(session, cwd, generation)
return generation
@@ -880,15 +637,13 @@ def _set_session_cwd(session: dict, cwd: str) -> str:
if not os.path.isdir(resolved):
raise ValueError(f"working directory does not exist: {cwd}")
session["cwd"] = resolved
# An explicit user choice — persist it as the workspace (and let a later
# lazy row creation persist it too, not the launch-dir fallback).
# An explicit user choice: persisted as the workspace (not the launch-dir
# fallback) and superseding any settle-adopted cwd.
session["explicit_cwd"] = True
# A user's choice supersedes any earlier settle-adopted cwd: from here on
# the terminal wandering must not move the workspace again.
session["cwd_from_settle"] = False
_register_session_cwd(session)
# The synchronous DB write claims ordering authority; Git subprocesses stay
# off the hot path and may publish only for that exact generation.
# The synchronous DB write claims ordering authority; git probes may
# publish only for that exact generation.
_persist_session_cwd_and_schedule_git_meta(session, resolved)
try:
from tools.terminal_tool import cleanup_vm
+177 -174
View File
@@ -12,13 +12,15 @@ from .method_ctx import HandlerRegistry, bind_module
_registry = HandlerRegistry()
# waste AND feeds the Ink render-tree blowup that silently OOM-killed the TUI
# parent (#34095). Cap here to match the render budget (a hair more, so the
# "[omitted …]" label is still informative when output is genuinely large).
# Full output stays in the agent context and the SQLite session, untouched.
# Verbose tool text is capped to the Ink render budget (a hair more, so the
# "[omitted …]" label stays informative): unbounded output fed a render-tree
# blowup that OOM-killed the TUI parent. Full output stays in the agent context
# and the SQLite session, untouched.
_TUI_VERBOSE_TEXT_MAX_CHARS = 1_000
_TUI_VERBOSE_TEXT_MAX_LINES = 16
_TODO_TOOL_NAMES = ("todo_list", "todo") # legacy alias: pre-rename replays
def _cap_tui_verbose_text(text: str) -> str:
if (
@@ -48,8 +50,7 @@ def _cap_tui_verbose_text(text: str) -> str:
omitted_lines = text[:start].count("\n")
if omitted_lines:
label = (
"[showing verbose tail; omitted "
f"{omitted_lines} lines / {omitted_chars} chars]\n"
"[showing verbose tail; omitted " f"{omitted_lines} lines / {omitted_chars} chars]\n"
)
else:
label = f"[showing verbose tail; omitted {omitted_chars} chars]\n"
@@ -141,14 +142,23 @@ def _normalize_todo_state(value: object) -> dict | None:
except (TypeError, ValueError):
return None
todos = list(value["todos"])
# Unused TodoStore snapshot() is {todos: [], revision: 0}. Attaching
# that on resume stamps a client watermark and blocks unversioned
# tool.start merges. An empty list at revision >= 1 is a real clear.
# Unused TodoStore snapshot() is {todos: [], revision: 0}: attaching it on
# resume stamps a client watermark and blocks unversioned tool.start merges.
# An empty list at revision >= 1 is a real clear.
if not todos and revision == 0:
return None
return {"todos": todos, "revision": revision}
def _cache_todo_state(session: dict, state: dict | None) -> None:
"""Keep the newest snapshot on the session (revision-monotonic)."""
if state is None:
return
cached = _normalize_todo_state(session.get("todo_state"))
if cached is None or state["revision"] >= cached["revision"]:
session["todo_state"] = state
def _session_todo_state(session: dict) -> dict | None:
"""Return the newest live/cached todo snapshot for a runtime session."""
cached = _normalize_todo_state(session.get("todo_state"))
@@ -180,15 +190,9 @@ def _attach_todo_state(payload: dict, session: dict) -> dict:
def _todo_state_from_history(history) -> dict | None:
"""Derive the latest todo snapshot from an already-loaded transcript.
Used by resume paths that answer before an AIAgent (and its live
TodoStore) exists. The canonical todo tool results already persist in
conversation history as ordinary tool messages, so the latest one paired
with an assistant ``todo`` tool call IS the durable snapshot — no side
table and no extra transcript read (each resume path passes the history
it already loaded).
"""
"""Latest todo snapshot from an already-loaded transcript, for resume paths
that answer before an AIAgent (and its live TodoStore) exists: the newest
tool result paired with an assistant ``todo`` call IS the durable snapshot."""
if not isinstance(history, list) or not history:
return None
try:
@@ -199,7 +203,7 @@ def _todo_state_from_history(history) -> dict | None:
if not isinstance(msg, dict):
continue
for call in msg.get("tool_calls") or []:
if (call.get("function") or {}).get("name") in ("todo_list", "todo"):
if (call.get("function") or {}).get("name") in _TODO_TOOL_NAMES:
cid = call.get("id")
if cid:
todo_call_ids.add(cid)
@@ -245,19 +249,16 @@ def _on_tool_start(sid: str, tool_call_id: str, name: str, args: dict):
"name": name,
"context": _tool_ctx(name, args),
}
# The desktop renders the expanded tool row (the `$` transcript) from
# the args of the part, and `context` is an 80-char display preview.
# tool.complete already ships full args to every client. When
# tool.start ships them too, the expanded row is complete while the
# tool runs, at the cost of one duplicate transient payload per call.
# Full args here (not just the 80-char `context` preview) so the desktop's
# expanded tool row is complete while the tool runs; tool.complete ships
# them again. args.todos may be a partial merge — tool.complete is the
# source of truth for todos.
if args:
payload["args"] = args
if _session_verbose(sid):
args_text = _tool_args_text(args)
if args_text:
payload["args_text"] = args_text
# tool.complete is the source of truth for todos (full list from the
# tool result). args.todos here may be a partial merge update.
_emit("tool.start", sid, payload)
@@ -284,14 +285,12 @@ def _on_tool_complete(sid: str, tool_call_id: str, name: str, args: dict, result
if result_text:
payload["result_text"] = result_text
todo_state = None
if name in ("todo_list", "todo"): # legacy alias: pre-rename replays
if name in _TODO_TOOL_NAMES:
todo_state = _normalize_todo_state(payload.get("result"))
if todo_state is not None:
payload.update(todo_state)
if session is not None:
cached = _normalize_todo_state(session.get("todo_state"))
if cached is None or todo_state["revision"] >= cached["revision"]:
session["todo_state"] = todo_state
_cache_todo_state(session, todo_state)
try:
from agent.display import render_edit_diff_with_delta
@@ -310,16 +309,154 @@ def _on_tool_complete(sid: str, tool_call_id: str, name: str, args: dict, result
_tool_progress_enabled(sid)
or payload.get("inline_diff")
or _tool_lifecycle_required_for_ui(name)
or name in ("todo_list", "todo")
or name in _TODO_TOOL_NAMES
):
_emit("tool.complete", sid, payload)
# Task state is application data, not optional tool-progress chrome. A
# dedicated full-snapshot event lets every client reconcile immediately
# without interpreting provider text or partial merge arguments.
# Task state is application data, not tool-progress chrome: a dedicated
# full-snapshot event lets every client reconcile without parsing tool args.
if todo_state is not None:
_emit("todo.updated", sid, todo_state)
# ── _on_tool_progress dispatch ─────────────────────────────────────────────
# Each handler takes (sid, name, preview, kw). `tool.started` is dropped on
# purpose: _on_tool_start already emits the authoritative tool.start with the
# stable id and args; an id-less duplicate row makes the desktop live view
# diverge from hydrated history.
def _progress_output_risk(sid, name, preview, kw):
metadata = kw.get("risk_metadata")
if not isinstance(metadata, dict):
return
_emit("tool.output_risk", sid, {
"tool_id": str(kw.get("tool_call_id") or ""), "name": str(name),
"risk": str(metadata.get("risk") or "low"),
"findings": [str(item) for item in metadata.get("findings", [])],
"redacted": bool(metadata.get("redacted", False)),
})
def _progress_reasoning(sid, name, preview, kw):
payload: dict[str, object] = {"text": str(preview)}
if _session_verbose(sid):
payload["verbose"] = True
_emit("reasoning.available", sid, payload)
def _progress_moa_reference(sid, name, preview, kw):
# MoA reference-model output, rendered as a labelled block before the
# aggregator's response. `name` is the slot label, `preview` the text.
ref_payload: dict[str, object] = {
"label": str(name),
"text": str(preview or ""),
}
if kw.get("moa_index") is not None:
ref_payload["index"] = kw.get("moa_index")
if kw.get("moa_count") is not None:
ref_payload["count"] = kw.get("moa_count")
_emit("moa.reference", sid, ref_payload)
def _progress_moa_aggregating(sid, name, preview, kw):
_emit("moa.aggregating", sid, {"aggregator": str(name or "")})
def _progress_moa_progress(sid, name, preview, kw):
# Drives the status-bar `MOA: 2/3 refs done`; both counters required so the
# client renders deterministically.
refs_done = kw.get("moa_refs_done")
refs_total = kw.get("moa_refs_total")
if refs_done is None or refs_total is None:
return
_emit("moa.progress", sid, {
"label": str(name or ""), "refs_done": int(refs_done), "refs_total": int(refs_total),
})
def _progress_moa_phase(sid, name, preview, kw):
# Currently only phase="aggregator" fires, once fan-out completes.
phase = kw.get("moa_phase")
if not phase:
return
phase_payload: dict[str, object] = {"phase": str(phase)}
refs_done = kw.get("moa_refs_done")
refs_total = kw.get("moa_refs_total")
if refs_done is not None:
phase_payload["refs_done"] = int(refs_done)
if refs_total is not None:
phase_payload["refs_total"] = int(refs_total)
if name:
phase_payload["aggregator"] = str(name)
_emit("moa.phase", sid, phase_payload)
# Per-branch rollups emitted on subagent.complete.
_SUBAGENT_INT_FIELDS = ("input_tokens", "output_tokens", "reasoning_tokens", "api_calls")
def _progress_subagent(sid, name, preview, kw, event_type):
# Identity fields are all optional: older emitters omit them and the TUI
# spawn tree falls back to flat rendering.
payload = {
"goal": str(kw.get("goal") or ""), "task_count": int(kw.get("task_count") or 1),
"task_index": int(kw.get("task_index") or 0),
}
for key in ("subagent_id", "parent_id", "child_session_id", "delegation_id"):
if kw.get(key):
payload[key] = str(kw[key])
if kw.get("depth") is not None:
payload["depth"] = int(kw["depth"])
if kw.get("model"):
payload["model"] = str(kw["model"])
if kw.get("tool_count") is not None:
payload["tool_count"] = int(kw["tool_count"])
if kw.get("toolsets"):
payload["toolsets"] = [str(t) for t in kw["toolsets"]]
for int_key in _SUBAGENT_INT_FIELDS:
val = kw.get(int_key)
if val is not None:
try:
payload[int_key] = int(val)
except (TypeError, ValueError):
pass
for key in ("files_read", "files_written"):
if kw.get(key):
payload[key] = [str(p) for p in kw[key]]
if kw.get("output_tail"):
payload["output_tail"] = list(kw["output_tail"]) # list of dicts
if name:
payload["tool_name"] = str(name)
if preview:
payload["text"] = str(preview)
if kw.get("status"):
payload["status"] = str(kw["status"])
if kw.get("summary"):
payload["summary"] = str(kw["summary"])
if kw.get("duration_seconds") is not None:
payload["duration_seconds"] = float(kw["duration_seconds"])
if preview and event_type == "subagent.tool":
payload["tool_preview"] = str(preview)
payload["text"] = str(preview)
# subagent.text is the child's per-token reply, relayed solely to feed a
# watch window's live mirror (keyed off the child sid); on the parent it's
# hundreds of ignored frames, so skip that emit.
if event_type != "subagent.text":
_emit(event_type, sid, payload)
_mirror_subagent_to_child(event_type, payload)
# event_type -> (handler, requires) where `requires` names the arg that must be
# truthy for the row to be emitted at all ("name" / "preview" / None).
_PROGRESS_HANDLERS = {
"tool.output_risk": (_progress_output_risk, "name"),
"reasoning.available": (_progress_reasoning, "preview"),
"moa.reference": (_progress_moa_reference, "name"),
"moa.aggregating": (_progress_moa_aggregating, None),
"moa.progress": (_progress_moa_progress, None), "moa.phase": (_progress_moa_phase, None),
}
def _on_tool_progress(
sid: str,
event_type: str,
@@ -331,149 +468,15 @@ def _on_tool_progress(
if not _tool_progress_enabled(sid):
return
if event_type == "tool.started" and name:
# `_on_tool_start` already emits the authoritative `tool.start` with
# the stable tool id and args. Emitting another id-less progress row
# here makes the desktop live view diverge from hydrated history.
return
if event_type == "tool.output_risk" and name:
metadata = _kwargs.get("risk_metadata")
if not isinstance(metadata, dict):
return
payload: dict[str, object] = {
"tool_id": str(_kwargs.get("tool_call_id") or ""),
"name": str(name),
"risk": str(metadata.get("risk") or "low"),
"findings": [str(item) for item in metadata.get("findings", [])],
"redacted": bool(metadata.get("redacted", False)),
}
_emit("tool.output_risk", sid, payload)
return
if event_type == "reasoning.available" and preview:
payload: dict[str, object] = {"text": str(preview)}
if _session_verbose(sid):
payload["verbose"] = True
_emit("reasoning.available", sid, payload)
return
if event_type == "moa.reference" and name:
# MoA reference-model output — relay as a labelled block the Ink/desktop
# client renders before the aggregator's response (like a thinking
# block, tagged with the source model). `name` is the slot label,
# `preview` is the reference text.
ref_payload: dict[str, object] = {
"label": str(name),
"text": str(preview or ""),
}
if _kwargs.get("moa_index") is not None:
ref_payload["index"] = _kwargs.get("moa_index")
if _kwargs.get("moa_count") is not None:
ref_payload["count"] = _kwargs.get("moa_count")
_emit("moa.reference", sid, ref_payload)
return
if event_type == "moa.aggregating":
_emit("moa.aggregating", sid, {"aggregator": str(name or "")})
return
if event_type == "moa.progress":
# Per-reference completion — drives the status-bar progress indicator
# (`MOA: 2/3 refs done`) requested in issue #59546. Only emitted when
# both counters are present so the client can render deterministically.
refs_done = _kwargs.get("moa_refs_done")
refs_total = _kwargs.get("moa_refs_total")
if refs_done is None or refs_total is None:
return
_emit(
"moa.progress",
sid,
{
"label": str(name or ""),
"refs_done": int(refs_done),
"refs_total": int(refs_total),
},
)
return
if event_type == "moa.phase":
# Phase transition — currently only ``phase="aggregator"`` fires once
# the fan-out completes and the aggregator is about to act. Tells the
# client which phase of the MoA pipeline is currently running so it
# can swap status-bar copy accordingly.
phase = _kwargs.get("moa_phase")
if not phase:
return
phase_payload: dict[str, object] = {"phase": str(phase)}
refs_done = _kwargs.get("moa_refs_done")
refs_total = _kwargs.get("moa_refs_total")
if refs_done is not None:
phase_payload["refs_done"] = int(refs_done)
if refs_total is not None:
phase_payload["refs_total"] = int(refs_total)
if name:
phase_payload["aggregator"] = str(name)
_emit("moa.phase", sid, phase_payload)
entry = _PROGRESS_HANDLERS.get(event_type)
if entry is not None:
handler, requires = entry
if requires is None or {"name": name, "preview": preview}[requires]:
handler(sid, name, preview, _kwargs)
return
if event_type.startswith("subagent."):
payload = {
"goal": str(_kwargs.get("goal") or ""),
"task_count": int(_kwargs.get("task_count") or 1),
"task_index": int(_kwargs.get("task_index") or 0),
}
# Identity fields for the TUI spawn tree. All optional — older
# emitters that omit them fall back to flat rendering client-side.
if _kwargs.get("subagent_id"):
payload["subagent_id"] = str(_kwargs["subagent_id"])
if _kwargs.get("parent_id"):
payload["parent_id"] = str(_kwargs["parent_id"])
if _kwargs.get("child_session_id"):
payload["child_session_id"] = str(_kwargs["child_session_id"])
if _kwargs.get("delegation_id"):
payload["delegation_id"] = str(_kwargs["delegation_id"])
if _kwargs.get("depth") is not None:
payload["depth"] = int(_kwargs["depth"])
if _kwargs.get("model"):
payload["model"] = str(_kwargs["model"])
if _kwargs.get("tool_count") is not None:
payload["tool_count"] = int(_kwargs["tool_count"])
if _kwargs.get("toolsets"):
payload["toolsets"] = [str(t) for t in _kwargs["toolsets"]]
# Per-branch rollups emitted on subagent.complete (features 1+2+4).
for int_key in (
"input_tokens",
"output_tokens",
"reasoning_tokens",
"api_calls",
):
val = _kwargs.get(int_key)
if val is not None:
try:
payload[int_key] = int(val)
except (TypeError, ValueError):
pass
if _kwargs.get("files_read"):
payload["files_read"] = [str(p) for p in _kwargs["files_read"]]
if _kwargs.get("files_written"):
payload["files_written"] = [str(p) for p in _kwargs["files_written"]]
if _kwargs.get("output_tail"):
payload["output_tail"] = list(_kwargs["output_tail"]) # list of dicts
if name:
payload["tool_name"] = str(name)
if preview:
payload["text"] = str(preview)
if _kwargs.get("status"):
payload["status"] = str(_kwargs["status"])
if _kwargs.get("summary"):
payload["summary"] = str(_kwargs["summary"])
if _kwargs.get("duration_seconds") is not None:
payload["duration_seconds"] = float(_kwargs["duration_seconds"])
if preview and event_type == "subagent.tool":
payload["tool_preview"] = str(preview)
payload["text"] = str(preview)
# subagent.text is the child's per-token reply, relayed solely to feed a
# watch window's live mirror. It is meaningless on the parent session
# (which shows the child via the spawn tree, not its reply body), so
# skip the parent emit — sending hundreds of ignored token frames there
# is wasted traffic and a trap for any future parent-side subagent
# catch-all. The mirror keys off the child sid and is unaffected.
if event_type != "subagent.text":
_emit(event_type, sid, payload)
_mirror_subagent_to_child(event_type, payload)
_progress_subagent(sid, name, preview, _kwargs, event_type)
def register(server) -> None: