hermes-agent/plugins/hermes-achievements/docs/achievements-performance-implementation-spec.md

Hermes Achievements Implementation Spec (Detailed)

This document is implementation-facing detail to execute the performance refactor later.

Decision scope: keep only Achievements tab flow; remove /overview + top-banner slot integration.

---

A) Current Behavior Summary

• evaluate_all() performs:
  • full scan_sessions()
  • SessionDB.list_sessions_rich(...)
  • db.get_messages(session_id) for each session
  • text/tool regex analysis + aggregation + evaluation
• /overview and /achievements both currently call evaluate_all() directly.
• slot calls (sessions:top, analytics:top) currently invoke /overview.

Consequence: repeated full recomputes and contention.

---

B) De-scope/Removal Changes

1. Remove backend route:

• GET /overview

2. Remove frontend slot usage:

• SummarySlot component
• registerSlot("sessions:top")
• registerSlot("analytics:top")

3. Remove manifest slot declarations:

• "slots": ["sessions:top", "analytics:top"]

4. Keep:

• tab route/page for Achievements
• /achievements endpoint and full tab rendering

---

C) Target Internal Interfaces

1) SnapshotStore

Responsibilities:

• hold latest computed snapshot in memory
• persist/load snapshot from disk
• expose age and staleness checks

Storage path:

• ~/.hermes/plugins/hermes-achievements/scan_snapshot.json

Methods (conceptual):

• get() -> snapshot | null
• set(snapshot)
• is_stale(ttl_seconds)

2) ScanCoordinator

Responsibilities:

• single-flight guard for compute jobs
• track scan status

Methods:

• run_if_needed(force: bool = false)
• get_status()

State fields:

• state: idle|running|failed
• started_at, finished_at
• last_error
• run_count

3) build_snapshot()

Responsibilities:

• execute current compute logic once
• on first run, perform full scan and materialize per-session contributions
• on subsequent runs, process only changed/new sessions via checkpoint fingerprints
• produce shape consumed by /achievements

Output:

• achievements
• count fields
• optional scan_meta

---

D) Endpoint Behavior Matrix (No /overview)

Endpoint	Cache fresh	Cache stale	No cache	Force rescan
/achievements	return cached	return stale + trigger bg refresh	blocking bootstrap scan	n/a
/rescan	trigger refresh	trigger refresh	trigger refresh	yes
/scan-status	status only	status only	status only	status only

Notes:

• At most one scan run active.
• Other callers either await same run or receive stale snapshot according to policy.

---

E) Data Shape (Proposed)

{
  "generated_at": 0,
  "is_stale": false,
  "scan_meta": {
    "duration_ms": 0,
    "sessions_scanned": 0,
    "messages_scanned": 0,
    "mode": "full",
    "error": null
  },
  "achievements": [],
  "unlocked_count": 0,
  "discovered_count": 0,
  "secret_count": 0,
  "total_count": 0,
  "error": null
}

Compatibility guidance:

• Keep existing /achievements keys.
• Add metadata keys without breaking old callers.

Checkpoint file (new):

• ~/.hermes/plugins/hermes-achievements/scan_checkpoint.json

Suggested checkpoint shape:

{
  "schema_version": 1,
  "generated_at": 0,
  "sessions": {
    "<session_id>": {
      "fingerprint": {
        "updated_at": 0,
        "message_count": 0,
        "hash": "optional"
      },
      "contribution": {
        "metrics": {}
      }
    }
  }
}

Notes:

• fingerprint mismatch => recompute that session contribution only.
• unchanged fingerprint => reuse stored contribution.

---

F) Concurrency Contract

• Any request path that needs fresh data must pass through single-flight coordinator.
• If a scan is running:
  • do not start second scan
  • either await in-flight run (bounded) or serve stale snapshot immediately
• lock scope must include scan start/finish state transitions.

---

G) Error Handling Contract

• If refresh fails and prior snapshot exists:
  • return prior snapshot with is_stale=true and error metadata
• If refresh fails and no prior snapshot:
  • return explicit error response (current behavior equivalent)
• scan-status should always return last known state/error.

---

H) Frontend Integration Contract

• Achievements page:
  • one fetch on mount to /achievements
  • optional background refresh indicator if stale
• no top-banner slot integration
• avoid duplicate in-flight calls during fast navigation by cancellation/debounce.

---

I) Validation Checklist

• /overview route removed
• manifest has no sessions:top/analytics:top slots
• frontend has no api("/overview") calls
• repeated Achievements navigation does not create multiple heavy scans
• average warm load times meet SLOs
• unlock totals match pre-refactor baseline for same history
• no schema regression in /achievements response

---

J) Suggested File Placement for Future Work

• backend changes: dashboard/plugin_api.py
• optional extraction:
  • dashboard/perf_snapshot.py
  • dashboard/perf_scan_coordinator.py
• frontend request hygiene: dashboard/dist/index.js (or source if available)
• plugin metadata: dashboard/manifest.json
• persisted runtime files:
  • ~/.hermes/plugins/hermes-achievements/state.json (existing unlock state)
  • ~/.hermes/plugins/hermes-achievements/scan_snapshot.json (new)
  • ~/.hermes/plugins/hermes-achievements/scan_checkpoint.json (new)

---

K) Post-Implementation Reporting Template

Record:

• dataset size (sessions/messages/tool calls)
• pre/post /achievements timings (cold/warm)
• whether single-flight dedupe triggered under repeated tab open
• any behavioral diffs in unlock counts