Add Hermes Agent as a first-class data source (read state.db for real usage)

[yjk72091]

Feature Description

Add TokenStep support for Hermes Agent (https://hermes-agent.nousresearch.com) as a first-class data source. Hermes is currently listed as "待确认" (candidate, not yet implemented) in docs/AGENT_SUPPORT.md — this issue proposes the integration path and provides verified schema information so it can move to "实验支持" and then "正式支持" status.

Motivation

Hermes Agent is a CLI + messaging-gateway agent (similar to Claude Code / Codex / OpenCode) with significant adoption among power users. Hermes session data is already persisted locally with real, non-estimated API usage fields — the document's current note that "本机日志存在 tokens=~ 估算" appears to be based on older session JSON files; the canonical store (state.db, SQLite) has authoritative token counts.

Without TokenStep support, Hermes users (myself included) cannot see their daily token usage in the menu bar app, even though the data is sitting on their own disk.

Proposed Solution

Add a Hermes collector that reads ~/.hermes/state.db (SQLite, read-only) and aggregates per-session token counts the same way the existing Codex / Claude Code collectors do.

Data location

Path	Format	Notes
~/.hermes/state.db	SQLite	Canonical store, per-session aggregate
~/.hermes/profiles/<name>/state.db	SQLite	Same schema, per-profile for users who run multiple profiles

Schema (verified, currently on my machine)

CREATE TABLE sessions (
    id TEXT PRIMARY KEY,
    source TEXT NOT NULL,                  -- 'tui' | 'cli' | 'weixin' | 'subagent' | 'gateway' | ...
    user_id TEXT,
    session_key TEXT,
    chat_id TEXT,
    chat_type TEXT,
    thread_id TEXT,
    model TEXT NOT NULL,                   -- e.g. 'MiniMax-M3'
    model_config TEXT,
    system_prompt TEXT,
    parent_session_id TEXT,
    started_at REAL NOT NULL,              -- unix epoch seconds
    ended_at REAL,
    end_reason TEXT,
    message_count INTEGER DEFAULT 0,
    tool_call_count INTEGER DEFAULT 0,
    input_tokens INTEGER DEFAULT 0,        -- non-cached input tokens
    output_tokens INTEGER DEFAULT 0,
    cache_read_tokens INTEGER DEFAULT 0,    -- Anthropic cache_read_input_tokens
    cache_write_tokens INTEGER DEFAULT 0,  -- Anthropic cache_creation_input_tokens
    reasoning_tokens INTEGER DEFAULT 0,
    cwd TEXT,
    git_branch TEXT,
    git_repo_root TEXT,
    billing_provider TEXT,                 -- e.g. 'minimax-cn'
    billing_base_url TEXT                  -- e.g. 'https://api.minimaxi.com/anthropic'
    -- ... more columns exist but not relevant for usage
);

Sample query (verified)

SELECT
  id, source, model,
  input_tokens, output_tokens,
  cache_read_tokens, cache_write_tokens,
  reasoning_tokens,
  datetime(started_at, 'unixepoch') AS started_at_iso,
  billing_provider, billing_base_url
FROM sessions
WHERE started_at >= ?    -- since timestamp (unix epoch seconds)
  AND input_tokens + output_tokens + cache_read_tokens + cache_write_tokens > 0
ORDER BY started_at ASC;

Sample result (real data from my own machine today)

20260629_174612_dedd28   | tui      | MiniMax-M3 |  82316 |  3974 | 686592 | 0 | 0
20260629_180027_21b639b0 | weixin   | MiniMax-M3 |  37452 |   302 |  18899 | 0 | 0
20260630_102924_ca5163   | tui      | MiniMax-M3 |  59364 | 21740 | 201216 | 0 | 0
20260630_104610_f47cbd   | subagent | MiniMax-M3 |   1238 |   613 |    256 | 0 | 0
20260630_151601_b2f1cb   | subagent | MiniMax-M3 |   2235 |   248 |    128 | 0 | 0

Token口径建议 (for daily aggregation)

Per AGENT_SUPPORT.md rule #1 ("优先读官方或工具本地写出的 usage 字段"),建议沿用 Anthropic 标准口径:

• input total = input_tokens + cache_read_tokens + cache_write_tokens(全部计入"读入")
• output total = output_tokens
• model label = sessions.model(已含具体模型名,例如 MiniMax-M3)
• client/source label = sessions.source(区分 tui / cli / weixin / subagent 等)

或者更保守地,只把 input_tokens + output_tokens 计入总数,把 cache tokens 作为分项单独展示(给用户看缓存效率)。

Dedupe

state.db 中 sessions.id 是 primary key,天然唯一。不需要按 message.id 去重(那是 Claude Code 那边的麻烦事,Hermes 已经聚合好了)。也不需要担心和 Codex/Claude Code 重复——state.db 是 Hermes 自己的数据库,完全独立。

实现建议

参考现有 Codex collector 的结构(读 SQLite → 解析 sessions 行 → 按 model + 日期聚合),Hermes 这边可以直接复制粘贴改个路径:

~/.hermes/state.db                                  (default profile)
~/.hermes/profiles/<name>/state.db                  (named profiles)

多 profile 场景下,建议合并统计时以 model 为主键,profile name 作为可选的客户端标签。

Alternatives Considered

1. 从 provider 账单 API 拉(OpenRouter / Anthropic OAuth usage):不行,Hermes 支持 20+ provider,大部分没有 usage API;且 TokenStep 的 local-first 定位不应该走这条路。
2. 解析 ~/.hermes/sessions/*.jsonl request_dump:不推荐,这些 dump 只在错误/重试时被写入,完整度不可控。
3. 从 state.db.messages.token_count 读:字段当前大部分为 0/未填充(我的实例验证),不能作为主数据源。sessions 表才是真。
4. 等 Hermes 提供官方 usage 文件:文档里写"需要真实 API usage 或统一事件",其实 sessions 表已经提供了。

Evidence

我机器上的真实数据(2026-06-29):

$ sqlite3 ~/.hermes/state.db \
    "SELECT COUNT(*), SUM(input_tokens), SUM(output_tokens), SUM(cache_read_tokens) FROM sessions;"
5|182605|26877|907091

5 个 session,合计 input 182k / output 26k / cache_read 907k,全部为真实 API 返回的数字。

Environment

• macOS 26.5.1
• TokenStep 0.1.28 (latest release)
• Hermes Agent latest (state.db schema version current)

Acceptance criteria

• TokenStep 显示 Hermes 作为一个数据源
• 每日用量按 sessions.model 分桶,数字与 state.db 直接查询一致
• cache tokens 在 UI 上独立显示(让用户能看到缓存效率)
• 文档 docs/AGENT_SUPPORT.md 从"候选支持"移到"实验支持"或"正式支持"
• 多 profile 用户(像我)能合并统计