feat(agent): capability-refresh + timeless prompts for eternal Bot Chat sessions

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.
This commit is contained in:
Teknium
2026-08-16 12:45:02 -07:00
parent 72bae0e91a
commit ea4310e76c
5 changed files with 321 additions and 1 deletions
+59
View File
@@ -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
+21 -1
View File
@@ -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:
+68
View File
@@ -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)
+102
View File
@@ -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()
+71
View File
@@ -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"]: