plugin_api.py 54 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894
  1. """Hermes Achievements dashboard plugin backend, mounted at /api/plugins/hermes-achievements/.
  2. Scans the session history into per-session stats (checkpointed by fingerprint so warm
  3. scans are cheap), aggregates them, and evaluates the tiered / multi-condition catalog.
  4. Cold scans run on a background thread; ``/achievements`` serves the last snapshot.
  5. """
  6. from __future__ import annotations
  7. import json
  8. import math
  9. import re
  10. import threading
  11. import time
  12. from pathlib import Path
  13. from typing import Any, Dict, List, Optional, Set
  14. from fastapi import APIRouter
  15. from hermes_constants import get_hermes_home
  16. router = APIRouter()
  17. SNAPSHOT_TTL_SECONDS = 120
  18. _SCAN_LOCK = threading.Lock()
  19. _SNAPSHOT_CACHE: Optional[dict[str, Any]] = None
  20. _SNAPSHOT_CACHE_AT = 0
  21. # Key order is part of the /scan-status wire shape.
  22. _SCAN_STATUS: dict[str, Any] = {"state": "idle", "started_at": None, "finished_at": None, "last_error": None, "last_duration_ms": None, "run_count": 0}
  23. ERROR_RE = re.compile(r"\b(error|failed|failure|traceback|exception|permission denied|not found|eaddrinuse|already in use|timed out|blocked)\b", re.IGNORECASE)
  24. PORT_RE = re.compile(r"\b(port\s+)?(3000|5173|8000|8080|9119)\b.*\b(in use|already|taken|eaddrinuse)\b|\beaddrinuse\b", re.IGNORECASE)
  25. INSTALL_RE = re.compile(r"\b(npm|pnpm|yarn|pip|uv)\b.*\b(install|add)\b", re.IGNORECASE)
  26. SUCCESS_RE = re.compile(r"\b(success|passed|built|compiled|done|exit_code[\"']?\s*[:=]\s*0|verified|ok)\b", re.IGNORECASE)
  27. FILE_RE = re.compile(r"(?:/home/|~/?|\./|/mnt/)[\w./-]+\.(?:py|js|ts|tsx|jsx|css|html|md|json|yaml|yml|svg|sql|sh)")
  28. TIER_NAMES = ["Copper", "Silver", "Gold", "Diamond", "Olympian"]
  29. def _ach(
  30. id: str, name: str, description: str, category: str, icon: str, *,
  31. metric: Optional[str] = None, tiers: Optional[list[int]] = None,
  32. requires: Optional[list[tuple]] = None, secret: bool = False) -> dict[str, Any]:
  33. """Build one catalog entry. ``kind`` is derived: ``requires`` -> multi_condition; a
  34. ``max_*`` metric is a per-session best (best_session); anything else accumulates over
  35. the whole history (lifetime)."""
  36. kind = "multi_condition" if requires is not None else ("best_session" if metric.startswith("max_") else "lifetime")
  37. item: dict[str, Any] = {"id": id, "name": name, "description": description, "category": category, "kind": kind, "icon": icon}
  38. if secret:
  39. item["secret"] = True
  40. if requires is not None:
  41. item["requirements"] = [{"metric": m, "gte": gte} for m, gte in requires]
  42. else:
  43. item["threshold_metric"] = metric
  44. item["tiers"] = [{"name": n, "threshold": t} for n, t in zip(TIER_NAMES, tiers)]
  45. return item
  46. ACHIEVEMENTS: list[dict[str, Any]] = [
  47. # Agent Autonomy — mostly best-session feats
  48. _ach("let_him_cook", "Let Him Cook", "Let Hermes run a serious autonomous tool chain in one session.", "Agent Autonomy", "flame", metric="max_tool_calls_in_session", tiers=[200, 500, 1200, 3000, 8000]),
  49. _ach("autonomous_avalanche", "Autonomous Avalanche", "Accumulate a lifetime avalanche of Hermes tool calls across sessions.", "Agent Autonomy", "avalanche", metric="total_tool_calls", tiers=[1000, 3000, 8000, 20000, 50000]),
  50. _ach("toolchain_maxxer", "Toolchain Maxxer", "Use a wide spread of distinct Hermes tools in one session.", "Agent Autonomy", "nodes", metric="max_distinct_tools_in_session", tiers=[18, 28, 45, 70, 100]),
  51. _ach("full_send", "Full Send", "Terminal, files, and web/browser all get involved in one real run.", "Agent Autonomy", "rocket", requires=[("max_terminal_calls_in_session", 180), ("max_file_tool_calls_in_session", 120), ("max_web_browser_calls_in_session", 60)]),
  52. _ach("subagent_commander", "Subagent Commander", "Coordinate delegated agent work.", "Agent Autonomy", "branch", metric="total_delegate_calls", tiers=[5, 40, 100, 1000, 5000]),
  53. _ach("background_process_enjoyer", "Background Process Enjoyer", "Start or control enough long-running processes to deserve the title.", "Agent Autonomy", "daemon", metric="total_process_calls", tiers=[300, 800, 2000, 6000, 15000]),
  54. _ach("cron_necromancer", "Cron Necromancer", "Raise scheduled autonomous jobs from the dead.", "Agent Autonomy", "clock", metric="total_cron_calls", tiers=[1000, 3000, 8000, 20000, 50000]),
  55. # Debugging Chaos — higher thresholds + multi-condition events
  56. _ach("red_text_connoisseur", "Red Text Connoisseur", "Encounter enough errors to develop a palate for red text.", "Debugging Chaos", "warning", metric="total_errors", tiers=[1500, 4000, 10000, 25000, 75000]),
  57. _ach("stack_trace_sommelier", "Stack Trace Sommelier", "Taste tracebacks by the flight, not by the sip.", "Debugging Chaos", "wine", metric="traceback_events", tiers=[300, 1000, 3000, 8000, 20000]),
  58. _ach("actually_read_the_logs", "Actually Read The Logs", "Inspect logs repeatedly instead of guessing.", "Debugging Chaos", "scroll", metric="log_read_events", tiers=[1000, 3000, 8000, 20000, 50000]),
  59. _ach("port_3000_taken", "Port 3000 Is Taken", "Discover dev-server port conflict patterns enough times to become numb.", "Debugging Chaos", "plug", metric="port_conflict_events", tiers=[15, 40, 100, 300, 1000], secret=True),
  60. _ach("permission_denied_any_percent", "Permission Denied Any%", "Speedrun into permission walls.", "Debugging Chaos", "lock", metric="permission_denied_events", tiers=[25, 75, 200, 600, 1500], secret=True),
  61. _ach("dependency_hell_tourist", "Dependency Hell Tourist", "Package installs fail, then somehow life continues.", "Debugging Chaos", "package_skull", requires=[("install_error_events", 25), ("install_success_events", 10)]),
  62. _ach("the_fix_was_restarting", "The Fix Was Restarting It", "Restart after enough error clusters to call it a technique.", "Debugging Chaos", "restart", requires=[("restart_after_error_events", 50), ("total_errors", 4000)]),
  63. _ach("forgot_the_env_var", "Forgot The Env Var", "Auth or configuration failed because an environment variable was missing.", "Debugging Chaos", "key", metric="env_var_error_events", tiers=[5000, 15000, 40000, 100000, 250000], secret=True),
  64. _ach("yaml_colon_incident", "YAML Colon Incident", "Configuration syntax bites back.", "Debugging Chaos", "colon", metric="yaml_error_events", tiers=[1000, 3000, 8000, 20000, 50000], secret=True),
  65. _ach("docker_name_collision", "Docker Name Collision", "A container name already exists. Of course it does.", "Debugging Chaos", "container", metric="docker_conflict_events", tiers=[75, 200, 600, 1500, 4000], secret=True),
  66. # Vibe Coding
  67. _ach("supposed_to_be_quick", "This Was Supposed To Be Quick", "A tiny ask becomes an entire expedition.", "Vibe Coding", "melting_clock", metric="max_messages_in_session", tiers=[300, 600, 1200, 2500, 6000]),
  68. _ach("one_more_small_change", "One More Small Change", "Make enough file edits in one session to invalidate the phrase small change.", "Vibe Coding", "pencil", metric="max_file_tool_calls_in_session", tiers=[150, 400, 1000, 3000, 8000]),
  69. _ach("vibe_architect", "Vibe Architect", "Touch a broad surface area in one project session.", "Vibe Coding", "blueprint", metric="max_files_touched_in_session", tiers=[300, 700, 1500, 4000, 10000]),
  70. _ach("pixel_goblin", "Pixel Goblin", "Do sustained frontend, CSS, SVG, or visual tuning.", "Vibe Coding", "pixel", metric="frontend_activity_events", tiers=[20000, 50000, 120000, 300000, 800000]),
  71. _ach("ship_first_ask_later", "Ship First, Ask Later", "Git activity after a serious tool chain.", "Vibe Coding", "ship", requires=[("git_events", 50), ("max_tool_calls_in_session", 500)]),
  72. _ach("css_exorcist", "CSS Exorcist", "Cast repeated styling demons out of the interface.", "Vibe Coding", "spark_cursor", metric="css_activity_events", tiers=[10000, 30000, 80000, 200000, 500000]),
  73. _ach("one_character_fix", "One Character Fix", "A tiny edit after a pile of errors. Painful. Beautiful.", "Vibe Coding", "needle", requires=[("tiny_patch_after_errors_events", 5), ("total_errors", 4000)], secret=True),
  74. # Hermes Native
  75. _ach("skillsmith", "Skillsmith", "Work with Hermes skills enough to leave fingerprints.", "Hermes Native", "hammer_scroll", metric="skill_events", tiers=[5000, 15000, 40000, 100000, 250000]),
  76. _ach("skill_issue_skill_created", "Skill Issue? Skill Created.", "Create or patch durable procedures instead of repeating yourself.", "Hermes Native", "anvil", metric="skill_manage_events", tiers=[25, 75, 200, 600, 1500]),
  77. _ach("memory_keeper", "Memory Keeper", "Persist durable knowledge with memory or Mnemosyne.", "Hermes Native", "crystal", metric="memory_events", tiers=[100, 300, 1000, 3000, 8000]),
  78. _ach("memory_palace", "Memory Palace", "Build a serious durable-memory trail.", "Hermes Native", "palace", metric="memory_write_events", tiers=[100, 300, 1000, 3000, 8000]),
  79. _ach("context_dragon", "Context Dragon", "Brush against compression, huge context, or token pressure repeatedly.", "Hermes Native", "dragon", metric="context_events", tiers=[5000, 15000, 40000, 100000, 250000]),
  80. _ach("gateway_dweller", "Gateway Dweller", "Live through gateway-connected Hermes workflows.", "Hermes Native", "antenna", metric="gateway_events", tiers=[5000, 15000, 40000, 100000, 250000]),
  81. _ach("plugin_goblin", "Plugin Goblin", "Use or develop plugins enough that the dashboard notices.", "Hermes Native", "puzzle", metric="plugin_events", tiers=[1000, 3000, 8000, 20000, 50000]),
  82. _ach("rollback_wizard", "Rollback Wizard", "Invoke rollback/checkpoint recovery magic.", "Hermes Native", "rewind", metric="rollback_events", tiers=[500, 1500, 4000, 10000, 25000], secret=True),
  83. # Research/Web
  84. _ach("rabbit_hole_certified", "Rabbit Hole Certified", "Search or extract enough web content to qualify as a research spiral.", "Research/Web", "spiral", metric="total_web_calls", tiers=[400, 1200, 3000, 8000, 20000]),
  85. _ach("citation_goblin", "Citation Goblin", "Extract enough web pages to become a tiny librarian.", "Research/Web", "quote", metric="total_web_extract_calls", tiers=[100, 300, 1000, 3000, 8000]),
  86. _ach("docs_archaeologist", "Docs Archaeologist", "Dig through documentation sources over and over.", "Research/Web", "compass", metric="docs_activity_events", tiers=[5000, 15000, 40000, 100000, 250000]),
  87. _ach("browser_possession", "Browser Possession", "Possess a browser through automation repeatedly.", "Research/Web", "browser", metric="browser_calls", tiers=[75, 200, 600, 1500, 4000]),
  88. # Tool Mastery
  89. _ach("terminal_goblin", "Terminal Goblin", "Spend serious time in shell-land.", "Tool Mastery", "terminal", metric="total_terminal_calls", tiers=[750, 2000, 6000, 15000, 50000]),
  90. _ach("patch_wizard", "Patch Wizard", "Bend files to your will with targeted patches.", "Tool Mastery", "wand", metric="total_patch_calls", tiers=[250, 750, 2000, 6000, 15000]),
  91. _ach("file_archaeologist", "File Archaeologist", "Dig through the filesystem with reads and searches.", "Tool Mastery", "folder", metric="total_file_reads_searches", tiers=[750, 2000, 6000, 15000, 50000]),
  92. _ach("image_whisperer", "Image Whisperer", "Use image generation or vision tools enough for visual work.", "Tool Mastery", "eye", metric="image_vision_calls", tiers=[100, 300, 1000, 3000, 8000]),
  93. _ach("voice_of_the_machine", "Voice Of The Machine", "Use text-to-speech or voice tooling repeatedly.", "Tool Mastery", "wave", metric="tts_calls", tiers=[10, 30, 100, 300, 800]),
  94. # Model Lore
  95. _ach("model_hopper", "Model Hopper", "Switch or inspect providers/models enough to count as a habit.", "Model Lore", "swap", metric="model_events", tiers=[10000, 30000, 80000, 200000, 500000]),
  96. _ach("openrouter_enjoyer", "OpenRouter Enjoyer", "Route model work through OpenRouter repeatedly.", "Model Lore", "router", metric="openrouter_events", tiers=[250, 750, 2000, 6000, 15000]),
  97. _ach("codex_conjurer", "Codex Conjurer", "Summon Codex-flavored assistance often enough for a ritual.", "Model Lore", "codex", metric="codex_events", tiers=[500, 1500, 4000, 10000, 25000]),
  98. _ach("multi_model_mage", "Multi-Model Mage", "Use a real spread of distinct model names across Hermes history.", "Model Lore", "prism", metric="distinct_model_count", tiers=[10, 20, 40, 80, 160]),
  99. _ach("five_model_flight", "Five-Model Flight", "Try at least five distinct LLMs instead of marrying the first model that answers.", "Model Lore", "prism", metric="distinct_model_count", tiers=[5, 10, 20, 40, 80]),
  100. _ach("provider_polyglot", "Provider Polyglot", "Use models from multiple providers across Hermes history.", "Model Lore", "swap", metric="distinct_provider_count", tiers=[2, 3, 5, 8, 12]),
  101. _ach("model_sommelier", "Model Sommelier", "Taste enough model/provider conversations to develop preferences.", "Model Lore", "wine", metric="model_events", tiers=[250, 750, 2000, 6000, 15000]),
  102. _ach("claude_confidant", "Claude Confidant", "Bring Claude-flavored reasoning into the workflow repeatedly.", "Model Lore", "quote", metric="claude_events", tiers=[50, 150, 500, 1500, 4000]),
  103. _ach("gemini_cartographer", "Gemini Cartographer", "Map enough Gemini-related workflows to know the terrain.", "Model Lore", "compass", metric="gemini_events", tiers=[50, 150, 500, 1500, 4000]),
  104. _ach("open_weights_pilgrim", "Open Weights Pilgrim", "Actually chat with local/open-weight models through Hermes session metadata.", "Model Lore", "terminal", metric="local_model_chat_sessions", tiers=[1, 3, 10, 30, 100]),
  105. # Workflow Intelligence
  106. _ach("toolset_cartographer", "Toolset Cartographer", "Navigate Hermes toolsets deliberately instead of treating tools as a blur.", "Hermes Native", "compass", metric="toolset_events", tiers=[20, 60, 200, 600, 1500]),
  107. _ach("config_surgeon", "Config Surgeon", "Operate on real config files, manifests, env files, and dashboard settings without flinching.", "Hermes Native", "key", metric="config_events", tiers=[100, 300, 1000, 3000, 10000]),
  108. _ach("rebase_acrobat", "Rebase Acrobat", "Handle real git history surgery: rebase, conflict, merge, fetch, push.", "Vibe Coding", "branch", metric="git_history_events", tiers=[10, 30, 100, 300, 800]),
  109. _ach("test_suite_tamer", "Test Suite Tamer", "Run enough verification commands that green text becomes part of the ritual.", "Tool Mastery", "daemon", metric="test_events", tiers=[100, 300, 800, 2400, 6000]),
  110. _ach("screenshot_hunter", "Screenshot Hunter", "Capture, inspect, and polish visual proof instead of just claiming it works.", "Tool Mastery", "eye", metric="screenshot_events", tiers=[50, 150, 500, 1500, 5000]),
  111. # Lifestyle
  112. _ach("marathon_operator", "Marathon Operator", "Accumulate a serious number of Hermes sessions.", "Lifestyle", "marathon", metric="session_count", tiers=[75, 200, 500, 1500, 5000]),
  113. _ach("weekend_warrior", "Weekend Warrior", "Run Hermes on weekends enough times to make it a lifestyle.", "Lifestyle", "calendar", metric="weekend_sessions", tiers=[25, 75, 200, 600, 1500]),
  114. _ach("night_shift_operator", "Night Shift Operator", "Run sessions during gremlin hours repeatedly.", "Lifestyle", "moon", metric="night_sessions", tiers=[25, 75, 200, 600, 1500]),
  115. _ach("cache_hit_appreciator", "Cache Hit Appreciator", "Notice or benefit from prompt/cache behavior.", "Lifestyle", "cache", metric="cache_events", tiers=[100, 300, 1000, 3000, 8000], secret=True),
  116. ]
  117. # ---- Durable state files ----
  118. SNAPSHOT_FILE = "scan_snapshot.json"
  119. CHECKPOINT_FILE = "scan_checkpoint.json"
  120. # Checkpoint schema 2: per-session stats read the compaction-archived display history, not just
  121. # the active window. Version 1 caches were computed active-only and are rescanned once.
  122. _CHECKPOINT_SCHEMA_VERSION = 2
  123. def _data_dir() -> Path:
  124. """Durable data root (``<hermes home>/plugin-data/hermes-achievements/``). State used to
  125. live in the install tree and died on ``hermes plugins remove``/``update``; legacy files
  126. migrate on first read (see ``_data_file``)."""
  127. try:
  128. from plugins.plugin_storage import plugin_data_dir
  129. return plugin_data_dir("hermes-achievements")
  130. except Exception:
  131. # Standalone dashboard import (no plugins package on sys.path): same layout, computed locally.
  132. root = get_hermes_home() / "plugin-data" / "hermes-achievements"
  133. root.mkdir(parents=True, exist_ok=True)
  134. return root
  135. def _data_file(name: str) -> Path:
  136. path = _data_dir() / name
  137. if not path.exists():
  138. legacy = get_hermes_home() / "plugins" / "hermes-achievements" / name
  139. if legacy.exists():
  140. try:
  141. # Two statements so the read (utf-8-sig, tolerates a BOM)
  142. # and the write (utf-8, never emits one) stay distinct.
  143. legacy_text = legacy.read_text(encoding="utf-8-sig")
  144. path.write_text(legacy_text, encoding="utf-8")
  145. except Exception:
  146. pass
  147. return path
  148. def _read_json(name: str) -> Any:
  149. """Parsed data file, or ``None`` when missing/unreadable."""
  150. path = _data_file(name)
  151. try:
  152. return json.loads(path.read_text(encoding="utf-8-sig"))
  153. except Exception:
  154. return None
  155. def _write_json(name: str, data: Any) -> None:
  156. path = _data_file(name)
  157. path.parent.mkdir(parents=True, exist_ok=True)
  158. path.write_text(json.dumps(_json_safe(data), indent=2, sort_keys=True), encoding="utf-8")
  159. def _json_safe(value: Any) -> Any:
  160. if isinstance(value, dict):
  161. return {k: _json_safe(v) for k, v in value.items()}
  162. if isinstance(value, (list, tuple)):
  163. return [_json_safe(v) for v in value]
  164. if isinstance(value, set):
  165. return sorted(_json_safe(v) for v in value)
  166. return value
  167. def load_state() -> dict[str, Any]:
  168. data = _read_json("state.json")
  169. return {"unlocks": {}} if data is None else data
  170. def save_state(state: dict[str, Any]) -> None:
  171. _write_json("state.json", state)
  172. def load_checkpoint() -> dict[str, Any]:
  173. data = _read_json(CHECKPOINT_FILE)
  174. if isinstance(data, dict):
  175. data.setdefault("schema_version", 1)
  176. data.setdefault("generated_at", 0)
  177. data.setdefault("sessions", {})
  178. if isinstance(data.get("sessions"), dict):
  179. return data
  180. return {"schema_version": _CHECKPOINT_SCHEMA_VERSION, "generated_at": 0, "sessions": {}}
  181. def session_fingerprint(meta: dict[str, Any]) -> dict[str, Any]:
  182. return {"last_active": meta.get("last_active"), "started_at": meta.get("started_at"), "model": meta.get("model"), "title": meta.get("title") or meta.get("preview") or "Untitled"}
  183. def _cache_is_fresh(now: int) -> bool:
  184. return _SNAPSHOT_CACHE is not None and (now - _SNAPSHOT_CACHE_AT) <= SNAPSHOT_TTL_SECONDS
  185. def _is_snapshot_stale(snapshot: Optional[dict[str, Any]], now: Optional[int] = None) -> bool:
  186. ts = int(snapshot.get("generated_at") or 0) if isinstance(snapshot, dict) else 0
  187. return ts <= 0 or (int(now or time.time()) - ts) > SNAPSHOT_TTL_SECONDS
  188. def _scan_status_payload(now: Optional[int] = None) -> dict[str, Any]:
  189. current = int(now or time.time())
  190. snap = _SNAPSHOT_CACHE if isinstance(_SNAPSHOT_CACHE, dict) else None
  191. generated_at = int(snap.get("generated_at") or 0) if snap else 0
  192. return {
  193. **_SCAN_STATUS,
  194. "ttl_seconds": SNAPSHOT_TTL_SECONDS,
  195. "snapshot_generated_at": generated_at or None,
  196. "snapshot_age_seconds": (current - generated_at) if generated_at else None,
  197. "snapshot_stale": _is_snapshot_stale(snap, current)}
  198. # ---- Per-session analysis ----
  199. def _tool_name_from_call(call: Any) -> Optional[str]:
  200. if not isinstance(call, dict):
  201. return None
  202. return call.get("name") or (call.get("function") or {}).get("name")
  203. def _content(msg: dict[str, Any]) -> str:
  204. content = msg.get("content")
  205. if content is None:
  206. return ""
  207. if isinstance(content, str):
  208. return content
  209. try:
  210. return json.dumps(content)
  211. except Exception:
  212. return str(content)
  213. def _count_tool(tool_names: list[str], *needles: str) -> int:
  214. lowered = [name.lower() for name in tool_names]
  215. return sum(1 for name in lowered if any(needle in name for needle in needles))
  216. _PROVIDER_MARKERS = ["openai", "anthropic", "google", "gemini", "mistral", "meta", "qwen", "deepseek", "xai", "nous", "ollama", "groq", "openrouter", "codex"]
  217. _LOCAL_MARKERS = ["ollama", "llama.cpp", "localhost", "127.0.0.1", "local/", "local:", "gguf", "vllm-local"]
  218. def model_provider(model_name: str) -> Optional[str]:
  219. name = (model_name or "").strip().lower()
  220. if not name or name == "none":
  221. return None
  222. if "/" in name:
  223. return name.split("/", 1)[0]
  224. for provider in _PROVIDER_MARKERS:
  225. if provider in name:
  226. return "google" if provider == "gemini" else provider
  227. return name.split(":", 1)[0].split("-", 1)[0]
  228. def is_local_model_name(model_name: str) -> bool:
  229. name = (model_name or "").strip().lower()
  230. return bool(name) and name != "none" and any(marker in name for marker in _LOCAL_MARKERS)
  231. def analyze_messages(session_id: str, title: str, messages: list[dict[str, Any]]) -> dict[str, Any]:
  232. tool_names: set[str] = set()
  233. tool_sequence: list[str] = []
  234. files_touched: set[str] = set()
  235. full_text_parts: list[str] = []
  236. error_count = 0
  237. for msg in messages:
  238. text = _content(msg)
  239. full_text_parts.append(text)
  240. if msg.get("tool_name"):
  241. name = str(msg["tool_name"])
  242. tool_names.add(name)
  243. # Tool result rows name the tool that already appeared in the assistant tool_calls:
  244. # keep it for distinct-tool detection but don't double-count it as a new call.
  245. if msg.get("role") != "tool":
  246. tool_sequence.append(name)
  247. for call in msg.get("tool_calls") or []:
  248. name = _tool_name_from_call(call)
  249. if name:
  250. tool_names.add(name)
  251. tool_sequence.append(name)
  252. if ERROR_RE.search(text):
  253. error_count += 1
  254. blob = text
  255. if msg.get("tool_calls"):
  256. blob += " " + json.dumps(msg.get("tool_calls"), default=str)
  257. files_touched.update(FILE_RE.findall(blob))
  258. full_text = "\n".join(full_text_parts)
  259. lower = full_text.lower()
  260. def hits(pattern: str) -> int:
  261. return len(re.findall(pattern, full_text, re.IGNORECASE))
  262. web_calls = _count_tool(tool_sequence, "web_search", "web_extract")
  263. browser_calls = _count_tool(tool_sequence, "browser")
  264. return {
  265. "session_id": session_id,
  266. "title": title or "Untitled session",
  267. "message_count": len(messages),
  268. "tool_call_count": len(tool_sequence),
  269. "tool_names": tool_names,
  270. "distinct_tool_count": len(tool_names),
  271. "error_count": error_count,
  272. "terminal_calls": _count_tool(tool_sequence, "terminal"),
  273. "web_calls": web_calls,
  274. "web_extract_calls": _count_tool(tool_sequence, "web_extract"),
  275. "browser_calls": browser_calls,
  276. "web_browser_calls": web_calls + browser_calls,
  277. "patch_calls": _count_tool(tool_sequence, "patch"),
  278. "file_reads_searches": _count_tool(tool_sequence, "read_file", "search_files"),
  279. "file_tool_calls": _count_tool(tool_sequence, "read_file", "write_file", "patch", "search_files"),
  280. "files_touched_count": len(files_touched),
  281. "delegate_calls": _count_tool(tool_sequence, "delegate_task"),
  282. "process_calls": _count_tool(tool_sequence, "process") + hits(r"background\s*=\s*true"),
  283. "cron_calls": _count_tool(tool_sequence, "cronjob"),
  284. "image_vision_calls": _count_tool(tool_sequence, "image", "vision"),
  285. "tts_calls": _count_tool(tool_sequence, "tts", "text_to_speech"),
  286. "skill_events": _count_tool(tool_sequence, "skill") + len(re.findall(r"\bskill", lower)),
  287. "skill_manage_events": _count_tool(tool_sequence, "skill_manage"),
  288. "memory_events": _count_tool(tool_sequence, "memory", "mnemosyne"),
  289. "memory_write_events": _count_tool(tool_sequence, "mnemosyne_remember", "memory"),
  290. "port_conflict": bool(PORT_RE.search(full_text)),
  291. "port_conflict_events": 1 if PORT_RE.search(full_text) else 0,
  292. "traceback_events": hits(r"traceback|exception"),
  293. "log_read_events": hits(r"gateway\.log|errors\.log|agent\.log|/api/logs|\blogs\b"),
  294. "permission_denied_events": hits(r"permission denied|eacces|operation not permitted"),
  295. "install_error_events": 1 if INSTALL_RE.search(full_text) and ERROR_RE.search(full_text) else 0,
  296. "install_success_events": 1 if INSTALL_RE.search(full_text) and SUCCESS_RE.search(full_text) else 0,
  297. "restart_after_error_events": 1 if error_count and re.search(r"\brestart|reload|kill|start\b", full_text, re.IGNORECASE) else 0,
  298. "env_var_error_events": hits(r"missing .*env|api key|environment variable|not configured|unauthorized|auth"),
  299. "yaml_error_events": hits(r"yaml|yml|colon|parse error") if ERROR_RE.search(full_text) else 0,
  300. "docker_conflict_events": hits(r"docker.*(name|container).*already|container name conflict|Conflict\. The container"),
  301. "frontend_activity_events": hits(r"\.(css|svg|tsx|jsx)|frontend|tailwind|react"),
  302. "css_activity_events": hits(r"\.css|tailwind|style|className|visual"),
  303. "git_events": hits(r"\bgit\s+(commit|push|merge|rebase|status|diff)"),
  304. "tiny_patch_after_errors_events": 1 if error_count >= 5 and re.search(r"one character|single character|typo", full_text, re.IGNORECASE) else 0,
  305. "context_events": hits(r"compress|context window|token|cache"),
  306. "gateway_events": hits(r"gateway|discord|telegram|slack|api_server"),
  307. "plugin_events": hits(r"plugin|dashboard-plugins|__HERMES_PLUGIN|manifest\.json"),
  308. "rollback_events": hits(r"rollback|checkpoint"),
  309. "docs_activity_events": hits(r"docs|documentation|docusaurus|README"),
  310. "model_events": hits(r"model|provider|openrouter|codex|gemini|claude|anthropic|openai|mistral|qwen|deepseek|llama|ollama|vllm|gguf"),
  311. "openrouter_events": hits(r"openrouter"),
  312. "codex_events": hits(r"codex"),
  313. "claude_events": hits(r"claude|anthropic"),
  314. "gemini_events": hits(r"gemini|google ai|google model"),
  315. "local_model_events": hits(r"ollama|llama\.cpp|gguf|vllm|local model|open[- ]weight|open weights"),
  316. "toolset_events": hits(r"toolset|enabled_toolsets|browser tool|terminal tool|file tool|web tool"),
  317. "config_events": hits(r"config\.ya?ml|\b[a-z0-9_-]+config\.(?:js|ts|json|ya?ml)|\.env(?:\b|\.)|manifest\.json|settings\.json|pyproject\.toml|package\.json"),
  318. "git_history_events": hits(r"\bgit\s+(rebase|merge|fetch|pull|push|tag|checkout)|merge conflict|conflict\s*\(|rebase --continue"),
  319. "test_events": hits(r"pytest|unittest|vitest|playwright|npm test|pnpm test|node --check|py_compile|tests? passed|\bOK\b"),
  320. "screenshot_events": hits(r"screenshot|playwright|vision_analyze|browser_vision|\.png|image data"),
  321. "release_events": hits(r"\bgit\s+tag|release|version bump|changelog|publish|pushed? tag"),
  322. "cache_events": hits(r"cache hit|prompt caching|cache_read"),
  323. "model_names": set()}
  324. # ---- Evaluation ----
  325. def _result(*, unlocked: bool, discovered: bool, state: str, tier, progress: int, next_tier, next_threshold: int, progress_pct: int) -> dict[str, Any]:
  326. """Uniform evaluation result (key order is part of the wire shape)."""
  327. return {"unlocked": unlocked, "discovered": discovered, "state": state, "tier": tier, "progress": progress, "next_tier": next_tier, "next_threshold": next_threshold, "progress_pct": progress_pct}
  328. def _state(definition: dict[str, Any], unlocked: bool, any_progress: bool) -> tuple[str, bool]:
  329. """``(state, discovered)``: secret badges stay hidden until the first matching signal."""
  330. secret = bool(definition.get("secret"))
  331. state = "unlocked" if unlocked else ("secret" if secret and not any_progress else "discovered")
  332. return state, any_progress or not secret
  333. def evaluate_tiered(definition: dict[str, Any], aggregate: dict[str, Any]) -> dict[str, Any]:
  334. progress = int(aggregate.get(definition["threshold_metric"], 0) or 0)
  335. tiers_list = sorted(definition.get("tiers", []), key=lambda t: t["threshold"])
  336. achieved = [t for t in tiers_list if progress >= t["threshold"]]
  337. next_tiers = [t for t in tiers_list if progress < t["threshold"]]
  338. next_threshold = next_tiers[0]["threshold"] if next_tiers else (tiers_list[-1]["threshold"] if tiers_list else 1)
  339. current_threshold = achieved[-1]["threshold"] if achieved else 0
  340. denom = max(1, next_threshold - current_threshold)
  341. pct = 100 if not next_tiers and achieved else max(0, min(99, math.floor(((progress - current_threshold) / denom) * 100)))
  342. state, discovered = _state(definition, bool(achieved), progress > 0)
  343. return _result(
  344. unlocked=bool(achieved), discovered=discovered, state=state, tier=achieved[-1]["name"] if achieved else None,
  345. progress=progress, next_tier=next_tiers[0]["name"] if next_tiers else None, next_threshold=next_threshold, progress_pct=pct)
  346. def evaluate_requirements(definition: dict[str, Any], aggregate: dict[str, Any]) -> dict[str, Any]:
  347. requirements = definition.get("requirements", [])
  348. if not requirements:
  349. state, discovered = _state(definition, False, False)
  350. return _result(unlocked=False, discovered=discovered, state=state, tier=None, progress=0, next_tier=None, next_threshold=1, progress_pct=0)
  351. parts = []
  352. any_progress = False
  353. complete = True
  354. for requirement in requirements:
  355. value = int(aggregate.get(requirement["metric"], 0) or 0)
  356. threshold = int(requirement.get("gte", 1))
  357. any_progress = any_progress or value > 0
  358. complete = complete and value >= threshold
  359. parts.append(min(1.0, value / max(1, threshold)))
  360. pct = math.floor((sum(parts) / len(parts)) * 100)
  361. state, discovered = _state(definition, complete, any_progress)
  362. return _result(
  363. unlocked=complete, discovered=discovered, state=state, tier=None, progress=pct, next_tier=None,
  364. next_threshold=100, progress_pct=100 if complete else min(99, pct))
  365. def evaluate_definition(definition: dict[str, Any], aggregate: dict[str, Any]) -> dict[str, Any]:
  366. if "threshold_metric" in definition:
  367. return evaluate_tiered(definition, aggregate)
  368. return evaluate_requirements(definition, aggregate)
  369. METRIC_LABELS = {
  370. "max_tool_calls_in_session": "tool calls in one session",
  371. "max_distinct_tools_in_session": "distinct Hermes tools used in one session",
  372. "max_terminal_calls_in_session": "terminal calls in one session",
  373. "max_file_tool_calls_in_session": "file/search/patch calls in one session",
  374. "max_web_browser_calls_in_session": "web search/extract or browser calls in one session",
  375. "max_messages_in_session": "messages in one session",
  376. "max_files_touched_in_session": "files touched in one session",
  377. "total_delegate_calls": "lifetime delegate_task calls",
  378. "total_process_calls": "lifetime background process operations",
  379. "total_cron_calls": "lifetime scheduled-job operations",
  380. "total_errors": "error/failed/traceback messages observed",
  381. "traceback_events": "traceback or exception mentions",
  382. "log_read_events": "log inspections",
  383. "port_conflict_events": "dev-server port conflict detections",
  384. "permission_denied_events": "permission-denied errors",
  385. "install_error_events": "package-install failures",
  386. "install_success_events": "successful package installs after package work",
  387. "restart_after_error_events": "restart/reload actions after error clusters",
  388. "env_var_error_events": "missing auth/config/environment-variable events",
  389. "yaml_error_events": "YAML/config parse incidents",
  390. "docker_conflict_events": "Docker/container-name conflicts",
  391. "frontend_activity_events": "frontend/CSS/SVG/React activity mentions",
  392. "css_activity_events": "CSS, styling, Tailwind, or className activity",
  393. "git_events": "git workflow commands",
  394. "tiny_patch_after_errors_events": "tiny typo-style fixes after error clusters",
  395. "skill_events": "Hermes skill mentions or tool use",
  396. "skill_manage_events": "skill_manage create/patch/delete operations",
  397. "memory_events": "memory or Mnemosyne tool events",
  398. "memory_write_events": "durable memory writes",
  399. "context_events": "context, compression, token, or cache-pressure mentions",
  400. "gateway_events": "gateway/API/chat-platform activity",
  401. "plugin_events": "dashboard plugin development or usage signals",
  402. "rollback_events": "rollback/checkpoint recovery mentions",
  403. "docs_activity_events": "documentation/README/docs activity",
  404. "model_events": "model/provider-related activity",
  405. "openrouter_events": "OpenRouter mentions",
  406. "codex_events": "Codex mentions",
  407. "cache_events": "prompt-cache/cache-hit mentions",
  408. "total_web_calls": "lifetime web_search/web_extract calls",
  409. "total_web_extract_calls": "lifetime web_extract calls",
  410. "browser_calls": "lifetime browser automation calls",
  411. "total_tool_calls": "lifetime Hermes tool calls",
  412. "total_terminal_calls": "lifetime terminal calls",
  413. "total_patch_calls": "lifetime targeted patch edits",
  414. "total_file_reads_searches": "lifetime read_file/search_files calls",
  415. "image_vision_calls": "image generation or vision tool calls",
  416. "tts_calls": "text-to-speech or voice tool calls",
  417. "distinct_model_count": "distinct model names seen in session metadata",
  418. "distinct_provider_count": "distinct model providers inferred from session metadata",
  419. "claude_events": "Claude/Anthropic model mentions",
  420. "gemini_events": "Gemini/Google model mentions",
  421. "local_model_events": "local/open-weight model mentions",
  422. "local_model_chat_sessions": "Hermes sessions whose model metadata is local/open-weight",
  423. "toolset_events": "toolset or tool-family mentions",
  424. "config_events": "configuration/environment/manifest activity",
  425. "git_history_events": "git history operations such as rebase, merge, fetch, push, or tag",
  426. "test_events": "test/check/verification command mentions",
  427. "screenshot_events": "screenshot, Playwright, PNG, or vision-inspection activity",
  428. "release_events": "release, version, publish, or git tag events",
  429. "session_count": "Hermes sessions",
  430. "weekend_sessions": "sessions started on weekends",
  431. "night_sessions": "sessions started late night or before dawn"}
  432. def metric_label(metric: str) -> str:
  433. return METRIC_LABELS.get(metric, metric.replace("_", " "))
  434. def criteria_for(definition: dict[str, Any]) -> str:
  435. if definition.get("secret") and definition.get("state") == "secret":
  436. return "Secret: exact requirement hidden until Hermes sees the first matching signal. Keep using Hermes across debugging, tools, memory, skills, plugins, and model workflows to reveal it."
  437. if "threshold_metric" in definition:
  438. tiers_list = sorted(definition.get("tiers", []), key=lambda t: t["threshold"])
  439. if not tiers_list:
  440. return "Requirement: use Hermes in the matching workflow."
  441. ladder = ", ".join(f"{t['name']} {t['threshold']}" for t in tiers_list)
  442. return f"Requirement: {metric_label(definition['threshold_metric'])}. Tier ladder: {ladder}."
  443. requirements = definition.get("requirements") or []
  444. if requirements:
  445. return "Requirement: " + "; ".join(f"{metric_label(r['metric'])} ≥ {int(r.get('gte', 1))}" for r in requirements) + "."
  446. return "Requirement: complete the matching Hermes behavior."
  447. def display_achievement(item: dict[str, Any]) -> dict[str, Any]:
  448. clean = dict(item)
  449. if clean.get("state") == "secret":
  450. return {**clean, "name": "???", "description": "Secret achievement: hidden until Hermes detects the first relevant behavior in your session history.", "criteria": criteria_for(clean), "icon": "secret"}
  451. clean["criteria"] = criteria_for(clean)
  452. return clean
  453. # ---- Scanning + aggregation ----
  454. def _scan_meta(mode: str, total: int, *, rescanned: int = 0, reused: int = 0, scanned_so_far: Optional[int] = None, expected_total: Optional[int] = None) -> dict[str, Any]:
  455. meta = {"mode": mode, "sessions_total": total, "sessions_rescanned": rescanned, "sessions_reused": reused}
  456. if scanned_so_far is not None:
  457. meta.update(sessions_scanned_so_far=scanned_so_far, sessions_expected_total=expected_total)
  458. return meta
  459. def scan_sessions(limit: Optional[int] = None, progress_callback: Optional[Any] = None, progress_every: int = 250) -> dict[str, Any]:
  460. """Scan Hermes sessions and build per-session achievement stats.
  461. ``limit=None`` (default) scans the ENTIRE history (SQLite ``LIMIT -1``); a former cap
  462. of 200 silently shrank lifetime totals on long-running installs. The checkpoint stores
  463. per-session stats keyed by ``(started_at, last_active)`` fingerprint so warm scans only
  464. re-analyze changed sessions. ``progress_callback(partial_sessions, scanned_so_far,
  465. total)`` fires every ``progress_every`` sessions so background scans can publish
  466. intermediate snapshots.
  467. """
  468. try:
  469. from hermes_state import SessionDB
  470. # The scan only reads. A writable open here was a second writer connection (schema
  471. # init, write lock, close-time checkpoint) beside the dashboard's own store on every
  472. # scan, and counted toward the "live SessionDB handles" precursor (#100896).
  473. db = SessionDB(read_only=True)
  474. except Exception as exc:
  475. return {"sessions": [], "aggregate": {}, "error": f"Could not open SessionDB: {exc}", "scan_meta": _scan_meta("failed", 0)}
  476. previous_checkpoint = load_checkpoint()
  477. previous_sessions = previous_checkpoint["sessions"] # load_checkpoint guarantees a dict
  478. checkpoint_is_current = int(previous_checkpoint.get("schema_version") or 0) == _CHECKPOINT_SCHEMA_VERSION
  479. reused = rescanned = 0
  480. db_limit = -1 if (limit is None or limit <= 0) else int(limit)
  481. try:
  482. sessions_meta = db.list_sessions_rich(limit=db_limit, include_children=True, project_compression_tips=False)
  483. total_sessions = len(sessions_meta)
  484. sessions: list[dict[str, Any]] = []
  485. checkpoint_sessions: dict[str, Any] = {}
  486. for idx, meta in enumerate(sessions_meta, start=1):
  487. sid = meta.get("id")
  488. if not sid:
  489. continue
  490. fp = session_fingerprint(meta)
  491. cached = previous_sessions.get(sid)
  492. cached = cached if isinstance(cached, dict) else {}
  493. title = meta.get("title") or meta.get("preview")
  494. if checkpoint_is_current and isinstance(cached.get("stats"), dict) and cached.get("fingerprint") == fp:
  495. stats = dict(cached["stats"])
  496. reused += 1
  497. else:
  498. # Compaction-archived display history too (deduped, no Undo/Rewind rows): the active
  499. # window shrinks after compaction, and stats read from it were never monotonic
  500. # (#112273). Rewound rows stay out — that work was undone.
  501. stats = analyze_messages(sid, title or "Untitled", db.get_messages(sid, include_compacted=True))
  502. rescanned += 1
  503. stats.update(session_id=sid, title=title or stats.get("title") or "Untitled", started_at=meta.get("started_at"), last_active=meta.get("last_active"), source=meta.get("source"))
  504. if meta.get("model"):
  505. # Checkpoint round-trips turn the set into a list; handle both.
  506. model = str(meta.get("model"))
  507. names = stats.setdefault("model_names", set())
  508. if isinstance(names, set):
  509. names.add(model)
  510. elif isinstance(names, list):
  511. if model not in names:
  512. names.append(model)
  513. else:
  514. stats["model_names"] = {model}
  515. sessions.append(stats)
  516. checkpoint_sessions[sid] = {"fingerprint": fp, "stats": _json_safe(stats)}
  517. if progress_callback is not None and progress_every > 0 and (idx % progress_every == 0) and idx < total_sessions:
  518. try:
  519. progress_callback(list(sessions), idx, total_sessions)
  520. except Exception:
  521. pass # Advisory — a broken publisher must never abort the scan.
  522. _write_json(CHECKPOINT_FILE, {"schema_version": _CHECKPOINT_SCHEMA_VERSION, "generated_at": int(time.time()), "sessions": checkpoint_sessions})
  523. finally:
  524. db.close()
  525. return {
  526. "sessions": sessions,
  527. "aggregate": aggregate_stats(sessions),
  528. "scan_meta": _scan_meta(
  529. "incremental" if reused > 0 else "full", len(sessions), rescanned=rescanned, reused=reused,
  530. scanned_so_far=len(sessions), expected_total=total_sessions)}
  531. # Per-session bests: aggregate metric -> session stat key (also drives evidence_for).
  532. _SESSION_MAX_METRICS = {
  533. "max_tool_calls_in_session": "tool_call_count",
  534. "max_distinct_tools_in_session": "distinct_tool_count",
  535. "max_messages_in_session": "message_count",
  536. "max_terminal_calls_in_session": "terminal_calls",
  537. "max_file_tool_calls_in_session": "file_tool_calls",
  538. "max_web_calls_in_session": "web_calls",
  539. "max_web_browser_calls_in_session": "web_browser_calls",
  540. "max_files_touched_in_session": "files_touched_count"}
  541. # Lifetime sums: aggregate metric -> session stat key.
  542. _SESSION_SUM_METRICS = {
  543. "total_errors": "error_count",
  544. "total_tool_calls": "tool_call_count",
  545. "total_terminal_calls": "terminal_calls",
  546. "total_web_calls": "web_calls",
  547. "total_web_extract_calls": "web_extract_calls",
  548. "total_patch_calls": "patch_calls",
  549. "total_file_reads_searches": "file_reads_searches",
  550. "total_delegate_calls": "delegate_calls",
  551. "total_process_calls": "process_calls",
  552. "total_cron_calls": "cron_calls",
  553. "browser_calls": "browser_calls",
  554. "image_vision_calls": "image_vision_calls",
  555. "tts_calls": "tts_calls"}
  556. # ``*_events`` counters summed under their own name.
  557. _SESSION_EVENT_KEYS = [
  558. "traceback_events", "log_read_events", "port_conflict_events", "permission_denied_events", "install_error_events", "install_success_events", "restart_after_error_events", "env_var_error_events", "yaml_error_events", "docker_conflict_events", "frontend_activity_events", "css_activity_events", "git_events", "tiny_patch_after_errors_events", "skill_events", "skill_manage_events", "memory_events", "memory_write_events", "context_events", "gateway_events", "plugin_events", "rollback_events", "docs_activity_events", "model_events", "openrouter_events", "codex_events", "claude_events", "gemini_events", "local_model_events", "toolset_events", "config_events", "git_history_events", "test_events", "screenshot_events", "release_events", "cache_events",
  559. ]
  560. def aggregate_stats(sessions: list[dict[str, Any]]) -> dict[str, Any]:
  561. # Key order is part of the /rescan wire shape.
  562. agg: dict[str, Any] = {"session_count": len(sessions)}
  563. for key in (*_SESSION_MAX_METRICS, *_SESSION_SUM_METRICS, "distinct_model_count", "distinct_provider_count", "local_model_chat_sessions", "weekend_sessions", "night_sessions", *_SESSION_EVENT_KEYS):
  564. agg[key] = 0
  565. model_names: set[str] = set()
  566. provider_names: set[str] = set()
  567. for s in sessions:
  568. for key, stat in _SESSION_MAX_METRICS.items():
  569. agg[key] = max(agg[key], s.get(stat, 0))
  570. for key, stat in _SESSION_SUM_METRICS.items():
  571. agg[key] += s.get(stat, 0)
  572. for key in _SESSION_EVENT_KEYS:
  573. agg[key] += s.get(key, 0)
  574. session_models = s.get("model_names") or set()
  575. model_names.update(session_models)
  576. provider_names.update(filter(None, (model_provider(str(m)) for m in session_models)))
  577. if any(is_local_model_name(str(m)) for m in session_models):
  578. agg["local_model_chat_sessions"] += 1
  579. if s.get("started_at"):
  580. try:
  581. lt = time.localtime(float(s.get("started_at")))
  582. if lt.tm_wday >= 5:
  583. agg["weekend_sessions"] += 1
  584. if lt.tm_hour < 6 or lt.tm_hour >= 23:
  585. agg["night_sessions"] += 1
  586. except Exception:
  587. pass
  588. agg["distinct_model_count"] = len({m for m in model_names if m and m != "None"})
  589. agg["distinct_provider_count"] = len(provider_names)
  590. return agg
  591. def evidence_for(definition: dict[str, Any], sessions: list[dict[str, Any]]) -> Optional[dict[str, Any]]:
  592. key = _SESSION_MAX_METRICS.get(definition.get("threshold_metric"))
  593. if not sessions or key is None:
  594. return None
  595. s = max(sessions, key=lambda x: x.get(key, 0))
  596. return {"session_id": s.get("session_id"), "title": s.get("title"), "value": s.get(key, 0)}
  597. # ---- Snapshot assembly ----
  598. def _snapshot(evaluated: list[dict[str, Any]], scan: dict[str, Any], now: int) -> dict[str, Any]:
  599. """Wire payload shared by finished, partial and pending snapshots."""
  600. return {
  601. "achievements": evaluated,
  602. "sessions": scan.get("sessions", []),
  603. "aggregate": scan.get("aggregate", {}),
  604. "scan_meta": scan.get("scan_meta", {}),
  605. "error": scan.get("error"),
  606. "unlocked_count": sum(1 for a in evaluated if a["unlocked"]),
  607. "discovered_count": sum(1 for a in evaluated if a.get("state") == "discovered"),
  608. "secret_count": sum(1 for a in evaluated if a.get("state") == "secret"),
  609. "total_count": len(evaluated),
  610. "generated_at": now}
  611. def _compute_from_scan(scan: dict[str, Any], *, is_partial: bool = False) -> dict[str, Any]:
  612. """Evaluate every achievement definition against a scan result. Used by ``compute_all``
  613. for finished scans AND by the background progress callback for in-flight snapshots;
  614. ``is_partial=True`` skips persisting ``state.json`` unlocks — an "unlock time" from
  615. half a scan could be invalidated by a later session. Persisted unlocks are still read
  616. for partials: the background scan publishes them to the cache, so an earned badge would
  617. otherwise render as locked for the whole rescan (#112273)."""
  618. aggregate = scan.get("aggregate", {})
  619. state = load_state()
  620. unlocks = state.setdefault("unlocks", {})
  621. now = int(time.time())
  622. evaluated = []
  623. for definition in ACHIEVEMENTS:
  624. result = evaluate_definition(definition, aggregate)
  625. unlock_id = definition["id"]
  626. if not is_partial and result["unlocked"] and unlock_id not in unlocks:
  627. unlocks[unlock_id] = {"unlocked_at": now, "first_tier": result.get("tier"), "evidence": evidence_for(definition, scan.get("sessions", []))}
  628. # Sticky unlocks: state.json is a floor. A badge earned on evidence that rewind/compaction
  629. # later removed from the scan basis must not flicker back to locked (#112273).
  630. if unlock_id in unlocks and not result["unlocked"]:
  631. result.update(unlocked=True, discovered=True, state="unlocked",
  632. tier=result.get("tier") or unlocks[unlock_id].get("first_tier"))
  633. item = {**definition, **result}
  634. if result["unlocked"]:
  635. item["unlocked_at"] = unlocks.get(unlock_id, {}).get("unlocked_at")
  636. item["evidence"] = unlocks.get(unlock_id, {}).get("evidence") or evidence_for(definition, scan.get("sessions", []))
  637. evaluated.append(display_achievement(item))
  638. if not is_partial:
  639. save_state(state)
  640. return _snapshot(evaluated, scan, now)
  641. def compute_all(progress_callback: Optional[Any] = None, progress_every: int = 250) -> dict[str, Any]:
  642. scan = scan_sessions(progress_callback=progress_callback, progress_every=progress_every)
  643. return _compute_from_scan(scan, is_partial=False)
  644. _BACKGROUND_SCAN_THREAD: Optional[threading.Thread] = None
  645. _BACKGROUND_SCAN_LOCK = threading.Lock()
  646. def _build_pending_snapshot(now: int) -> dict[str, Any]:
  647. """Structurally-complete placeholder served while the first-ever scan runs, so the UI
  648. renders an empty list + spinner without special-casing "no data"."""
  649. evaluated = [
  650. display_achievement({
  651. **d, "unlocked": False, "discovered": False, "state": "secret" if d.get("secret") else "discovered", "progress": 0,
  652. "progress_pct": 0, "next_tier": (d.get("tiers") or [{}])[0].get("name"),
  653. "next_threshold": (d.get("tiers") or [{}])[0].get("threshold", 1), "tier": None})
  654. for d in ACHIEVEMENTS]
  655. return _snapshot(evaluated, {"scan_meta": _scan_meta("pending", 0), "error": None}, now)
  656. def _set_cache(snapshot: dict[str, Any], at: int) -> None:
  657. global _SNAPSHOT_CACHE, _SNAPSHOT_CACHE_AT
  658. _SNAPSHOT_CACHE = _json_safe(snapshot)
  659. _SNAPSHOT_CACHE_AT = at
  660. def _run_scan_and_update_cache(publish_partial_snapshots: bool = True) -> None:
  661. """Execute a scan + snapshot update (synchronously or from a thread). With
  662. ``publish_partial_snapshots`` (background scans) the scanner periodically publishes
  663. in-progress snapshots to ``_SNAPSHOT_CACHE`` so a long cold scan unlocks badges
  664. incrementally; synchronous /rescan callers pass ``False`` since they block on the result."""
  665. with _SCAN_LOCK:
  666. started = int(time.time())
  667. _SCAN_STATUS.update(state="running", started_at=started, last_error=None)
  668. def _publish_partial(partial_sessions, scanned_so_far, total):
  669. try:
  670. partial_scan = {
  671. "sessions": partial_sessions,
  672. "aggregate": aggregate_stats(partial_sessions),
  673. "scan_meta": _scan_meta("in_progress", scanned_so_far, scanned_so_far=scanned_so_far, expected_total=total),
  674. }
  675. # _SNAPSHOT_CACHE_AT stays 0 so partials remain in the 'stale' regime: the UI
  676. # keeps polling /scan-status and never mistakes an in-flight result for a finished one.
  677. _set_cache(_compute_from_scan(partial_scan, is_partial=True), 0)
  678. except Exception:
  679. pass # Intermediate publication is best-effort; don't kill the scan.
  680. try:
  681. computed = _json_safe(compute_all(progress_callback=_publish_partial if publish_partial_snapshots else None))
  682. _set_cache(computed, int(computed.get("generated_at") or int(time.time())))
  683. _write_json(SNAPSHOT_FILE, _SNAPSHOT_CACHE)
  684. _SCAN_STATUS["state"] = "idle"
  685. except Exception as exc:
  686. _SCAN_STATUS.update(state="failed", last_error=str(exc))
  687. finally:
  688. finished = int(time.time())
  689. _SCAN_STATUS.update(finished_at=finished, last_duration_ms=int((finished - started) * 1000), run_count=int(_SCAN_STATUS.get("run_count", 0)) + 1)
  690. def _start_background_scan() -> None:
  691. """Kick off a daemon-thread scan unless one is already running (idempotent)."""
  692. global _BACKGROUND_SCAN_THREAD
  693. with _BACKGROUND_SCAN_LOCK:
  694. existing = _BACKGROUND_SCAN_THREAD
  695. if existing is not None and existing.is_alive():
  696. return
  697. thread = threading.Thread(target=_run_scan_and_update_cache, kwargs={"publish_partial_snapshots": True}, name="hermes-achievements-scan", daemon=True)
  698. _BACKGROUND_SCAN_THREAD = thread
  699. thread.start()
  700. def evaluate_all(force: bool = False) -> dict[str, Any]:
  701. """Return the current achievements payload: a fresh in-memory cache is returned as is;
  702. a stale on-disk snapshot is served while a background rescan runs (UI decorates it with
  703. ``is_stale=True``); with no snapshot yet an empty-but-valid "pending" payload is served
  704. while the first scan runs; ``force=True`` (manual /rescan) scans synchronously. Cold
  705. scans on 8000+ session databases take minutes, hence the background thread."""
  706. global _SNAPSHOT_CACHE, _SNAPSHOT_CACHE_AT
  707. now = int(time.time())
  708. if not force and _cache_is_fresh(now):
  709. return _SNAPSHOT_CACHE or {}
  710. # Lazy-load the persisted snapshot so fresh process starts serve cached data.
  711. if _SNAPSHOT_CACHE is None:
  712. persisted = _read_json(SNAPSHOT_FILE)
  713. if isinstance(persisted, dict):
  714. _SNAPSHOT_CACHE = persisted
  715. _SNAPSHOT_CACHE_AT = int(persisted.get("generated_at") or 0) or now
  716. if force:
  717. # No partial publishing: the caller is blocking on the final result.
  718. _run_scan_and_update_cache(publish_partial_snapshots=False)
  719. elif not _cache_is_fresh(now):
  720. # Serve what we have (stale is fine) and refresh in the background; on a first-ever
  721. # run the UI polls /scan-status and re-fetches when the scan completes.
  722. _start_background_scan()
  723. return _SNAPSHOT_CACHE if _SNAPSHOT_CACHE is not None else _build_pending_snapshot(now)
  724. # ---- Routes ----
  725. @router.get("/achievements")
  726. async def achievements():
  727. data = evaluate_all()
  728. payload = {k: data[k] for k in ["achievements", "unlocked_count", "discovered_count", "secret_count", "total_count", "error", "generated_at"] if k in data}
  729. payload["is_stale"] = _is_snapshot_stale(data)
  730. payload["scan_meta"] = {**(data.get("scan_meta") or {}), "status": _scan_status_payload()}
  731. return payload
  732. @router.get("/scan-status")
  733. async def scan_status():
  734. return _scan_status_payload()
  735. @router.get("/recent-unlocks")
  736. async def recent_unlocks():
  737. data = evaluate_all()
  738. return sorted([a for a in data["achievements"] if a["unlocked"]], key=lambda a: a.get("unlocked_at") or 0, reverse=True)[:20]
  739. @router.get("/sessions/{session_id}/badges")
  740. async def session_badges(session_id: str):
  741. data = evaluate_all()
  742. session = next((s for s in data["sessions"] if s["session_id"] == session_id), None)
  743. if not session:
  744. return {"session_id": session_id, "badges": []}
  745. aggregate = aggregate_stats([session])
  746. results = [(d, evaluate_definition(d, aggregate)) for d in ACHIEVEMENTS]
  747. return {"session_id": session_id, "badges": [display_achievement({**d, **r}) for d, r in results if r["unlocked"]]}
  748. @router.post("/rescan")
  749. async def rescan():
  750. return {"ok": True, **evaluate_all(force=True)}
  751. @router.post("/reset-state")
  752. async def reset_state():
  753. global _SNAPSHOT_CACHE, _SNAPSHOT_CACHE_AT
  754. save_state({"unlocks": {}})
  755. _SNAPSHOT_CACHE = None
  756. _SNAPSHOT_CACHE_AT = 0
  757. _SCAN_STATUS.update(state="idle", started_at=None, finished_at=None, last_error=None, last_duration_ms=None)
  758. for name in (SNAPSHOT_FILE, CHECKPOINT_FILE):
  759. try:
  760. _data_file(name).unlink(missing_ok=True)
  761. except Exception:
  762. pass
  763. return {"ok": True}