feat: add Hermes Agent local session support

[pinion05]

Summary

• add Hermes Agent local session support by parsing $HERMES_HOME/state.db / ~/.hermes/state.db
• wire Hermes through local scanning, CLI/TUI filters, wrapped metadata, frontend source metadata, and submit validation
• add Hermes logo assets plus parser and validation tests

Implementation details

• read session-level usage from the Hermes sessions SQLite table
• preserve message_count from Hermes session metadata while importing aggregated token totals
• prefer actual_cost_usd, fall back to estimated_cost_usd, and infer provider from the model when billing_provider is missing or unknown
• skip empty sessions with no model / no usage totals
• handle row-level SQLite decode errors explicitly instead of silently dropping them

Validation

• cargo test -p tokscale-core hermes -q
• cargo test -p tokscale-cli -q
• bunx vitest run packages/frontend/__tests__/api/submit.test.ts
• bunx tsc --noEmit (verified on the main working tree at /home/pinion/tokscale)
• cargo run -p tokscale-cli -- models --hermes --light --no-spinner
• cargo run -p tokscale-cli -- graph --hermes --output /tmp/tokscale-hermes-graph.json

Notes

• This PR is rebuilt on a clean branch from upstream/main with only the meaningful Hermes commits retained, so the diff stays the same while the review history is cleaner.

Closes #391

---

Summary by cubic

Add Hermes Agent local session support by reading the SQLite sessions table at $HERMES_HOME/state.db (fallback ~/.hermes/state.db). Also fixes CLI labels to consistently show “Hermes Agent”. Addresses #391.

• New Features

  • Parse Hermes sessions with message_count, token totals, dedup by id, and cost selection (prefer actual_cost_usd, fallback to estimated_cost_usd; infer provider from model when needed). Skip empty sessions and warn on row decode errors.
  • Integrate with local scanning and pricing: detect the DB via HERMES_HOME or default path; exclude Hermes from extra dir scanning; apply pricing when cost is zero in tokscale-core.
  • CLI/TUI: add --hermes across commands, include in default clients, set TUI hotkey to e, add color, display name, and logo in tokscale-cli.
  • Frontend: add hermes source ID, logo, color, and display name; include in submission validation and types; add submit API test. Update README with paths and usage.

• Bug Fixes

  • CLI: label Hermes consistently as “Hermes Agent” in tables and summaries.

^{Written for commit 7f1f5e5. Summary will update on new commits.}

[vercel]

Someone is attempting to deploy a commit to the Inevitable Team on Vercel.

A member of the Team first needs to authorize it.

[cubic-dev-ai]

2 issues found across 22 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="crates/tokscale-cli/src/main.rs">

<violation number="1" location="crates/tokscale-cli/src/main.rs:1128">
P3: Hermes is now included in client filters, but `capitalize_client` doesn’t have a `"hermes"` arm, so CLI tables will render the client as lowercase `hermes` instead of a branded label (e.g., "Hermes"/"Hermes Agent" as used elsewhere). Add a Hermes mapping to keep display names consistent.</violation>
</file>

<file name="crates/tokscale-core/src/sessions/hermes.rs">

<violation number="1" location="crates/tokscale-core/src/sessions/hermes.rs:154">
P2: Hermes dedup key uses only session_id, which can undercount per-model sessions; include model+provider in the key.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Hermes dedup key uses only session_id, which can undercount per-model sessions; include model+provider in the key.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At crates/tokscale-core/src/sessions/hermes.rs, line 154:

<comment>Hermes dedup key uses only session_id, which can undercount per-model sessions; include model+provider in the key.</comment>

<file context>
@@ -0,0 +1,159 @@
+                actual_cost.or(estimated_cost).unwrap_or(0.0).max(0.0),
+            );
+            msg.message_count = message_count.max(0);
+            msg.dedup_key = Some(session_id);
+            msg
+        },
</file context>

[pinion05]

Follow-up on the latest bot review:\n\n- I fixed the valid CLI display-name issue that cubic found. Hermes now renders as "Hermes Agent" in the CLI table path as well (commit ).\n- I am intentionally leaving the Hermes unchanged for now. This parser imports one per unique Hermes row from a single SQLite source, and uses as the dedup key. I do not currently have schema or real-data evidence that the same Hermes row id is reused across multiple model/provider variants, so changing the key to include model/provider would be speculative and could weaken the row-identity semantics. If there is a concrete collision/repro case later, I can revisit that separately.

[pinion05]

Superseding my previous malformed comment (shell quoting ate the inline code markers):

• I fixed the valid CLI display-name issue that cubic found. Hermes now renders as "Hermes Agent" in the CLI table path as well (commit 7f1f5e5).
• I am intentionally leaving the Hermes dedup_key unchanged for now. This parser imports one UnifiedMessage per unique Hermes sessions row from a single SQLite source, and uses sessions.id as the dedup key. I do not currently have schema or real-data evidence that the same Hermes row id is reused across multiple model/provider variants, so changing the key to include model/provider would be speculative and could weaken the row-identity semantics. If there is a concrete collision/repro case later, I can revisit that separately.

[pinion05]

@cubic-dev-ai please re-run the review on the latest commit.

[cubic-dev-ai]

@cubic-dev-ai please re-run the review on the latest commit.

@pinion05 I have started the AI code review. It will take a few minutes to complete.

[cubic-dev-ai]

No issues found across 22 files