From ea4310e76c211a93670268a98d4ff2fd0d51a0cc Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Sun, 16 Aug 2026 12:45:02 -0700 Subject: [PATCH] feat(agent): capability-refresh + timeless prompts for eternal Bot Chat sessions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bot Chats break the "new sessions come often" assumption behind build-once system prompts: capability edits used to sit invisible until /new or compression, and the frozen birth date became misinformation. - tools/bot_mode_probe.py: capability_fingerprint() hashes the profile's capability surface (disabled skills, toolset pins, MCP config, SOUL.md, installed skills, Bot-Mode roster); Bot Chat prompts embed the 12-hex epoch stamp - agent/conversation_loop.py restore path: stored Bot Chat prompt whose epoch mismatches disk → ONE rebuild (through a cleared skills-prompt cache so new installs appear), persisted so the next turn reuses the new bytes verbatim. Prompts without a stamp — every non-Bot-Chat session — never take the branch; probe failure fails closed to reuse - agent/system_prompt.py: Bot Chat prompts are timeless — the "Conversation started:" date is dropped (timezone kept); no ticking fields in an eternal session - tui_gateway: _sync_bot_capabilities at turn start rebuilds the live agent (tool definitions are construction-baked) when the fingerprint moves, same session id/history, with a user-visible notice Cache stance: this is the /model exception applied to capabilities — a loud, user-initiated, once-per-change prefix break. Unchanged state hashes identically and stored bytes are reused verbatim (E2E-proven). Validation: 9 probe unit tests incl. per-axis fingerprint changes; E2E v3 against the real restore path (fresh build → verbatim reuse → skill install → single refresh w/ new skill in index → verbatim reuse; regular sessions dated, unstamped, never refreshed); tests/agent/ 4647/4647. --- agent/conversation_loop.py | 59 +++++++++++++++++ agent/system_prompt.py | 22 ++++++- tests/tools/test_bot_mode_probe.py | 68 +++++++++++++++++++ tools/bot_mode_probe.py | 102 +++++++++++++++++++++++++++++ tui_gateway/server.py | 71 ++++++++++++++++++++ 5 files changed, 321 insertions(+), 1 deletion(-) diff --git a/agent/conversation_loop.py b/agent/conversation_loop.py index 9b37cbfa90..9efa25ad0a 100644 --- a/agent/conversation_loop.py +++ b/agent/conversation_loop.py @@ -780,6 +780,65 @@ def _restore_or_build_system_prompt(agent, system_message, conversation_history) ) if stored_prompt and _stored_prompt_matches_runtime(agent, stored_prompt): + # Bot Chat capability epoch: an eternal bot session must adopt + # user-initiated capability changes (skills/toolsets/MCP/SOUL/roster) + # on the next message, not at /new or compression. The stored prompt + # embeds a fingerprint of the capability surface; a mismatch against + # disk is a deliberate, once-per-change rebuild — the /model + # exception applied to capabilities. Prompts without the stamp + # (every non-Bot-Chat session) never take this branch, and the check + # fails closed to "reuse" so a probe failure can't burn cache. + _bot_stale = False + try: + from tools.bot_mode_probe import stored_prompt_capability_stale + + _home_for_epoch = None + try: + from agent.system_prompt import _agent_home + + _home_for_epoch = _agent_home(agent) + except Exception: + pass + _bot_stale = stored_prompt_capability_stale(stored_prompt, _home_for_epoch) + except Exception: + _bot_stale = False + if _bot_stale: + logger.info( + "Bot Chat capability epoch changed for session %s; rebuilding " + "system prompt to adopt the new capability surface (one-time " + "prefix-cache break).", + agent.session_id, + ) + agent._session_title_hint = "Bot Chat" + # The skills index inside the prompt comes from a two-layer cache + # (in-process LRU + disk snapshot) that doesn't watch the skills + # dir; a capability refresh must rebuild THROUGH it or a freshly + # installed skill stays invisible in the new prompt. + try: + from agent.prompt_builder import clear_skills_system_prompt_cache + + clear_skills_system_prompt_cache(clear_snapshot=True) + except Exception: + pass + agent._cached_system_prompt = agent._build_system_prompt(system_message) + agent._bot_capability_refreshed = True + # Persist the refreshed prompt so the NEXT turn restores the new + # bytes verbatim — the cache break is once per capability change, + # never per turn. (on_session_start deliberately not re-fired: + # this is a continuation, not a new session.) + if agent._session_db: + try: + agent._session_db.update_system_prompt( + agent.session_id, agent._cached_system_prompt + ) + except Exception as exc: + logger.warning( + "Session DB update_system_prompt failed after Bot Chat " + "capability refresh (session=%s): %s. The refresh will " + "re-fire next turn.", + agent.session_id, exc, + ) + return # Continuing session — reuse the exact system prompt from the # previous turn so the Anthropic cache prefix matches. agent._cached_system_prompt = stored_prompt diff --git a/agent/system_prompt.py b/agent/system_prompt.py index a7d707ffd8..2e2579a79c 100644 --- a/agent/system_prompt.py +++ b/agent/system_prompt.py @@ -594,7 +594,11 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None) # Gated by config.yaml ``agent.bot_mode_protocol`` (default True). if getattr(agent, "_bot_mode_protocol", True): try: - from tools.bot_mode_probe import BOT_CHAT_TITLE, get_bot_mode_protocol_section + from tools.bot_mode_probe import ( + BOT_CHAT_TITLE, + epoch_line, + get_bot_mode_protocol_section, + ) _title = str(getattr(agent, "_session_title_hint", "") or "").strip() if not _title: _sdb = getattr(agent, "_session_db", None) @@ -604,6 +608,16 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None) _bot_section = get_bot_mode_protocol_section(_agent_home(agent)) if _bot_section: post_workspace_parts.append(_bot_section) + # Eternal-session support: stamp the capability epoch so + # the restore path can detect user-initiated capability + # changes (skills/toolsets/MCP/SOUL/roster) and rebuild + # ONCE per change instead of waiting for /new or + # compression. Also marks this prompt as timeless — the + # volatile timestamp line is omitted (see below), since a + # birth date pinned in a session that lives for months is + # misinformation. + post_workspace_parts.append(epoch_line(_agent_home(agent))) + agent._bot_chat_timeless_prompt = True except Exception: pass @@ -825,6 +839,12 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None) timestamp_line = ( f"Conversation started: {now.strftime('%A, %B %d, %Y')}{_zone_suffix}" ) + # Bot Chat sessions are effectively eternal — a birth date frozen in the + # prompt becomes confidently-wrong misinformation within days. Timeless + # prompts keep the identity lines but drop the date (the timezone still + # rides workspace context; live time comes from the terminal tool). + if getattr(agent, "_bot_chat_timeless_prompt", False): + timestamp_line = f"Timezone: {', '.join(_zone_bits)}" if _zone_bits else "" if agent.pass_session_id and agent.session_id: timestamp_line += f"\nSession ID: {agent.session_id}" if agent.model: diff --git a/tests/tools/test_bot_mode_probe.py b/tests/tools/test_bot_mode_probe.py index ffec95bf68..abc2d5d672 100644 --- a/tests/tools/test_bot_mode_probe.py +++ b/tests/tools/test_bot_mode_probe.py @@ -101,3 +101,71 @@ def test_never_raises_on_garbage(tmp_path, monkeypatch): monkeypatch.setattr(bot_mode_probe, "_roster", lambda root: (_ for _ in ()).throw(OSError("boom"))) bot_mode_probe._reset_cache_for_tests() assert bot_mode_probe.get_bot_mode_protocol_section(home) == "" + + +# ── capability epoch ───────────────────────────────────────────────────────── + + +def test_fingerprint_stable_when_nothing_changes(tmp_path): + home = tmp_path / ".hermes" + home.mkdir() + _make_bot_profile(home, "researcher", managed=True) + assert bot_mode_probe.capability_fingerprint(home) == bot_mode_probe.capability_fingerprint(home) + + +def test_fingerprint_changes_on_each_capability_axis(tmp_path): + home = tmp_path / ".hermes" + home.mkdir() + _make_bot_profile(home, "researcher", managed=True) + base = bot_mode_probe.capability_fingerprint(home) + + # new skill installed + skill = home / "skills" / "web" / "scraping" + skill.mkdir(parents=True) + (skill / "SKILL.md").write_text("---\nname: scraping\n---\n", encoding="utf-8") + after_skill = bot_mode_probe.capability_fingerprint(home) + assert after_skill != base + + # toolset pin changed + (home / "config.yaml").write_text("tools:\n enabled_toolsets: [web]\n", encoding="utf-8") + after_tools = bot_mode_probe.capability_fingerprint(home) + assert after_tools != after_skill + + # MCP server added + (home / "config.yaml").write_text( + "tools:\n enabled_toolsets: [web]\nmcp_servers:\n github:\n preset: github\n", + encoding="utf-8", + ) + after_mcp = bot_mode_probe.capability_fingerprint(home) + assert after_mcp != after_tools + + # SOUL edited + (home / "SOUL.md").write_text("# New identity\n", encoding="utf-8") + after_soul = bot_mode_probe.capability_fingerprint(home) + assert after_soul != after_mcp + + # teammate added to the roster + _make_bot_profile(home, "coder", managed=True) + assert bot_mode_probe.capability_fingerprint(home) != after_soul + + +def test_stored_prompt_staleness(tmp_path): + home = tmp_path / ".hermes" + home.mkdir() + _make_bot_profile(home, "researcher", managed=True) + + stamped = "system stuff\n\n" + bot_mode_probe.epoch_line(home) + # unchanged surface → not stale (cache preserved) + assert not bot_mode_probe.stored_prompt_capability_stale(stamped, home) + + # capability change → stale exactly once + skill = home / "skills" / "new-skill" + skill.mkdir(parents=True) + (skill / "SKILL.md").write_text("---\nname: new-skill\n---\n", encoding="utf-8") + assert bot_mode_probe.stored_prompt_capability_stale(stamped, home) + restamped = "system stuff\n\n" + bot_mode_probe.epoch_line(home) + assert not bot_mode_probe.stored_prompt_capability_stale(restamped, home) + + # prompts without a stamp (every non-Bot-Chat session) are never stale + assert not bot_mode_probe.stored_prompt_capability_stale("ordinary prompt", home) + assert not bot_mode_probe.stored_prompt_capability_stale("", home) diff --git a/tools/bot_mode_probe.py b/tools/bot_mode_probe.py index 97bc57c684..3e7a70988c 100644 --- a/tools/bot_mode_probe.py +++ b/tools/bot_mode_probe.py @@ -158,6 +158,108 @@ def get_bot_mode_protocol_section(home: str | os.PathLike | None = None, *, forc return _cached[resolved] +# ── capability epoch ───────────────────────────────────────────────────────── +# +# Bot Chat sessions are effectively eternal — the "new sessions come along +# often" assumption behind build-once system prompts does not hold. When the +# user changes a bot's capabilities (skills, toolsets, MCP servers, SOUL) or +# the teammate roster changes, they expect the change to work on the NEXT +# message. The fingerprint below hashes exactly that capability surface; the +# built Bot Chat prompt embeds it, and the restore path in +# agent/conversation_loop.py rebuilds the prompt when the stored epoch no +# longer matches the disk state. This is the /model exception applied to +# capabilities: a LOUD, USER-INITIATED, once-per-change cache break — never +# a per-turn drift (unchanged state hashes identically and the stored bytes +# are reused verbatim). + +_EPOCH_PREFIX = "Capability epoch: " +_EPOCH_RE_TEXT = r"Capability epoch: ([0-9a-f]{12})" + + +def capability_fingerprint(home: str | os.PathLike | None = None) -> str: + """12-hex digest of the capability surface for ``home``'s profile. + + Sources: the profile's disabled skills + enabled toolsets + MCP server + config (config.yaml), SOUL.md bytes, installed skill names, and the + Bot-Mode roster (managed profile names). Deliberately NOT cached — the + whole point is detecting on-disk drift; callers compare it against the + epoch embedded in a stored prompt. Never raises. + """ + import hashlib + import json + + resolved = Path(str(home) if home else (os.getenv("HERMES_HOME") or os.path.expanduser("~/.hermes"))) + surface: dict = {} + try: + import yaml + + cfg_path = resolved / "config.yaml" + cfg = {} + if cfg_path.is_file(): + cfg = yaml.safe_load(cfg_path.read_text(encoding="utf-8", errors="replace")) or {} + skills_cfg = cfg.get("skills") if isinstance(cfg.get("skills"), dict) else {} + tools_cfg = cfg.get("tools") if isinstance(cfg.get("tools"), dict) else {} + skills_cfg = skills_cfg or {} + tools_cfg = tools_cfg or {} + surface["disabled_skills"] = sorted(str(s).lower() for s in (skills_cfg.get("disabled") or [])) + surface["enabled_toolsets"] = sorted(str(t) for t in (tools_cfg.get("enabled_toolsets") or [])) + mcp = cfg.get("mcp_servers") + surface["mcp"] = json.dumps(mcp, sort_keys=True, default=str) if isinstance(mcp, dict) else "" + except Exception: + pass + try: + soul = resolved / "SOUL.md" + surface["soul"] = hashlib.sha256(soul.read_bytes()).hexdigest() if soul.is_file() else "" + except Exception: + surface["soul"] = "" + try: + names = [] + skills_root = resolved / "skills" + if skills_root.is_dir(): + for skill_md in skills_root.glob("**/SKILL.md"): + names.append(str(skill_md.parent.relative_to(skills_root))) + surface["skills"] = sorted(names) + except Exception: + surface["skills"] = [] + try: + root = _hermes_root(resolved) + surface["roster"] = sorted(n for n, d in _roster(root) if _is_bot_managed(d)) + except Exception: + surface["roster"] = [] + try: + blob = json.dumps(surface, sort_keys=True).encode("utf-8") + return hashlib.sha256(blob).hexdigest()[:12] + except Exception: + return "unavailable" + + +def epoch_line(home: str | os.PathLike | None = None) -> str: + """The epoch stamp appended to a Bot Chat prompt.""" + return f"{_EPOCH_PREFIX}{capability_fingerprint(home)}" + + +def stored_prompt_capability_stale(stored_prompt: str, home: str | os.PathLike | None = None) -> bool: + """True when ``stored_prompt`` is a Bot Chat prompt whose embedded + capability epoch no longer matches the current disk state. + + Non-Bot-Chat prompts (no epoch stamp) are never stale by this check. + Fails closed to "not stale" — a broken probe must never turn into a + rebuild-every-turn cache burner. + """ + import re + + try: + m = re.search(_EPOCH_RE_TEXT, stored_prompt or "") + if not m: + return False + current = capability_fingerprint(home) + if current == "unavailable": + return False + return m.group(1) != current + except Exception: + return False + + def _reset_cache_for_tests() -> None: with _lock: _cached.clear() diff --git a/tui_gateway/server.py b/tui_gateway/server.py index 0fe842ff4d..bd3c38ffde 100644 --- a/tui_gateway/server.py +++ b/tui_gateway/server.py @@ -4950,6 +4950,68 @@ 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. + """ + agent = session.get("agent") + if agent is None: + return + try: + title = str(getattr(agent, "_session_title_hint", "") or "").strip() + if not title: + db = getattr(agent, "_session_db", None) + key = session.get("session_key") or "" + title = str((db.get_session_title(key) if (db and key) else None) or "").strip() + if title != "Bot Chat": + return + from tools.bot_mode_probe import capability_fingerprint + + home = session.get("profile_home") or None + current = capability_fingerprint(home) + if current == "unavailable": + return + seen = session.get("bot_caps_seen") + session["bot_caps_seen"] = current + if seen is None or seen == current: + return + 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), + ) + 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."}, + ) + except Exception as e: + logger.warning("Bot capability sync failed for %s: %s", sid, e) + + def _sync_agent_model_with_config(sid: str, session: dict) -> None: """Adopt a config.yaml model change at turn start, like gateways do per message. Sessions pinned with /model keep their choice; a failed switch @@ -10469,6 +10531,10 @@ def _run_prompt_submit( # child; delegate_task then captures it as non-serializable authority. transport_token = bind_transport(session.get("transport")) runtime_session_token = _current_runtime_session_record.set(session) + # Bound eagerly so the except/finally paths below always have an agent + # even if turn setup throws; re-read after _sync_bot_capabilities, + # which may swap in a rebuilt agent for Bot Chat sessions. + agent = session["agent"] approval_token = None session_tokens = [] home_token = None # per-turn HERMES_HOME override for a resumed remote profile @@ -10529,6 +10595,11 @@ def _run_prompt_submit( # config sync so an explicit pick wins over a config.yaml change. _apply_pending_model_switch(sid, session) _sync_agent_model_with_config(sid, session) + # Bot Chat capability sync — adopt Settings→Capabilities edits + # (skills/toolsets/MCP/SOUL) into the eternal bot session before + # the turn runs. No-op for every other session shape. + _sync_bot_capabilities(sid, session) + agent = session["agent"] # Snapshot after turn-start model sync. A deferred switch mutates # history and its version; that mutation belongs to this turn. with session["history_lock"]: