2.1 KiB
2.1 KiB
hermes-trace Architecture
Overview
hermes-trace is a Hermes Agent plugin that captures every LLM API call (main session, background review forks, subagents) to a local SQLite store with a Granian-powered query frontend.
Data Flow
LLM API call happens (main, background_review, or subagent)
│
▼
pre_api_request / post_api_request hooks in __init__.py
│
▼
db.write_turn() / db.write_tool_call()
│
▼
telemetry.db (SQLite: turns + tool_calls tables)
│
▼
Granian → FastAPI → Jinja2 templates → HTMX + Alpine.js in browser
│
▼
Flat turn timeline table
│
▼ click a row
Right-side overlay detail panel
Components
Capture Layer (__init__.py)
- Registers 3 Hermes plugin hooks:
pre_api_request,post_api_request,post_tool_call - Spawns a Granian daemon thread for the frontend server
- Spawns a cleanup daemon thread for periodic data retention
Data Layer (db.py)
- SQLite schema with
turnsandtool_callstables - Write helpers:
write_turn(),write_tool_call() - Read helpers:
get_sessions(),get_turns_for_session(),get_turns_with_tool_calls(),get_turn_detail() - Cleanup:
clean_expired_turns()withON DELETE CASCADEfor tool_calls
Frontend Server (app.py)
- FastAPI application served by Granian (
--interface asgi), launched as a subprocess from a daemon thread (Granian requires the main thread forsignal.signal()) - 6 routes (incl. focus_tc variant): session list, flat-table session view, turn detail overlay (with focus_tc), payload lazy-load, and a legacy waterfall fragment
- The waterfall route and template are legacy code with no live navigation path in the UI; they may be removed in a future cleanup
- Custom Jinja2 filters:
commas(thousands separator for token counts),utc8(UTC → UTC+8 datetime formatting) - Pretty-print helper:
_pretty_json()with optional\n→ newline replacement
Templates (templates/)
See docs/frontend.md for detailed frontend architecture.