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:
@@ -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
@@ -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:
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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()
|
||||
|
||||
@@ -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"]:
|
||||
|
||||
Reference in New Issue
Block a user