forked from Zakaria/hermes-agent
Hermes-agent
This commit is contained in:
Zakaria
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 Hermes Achievements contributors
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -0,0 +1,150 @@
|
||||
# Hermes Achievements
|
||||
|
||||
> **Bundled with Hermes Agent.** Originally authored by [@PCinkusz](https://github.com/PCinkusz) at https://github.com/PCinkusz/hermes-achievements — vendored into `plugins/hermes-achievements/` so it ships with the dashboard out-of-the-box and stays in lockstep with Hermes feature changes. Upstream repo remains the staging ground for new badges and UI iteration.
|
||||
>
|
||||
> When Hermes is installed via `pip install hermes-agent` or cloned from source, this plugin auto-registers as a dashboard tab on first `hermes dashboard` launch. No separate install step. See [Built-in Plugins → hermes-achievements](../../website/docs/user-guide/features/built-in-plugins.md) in the main docs.
|
||||
|
||||
Achievement system for the Hermes Dashboard: collectible, tiered badges generated from real local Hermes session history.
|
||||
|
||||
|
||||
|
||||
The screenshots use temporary demo tier data to show the full visual range. The plugin itself reads real local Hermes session history by default.
|
||||
|
||||
> **Update notice (2026-04-29):** If you installed this plugin before today, update to the latest version. The achievements scan path was refactored for much faster warm loads (snapshot cache + incremental checkpoint scan).
|
||||
>
|
||||
> **Share cards (2026-05-04, vendored in hermes-agent v0.4.0):** Unlocked achievement cards now have a "Share" button that renders a 1200×630 PNG share card (client-side canvas, no backend, no network) with Download + Copy-to-clipboard actions. Fits X/Twitter, Discord, LinkedIn, Bluesky link-preview dimensions.
|
||||
|
||||
## What it does
|
||||
|
||||
Hermes Achievements scans local Hermes sessions and unlocks badges based on real agent behavior:
|
||||
|
||||
- autonomous tool chains
|
||||
- debugging and recovery patterns
|
||||
- vibe-coding file edits
|
||||
- Hermes-native skills, memory, cron, and plugin usage
|
||||
- web research and browser automation
|
||||
- model/provider workflows
|
||||
- lifestyle patterns such as weekend or night sessions
|
||||
|
||||
Achievements have three visible states:
|
||||
|
||||
- **Unlocked** — earned at least one tier
|
||||
- **Discovered** — known achievement, progress visible, not earned yet
|
||||
- **Secret** — hidden until Hermes detects the first related signal
|
||||
|
||||
Most achievements level through:
|
||||
|
||||
```text
|
||||
Copper → Silver → Gold → Diamond → Olympian
|
||||
```
|
||||
|
||||
Each card has a collapsible **What counts** section showing the exact tracked metric or requirement once the user wants details.
|
||||
|
||||
Version `0.2.x` expands the catalog to 60+ achievements, including model/provider badges such as **Five-Model Flight**, **Provider Polyglot**, **Claude Confidant**, **Gemini Cartographer**, and **Open Weights Pilgrim**.
|
||||
|
||||
## Examples
|
||||
|
||||
- Let Him Cook
|
||||
- Toolchain Maxxer
|
||||
- Red Text Connoisseur
|
||||
- Port 3000 Is Taken
|
||||
- This Was Supposed To Be Quick
|
||||
- One More Small Change
|
||||
- Skillsmith
|
||||
- Memory Keeper
|
||||
- Context Dragon
|
||||
- Plugin Goblin
|
||||
- Rabbit Hole Certified
|
||||
|
||||
## Install
|
||||
|
||||
Clone into your Hermes plugins directory:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/PCinkusz/hermes-achievements ~/.hermes/plugins/hermes-achievements
|
||||
```
|
||||
|
||||
For local development, keep the repo elsewhere and symlink it:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/PCinkusz/hermes-achievements ~/hermes-achievements
|
||||
ln -s ~/hermes-achievements ~/.hermes/plugins/hermes-achievements
|
||||
```
|
||||
|
||||
Then rescan dashboard plugins:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:9119/api/dashboard/plugins/rescan
|
||||
```
|
||||
|
||||
If backend API routes 404, restart `hermes dashboard`; plugin APIs are mounted at dashboard startup.
|
||||
|
||||
## Updating
|
||||
|
||||
If you installed with git:
|
||||
|
||||
```bash
|
||||
cd ~/.hermes/plugins/hermes-achievements
|
||||
git pull --ff-only
|
||||
curl http://127.0.0.1:9119/api/dashboard/plugins/rescan
|
||||
```
|
||||
|
||||
If the update changes backend routes or `plugin_api.py`, restart `hermes dashboard` after pulling.
|
||||
|
||||
As of 2026-04-29, updating is strongly recommended because scan performance changed significantly:
|
||||
- removed duplicate `/overview` scan path
|
||||
- added cached `/achievements` snapshot
|
||||
- added incremental checkpoint reuse for unchanged sessions
|
||||
|
||||
Achievement unlock state is stored locally in `state.json` and is not overwritten by git updates. New achievements are evaluated from your existing Hermes session history. Achievement IDs are stable and should not be renamed casually because they are the unlock-state keys.
|
||||
|
||||
Releases are tagged in git, for example:
|
||||
|
||||
```bash
|
||||
git fetch --tags
|
||||
git checkout v0.2.0
|
||||
```
|
||||
|
||||
## Files
|
||||
|
||||
```text
|
||||
dashboard/
|
||||
├── manifest.json
|
||||
├── plugin_api.py
|
||||
└── dist/
|
||||
├── index.js
|
||||
└── style.css
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
Routes are mounted under:
|
||||
|
||||
```text
|
||||
/api/plugins/hermes-achievements/
|
||||
```
|
||||
|
||||
Endpoints:
|
||||
|
||||
```text
|
||||
GET /achievements
|
||||
GET /scan-status
|
||||
GET /recent-unlocks
|
||||
GET /sessions/{session_id}/badges
|
||||
POST /rescan
|
||||
POST /reset-state
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
Run checks:
|
||||
|
||||
```bash
|
||||
node --check dashboard/dist/index.js
|
||||
python3 -m py_compile dashboard/plugin_api.py
|
||||
python3 -m unittest tests/test_achievement_engine.py -v
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
+726
File diff suppressed because one or more lines are too long
@@ -0,0 +1,146 @@
|
||||
/* hermes-achievements dashboard styles
|
||||
* Originally authored by @PCinkusz — https://github.com/PCinkusz/hermes-achievements (MIT).
|
||||
* Bundled into hermes-agent. The in-progress scan banner rules at the bottom
|
||||
* (.ha-scan-banner*) are a small addition layered on top of the original bundle.
|
||||
*/
|
||||
.ha-page { display: flex; flex-direction: column; gap: 1rem; }
|
||||
.ha-hero { position: relative; overflow: hidden; display: flex; align-items: flex-end; justify-content: space-between; gap: 1rem; border: 1px solid var(--color-border); background: radial-gradient(circle at 12% 0, rgba(103,232,249,.13), transparent 30%), linear-gradient(135deg, color-mix(in srgb, var(--color-card) 88%, transparent), color-mix(in srgb, var(--color-primary) 10%, transparent)); padding: 1.25rem; }
|
||||
.ha-hero:before { content: ""; position: absolute; inset: auto -10% -80% -10%; height: 180%; pointer-events: none; background: radial-gradient(circle, rgba(242,201,76,.12), transparent 55%); }
|
||||
.ha-hero h1 { position: relative; margin: 0; font-size: clamp(2rem, 4vw, 4.2rem); line-height: .9; letter-spacing: -0.06em; }
|
||||
.ha-hero p { position: relative; max-width: 52rem; margin: .65rem 0 0; color: var(--color-muted-foreground); }
|
||||
.ha-kicker { position: relative; color: var(--color-muted-foreground); text-transform: uppercase; letter-spacing: .18em; font-size: .72rem; font-family: var(--font-mono, ui-monospace, monospace); }
|
||||
.ha-refresh { position: relative; white-space: nowrap; }
|
||||
.ha-stats { display: grid; grid-template-columns: repeat(5, minmax(0, 1fr)); gap: .75rem; }
|
||||
.ha-stat-content { padding: 1rem !important; }
|
||||
.ha-stat-label { color: var(--color-muted-foreground); font-size: .75rem; text-transform: uppercase; letter-spacing: .12em; }
|
||||
.ha-stat-value { margin-top: .35rem; font-size: 1.4rem; font-weight: 750; letter-spacing: -0.035em; }
|
||||
.ha-stat-hint { margin-top: .2rem; color: var(--color-muted-foreground); font-size: .75rem; }
|
||||
.ha-toolbar { display: flex; justify-content: space-between; gap: .75rem; align-items: center; flex-wrap: wrap; }
|
||||
.ha-pills { display: flex; gap: .35rem; flex-wrap: wrap; }
|
||||
.ha-pills button { border: 1px solid var(--color-border); background: color-mix(in srgb, var(--color-card) 72%, transparent); color: var(--color-muted-foreground); padding: .35rem .6rem; font-size: .78rem; cursor: pointer; }
|
||||
.ha-pills button.active, .ha-pills button:hover { color: var(--color-foreground); border-color: var(--ha-tier, var(--color-ring)); background: color-mix(in srgb, var(--color-primary) 16%, var(--color-card)); }
|
||||
.ha-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(320px, 1fr)); gap: .9rem; }
|
||||
.ha-card { --ha-tier: var(--color-border); position: relative; overflow: hidden; min-height: 214px; border: 1px solid color-mix(in srgb, var(--ha-tier) 46%, var(--color-border)); background: radial-gradient(circle at 2.6rem 2.2rem, color-mix(in srgb, var(--ha-tier) 16%, transparent), transparent 34%), linear-gradient(180deg, rgba(255,255,255,.04), transparent), color-mix(in srgb, var(--color-card) 92%, #000); transition: transform .16s ease, border-color .16s ease, opacity .16s ease, box-shadow .16s ease; }
|
||||
.ha-card:hover { transform: translateY(-2px); border-color: var(--ha-tier); box-shadow: 0 0 0 1px color-mix(in srgb, var(--ha-tier) 16%, transparent); }
|
||||
.ha-card-content { position: relative; z-index: 1; padding: 1rem !important; display: flex; flex-direction: column; gap: .75rem; height: 100%; }
|
||||
.ha-card-head { display: grid; grid-template-columns: 3.1rem minmax(0, 1fr) auto; gap: .85rem; align-items: start; }
|
||||
.ha-icon { display: grid; place-items: center; width: 2.9rem; height: 2.9rem; color: var(--ha-tier); }
|
||||
.ha-lucide { width: 1.78rem; height: 1.78rem; stroke: currentColor; stroke-width: 2.15; filter: drop-shadow(0 0 8px color-mix(in srgb, var(--ha-tier) 24%, transparent)); }
|
||||
.ha-card-title { font-weight: 780; line-height: 1.05; letter-spacing: -0.025em; }
|
||||
.ha-card-category { margin-top: .28rem; color: var(--color-muted-foreground); font-size: .76rem; }
|
||||
.ha-badges { display: flex; flex-direction: column; align-items: flex-end; gap: .25rem; }
|
||||
.ha-tier-badge, .ha-state-badge { border: 1px solid var(--ha-tier); color: var(--ha-tier); background: color-mix(in srgb, var(--ha-tier) 10%, transparent); padding: .16rem .38rem; font-size: .67rem; text-transform: uppercase; letter-spacing: .08em; font-family: var(--font-mono, ui-monospace, monospace); }
|
||||
.ha-description { margin: 0; color: var(--color-muted-foreground); font-size: .86rem; line-height: 1.45; min-height: 2.4em; }
|
||||
.ha-criteria { border: 1px solid color-mix(in srgb, var(--ha-tier) 28%, var(--color-border)); background: color-mix(in srgb, var(--ha-tier) 5%, transparent); }
|
||||
.ha-criteria summary { cursor: pointer; padding: .5rem .65rem; color: var(--ha-tier); text-transform: uppercase; letter-spacing: .1em; font-size: .66rem; font-family: var(--font-mono, ui-monospace, monospace); user-select: none; }
|
||||
.ha-criteria summary:hover { background: color-mix(in srgb, var(--ha-tier) 8%, transparent); }
|
||||
.ha-criteria p { margin: 0; border-top: 1px solid color-mix(in srgb, var(--ha-tier) 18%, var(--color-border)); padding: .55rem .65rem .65rem; color: color-mix(in srgb, var(--color-foreground) 78%, var(--color-muted-foreground)); font-size: .76rem; line-height: 1.38; }
|
||||
.ha-progress-row { display: flex; align-items: center; gap: .55rem; margin-top: 0; }
|
||||
.ha-progress-track { flex: 1; height: .48rem; border: 1px solid color-mix(in srgb, var(--ha-tier) 34%, var(--color-border)); background: rgba(0,0,0,.22); overflow: hidden; }
|
||||
.ha-progress-fill { height: 100%; background: linear-gradient(90deg, var(--ha-tier), color-mix(in srgb, var(--ha-tier) 48%, white)); }
|
||||
.ha-progress-text { min-width: 5.4rem; text-align: right; font-family: var(--font-mono, ui-monospace, monospace); color: var(--color-muted-foreground); font-size: .72rem; }
|
||||
.ha-evidence-slot { min-height: 1.65rem; margin-top: auto; display: flex; align-items: flex-end; }
|
||||
.ha-evidence { width: 100%; display: flex; align-items: center; gap: .4rem; color: var(--color-muted-foreground); font-size: .72rem; min-width: 0; }
|
||||
.ha-evidence-label { text-transform: uppercase; letter-spacing: .09em; font-family: var(--font-mono, ui-monospace, monospace); flex: 0 0 auto; }
|
||||
.ha-evidence-title { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: color-mix(in srgb, var(--color-foreground) 84%, var(--color-muted-foreground)); }
|
||||
.ha-evidence-empty { visibility: hidden; }
|
||||
.ha-latest h2 { margin: 0 0 .5rem; font-size: 1rem; }
|
||||
.ha-latest-row { display: flex; gap: .5rem; flex-wrap: wrap; }
|
||||
.ha-chip { display: inline-flex; align-items: center; gap: .35rem; border: 1px solid var(--ha-tier); color: var(--ha-tier); background: color-mix(in srgb, var(--ha-tier) 10%, transparent); padding: .35rem .55rem; font-size: .8rem; }
|
||||
.ha-chip-icon .ha-lucide { width: .95rem; height: .95rem; }
|
||||
.ha-slot { border-style: dashed; }
|
||||
.ha-slot-content { display: flex; gap: .6rem; align-items: center; padding: .65rem .8rem !important; font-size: .82rem; }
|
||||
.ha-slot-star { color: #67e8f9; }
|
||||
.ha-slot-muted { color: var(--color-muted-foreground); margin-left: auto; }
|
||||
.ha-error { border-color: #ef4444; color: #fecaca; }
|
||||
.ha-loading { color: var(--color-muted-foreground); font-family: var(--font-mono, ui-monospace, monospace); padding: 2rem; border: 1px dashed var(--color-border); }
|
||||
.ha-guide { display: grid; grid-template-columns: minmax(0, 1.15fr) minmax(0, .85fr); gap: .75rem; }
|
||||
.ha-guide > div { border: 1px solid var(--color-border); background: color-mix(in srgb, var(--color-card) 82%, transparent); padding: .85rem 1rem; }
|
||||
.ha-guide strong { display: block; margin-bottom: .45rem; font-size: .78rem; text-transform: uppercase; letter-spacing: .12em; font-family: var(--font-mono, ui-monospace, monospace); }
|
||||
.ha-guide p { margin: 0; color: var(--color-muted-foreground); font-size: .84rem; line-height: 1.45; }
|
||||
.ha-tier-legend { display: flex; align-items: center; gap: .45rem; flex-wrap: wrap; }
|
||||
.ha-tier-step { --ha-tier: var(--color-border); display: inline-flex; align-items: center; gap: .32rem; color: var(--ha-tier); border: 1px solid color-mix(in srgb, var(--ha-tier) 52%, var(--color-border)); background: color-mix(in srgb, var(--ha-tier) 8%, transparent); padding: .28rem .45rem; font-size: .72rem; font-family: var(--font-mono, ui-monospace, monospace); text-transform: uppercase; letter-spacing: .06em; }
|
||||
.ha-tier-step i { width: .55rem; height: .55rem; background: var(--ha-tier); display: inline-block; }
|
||||
.ha-tier-arrow { color: var(--color-muted-foreground); }
|
||||
.ha-state-discovered { opacity: .92; }
|
||||
.ha-state-discovered .ha-card-title { color: color-mix(in srgb, var(--color-foreground) 82%, var(--ha-tier)); }
|
||||
.ha-state-secret { opacity: .5; filter: grayscale(.55); }
|
||||
.ha-state-secret:after { content: ""; position: absolute; inset: 0; pointer-events: none; background: repeating-linear-gradient(-45deg, transparent 0 8px, rgba(255,255,255,.035) 8px 10px); }
|
||||
.ha-tier-pending { --ha-tier: color-mix(in srgb, var(--color-muted-foreground) 64%, transparent); }
|
||||
.ha-tier-copper { --ha-tier: #b87333; }
|
||||
.ha-tier-silver { --ha-tier: #c0c7d2; }
|
||||
.ha-tier-gold { --ha-tier: #f2c94c; box-shadow: 0 0 22px rgba(242,201,76,.08); }
|
||||
.ha-tier-diamond { --ha-tier: #67e8f9; box-shadow: 0 0 24px rgba(103,232,249,.1); }
|
||||
.ha-tier-olympian { --ha-tier: #c084fc; box-shadow: 0 0 34px rgba(192,132,252,.18), 0 0 12px rgba(242,201,76,.1); }
|
||||
@media (max-width: 980px) { .ha-stats { grid-template-columns: repeat(2, minmax(0, 1fr)); } .ha-guide { grid-template-columns: 1fr; } }
|
||||
@media (max-width: 800px) { .ha-stats { grid-template-columns: 1fr; } .ha-hero { flex-direction: column; align-items: stretch; } .ha-card-head { grid-template-columns: 3.1rem 1fr; } .ha-badges { grid-column: 1 / -1; align-items: flex-start; flex-direction: row; } }
|
||||
|
||||
.ha-secret-empty-content { padding: 1rem !important; }
|
||||
.ha-secret-empty strong { display: block; margin-bottom: .35rem; }
|
||||
.ha-secret-empty p { margin: 0; color: var(--color-muted-foreground); font-size: .86rem; line-height: 1.45; }
|
||||
.ha-page-loading { animation: ha-fade-in .18s ease-out; }
|
||||
.ha-loading-hero { align-items: center; }
|
||||
.ha-scan-status { position: relative; z-index: 1; display: flex; align-items: center; gap: .8rem; min-width: 18rem; border: 1px solid color-mix(in srgb, #67e8f9 35%, var(--color-border)); background: color-mix(in srgb, var(--color-card) 78%, transparent); padding: .8rem .95rem; color: var(--color-foreground); }
|
||||
.ha-scan-status strong { display: block; font-size: .82rem; text-transform: uppercase; letter-spacing: .1em; font-family: var(--font-mono, ui-monospace, monospace); }
|
||||
.ha-scan-status p { margin: .25rem 0 0; font-size: .78rem; line-height: 1.35; color: var(--color-muted-foreground); }
|
||||
.ha-scan-pulse { width: .72rem; height: .72rem; flex: 0 0 auto; border-radius: 999px; background: #67e8f9; box-shadow: 0 0 0 0 rgba(103,232,249,.55); animation: ha-pulse 1.35s ease-out infinite; }
|
||||
.ha-skeleton-card { pointer-events: none; }
|
||||
.ha-skeleton { position: relative; overflow: hidden; border-radius: 0; background: color-mix(in srgb, var(--color-muted-foreground) 16%, transparent); }
|
||||
.ha-skeleton:after { content: ""; position: absolute; inset: 0; transform: translateX(-100%); background: linear-gradient(90deg, transparent, rgba(255,255,255,.14), transparent); animation: ha-shimmer 1.35s infinite; }
|
||||
.ha-skeleton-stack { display: flex; flex-direction: column; gap: .45rem; padding-top: .15rem; }
|
||||
.ha-skeleton-icon { width: 2.9rem; height: 2.9rem; }
|
||||
.ha-skeleton-title { width: 72%; height: .95rem; }
|
||||
.ha-skeleton-meta { width: 45%; height: .65rem; }
|
||||
.ha-skeleton-badge { width: 4.4rem; height: 1.05rem; }
|
||||
.ha-skeleton-badge-short { width: 3.6rem; }
|
||||
.ha-skeleton-line { height: .78rem; width: 92%; }
|
||||
.ha-skeleton-line-short { width: 68%; }
|
||||
.ha-skeleton-criteria { height: 2.2rem; width: 100%; border: 1px solid color-mix(in srgb, var(--color-muted-foreground) 18%, var(--color-border)); }
|
||||
.ha-skeleton-evidence { width: 58%; height: .8rem; }
|
||||
.ha-skeleton-progress { flex: 1; height: .48rem; }
|
||||
.ha-skeleton-progress-text { width: 4.6rem; height: .75rem; }
|
||||
.ha-skeleton-stat-value { width: 56%; height: 1.35rem; margin-top: .55rem; }
|
||||
.ha-skeleton-stat-hint { width: 76%; height: .7rem; margin-top: .55rem; }
|
||||
.ha-loading-guide p { color: var(--color-muted-foreground); }
|
||||
@keyframes ha-shimmer { 100% { transform: translateX(100%); } }
|
||||
@keyframes ha-pulse { 0% { box-shadow: 0 0 0 0 rgba(103,232,249,.48); } 70% { box-shadow: 0 0 0 .65rem rgba(103,232,249,0); } 100% { box-shadow: 0 0 0 0 rgba(103,232,249,0); } }
|
||||
@keyframes ha-fade-in { from { opacity: 0; transform: translateY(3px); } to { opacity: 1; transform: translateY(0); } }
|
||||
.ha-loading-hero p, .ha-scan-status p, .ha-loading-guide p { text-transform: none; letter-spacing: normal; }
|
||||
|
||||
/* In-progress scan banner — shown on the main page while the background scan
|
||||
* is still walking through session history, so the user sees continuous
|
||||
* progress (X / Y sessions · Z%) instead of guessing whether anything is
|
||||
* happening. Reuses .ha-scan-pulse + ha-pulse keyframes from the loading page.
|
||||
*/
|
||||
.ha-scan-banner { display: flex; flex-direction: column; gap: .6rem; border: 1px solid color-mix(in srgb, #67e8f9 35%, var(--color-border)); background: color-mix(in srgb, var(--color-card) 78%, transparent); padding: .8rem .95rem; animation: ha-fade-in .18s ease-out; }
|
||||
.ha-scan-banner-head { display: flex; align-items: center; gap: .8rem; }
|
||||
.ha-scan-banner-text strong { display: block; font-size: .82rem; text-transform: uppercase; letter-spacing: .1em; font-family: var(--font-mono, ui-monospace, monospace); color: var(--color-foreground); }
|
||||
.ha-scan-banner-text p { margin: .25rem 0 0; font-size: .78rem; line-height: 1.35; color: var(--color-muted-foreground); text-transform: none; letter-spacing: normal; }
|
||||
.ha-scan-progress-track { height: .4rem; border: 1px solid color-mix(in srgb, #67e8f9 28%, var(--color-border)); background: rgba(0,0,0,.22); overflow: hidden; }
|
||||
.ha-scan-progress-fill { height: 100%; background: linear-gradient(90deg, #67e8f9, color-mix(in srgb, #67e8f9 48%, white)); transition: width .4s ease-out; }
|
||||
|
||||
/* Share achievement — trigger button on unlocked cards + modal dialog.
|
||||
* Added to the vendored bundle (on top of the upstream PCinkusz base).
|
||||
* Canvas rendering is pure client-side, no backend, no network.
|
||||
*/
|
||||
.ha-share-trigger { border: 1px solid color-mix(in srgb, var(--ha-tier) 58%, var(--color-border)); color: var(--ha-tier); background: color-mix(in srgb, var(--ha-tier) 8%, transparent); padding: .18rem .42rem; font-size: .66rem; text-transform: uppercase; letter-spacing: .08em; font-family: var(--font-mono, ui-monospace, monospace); cursor: pointer; margin-top: .05rem; transition: background .12s ease, border-color .12s ease; }
|
||||
.ha-share-trigger:hover { background: color-mix(in srgb, var(--ha-tier) 20%, transparent); border-color: var(--ha-tier); }
|
||||
.ha-share-trigger:focus-visible { outline: 2px solid var(--ha-tier); outline-offset: 2px; }
|
||||
|
||||
.ha-share-backdrop { position: fixed; inset: 0; z-index: 1000; background: rgba(4,6,10,.72); backdrop-filter: blur(6px); display: flex; align-items: center; justify-content: center; padding: 1.5rem; animation: ha-fade-in .14s ease-out; }
|
||||
.ha-share-dialog { width: min(760px, 100%); max-height: calc(100vh - 3rem); overflow: auto; border: 1px solid color-mix(in srgb, var(--color-border) 70%, var(--color-ring)); background: color-mix(in srgb, var(--color-card) 94%, #000); box-shadow: 0 24px 60px rgba(0,0,0,.55); display: flex; flex-direction: column; gap: .9rem; padding: 1rem 1.1rem 1.1rem; }
|
||||
.ha-share-head { display: flex; align-items: center; justify-content: space-between; gap: .75rem; }
|
||||
.ha-share-head strong { font-size: .82rem; text-transform: uppercase; letter-spacing: .1em; font-family: var(--font-mono, ui-monospace, monospace); color: var(--color-foreground); }
|
||||
.ha-share-close { width: 1.9rem; height: 1.9rem; display: grid; place-items: center; border: 1px solid var(--color-border); background: transparent; color: var(--color-muted-foreground); font-size: 1.1rem; cursor: pointer; line-height: 1; }
|
||||
.ha-share-close:hover { color: var(--color-foreground); border-color: var(--color-ring); }
|
||||
.ha-share-preview { position: relative; border: 1px solid var(--color-border); background: #0b0d11; overflow: hidden; aspect-ratio: 1200 / 630; }
|
||||
.ha-share-preview img { display: block; width: 100%; height: 100%; object-fit: contain; }
|
||||
.ha-share-placeholder { position: absolute; inset: 0; display: grid; place-items: center; color: var(--color-muted-foreground); font-family: var(--font-mono, ui-monospace, monospace); font-size: .82rem; text-transform: uppercase; letter-spacing: .1em; animation: ha-pulse 1.4s ease-in-out infinite; border-radius: 0; }
|
||||
.ha-share-error { border: 1px solid #ef4444; color: #fecaca; background: color-mix(in srgb, #ef4444 10%, transparent); padding: .55rem .7rem; font-size: .78rem; font-family: var(--font-mono, ui-monospace, monospace); }
|
||||
.ha-share-actions { display: flex; gap: .55rem; flex-wrap: wrap; }
|
||||
.ha-share-btn { border: 1px solid var(--color-border); background: color-mix(in srgb, var(--color-card) 72%, transparent); color: var(--color-foreground); padding: .5rem .85rem; font-size: .82rem; font-family: var(--font-mono, ui-monospace, monospace); text-transform: uppercase; letter-spacing: .08em; cursor: pointer; transition: border-color .12s ease, background .12s ease; }
|
||||
.ha-share-btn:hover:not(:disabled) { border-color: var(--color-ring); background: color-mix(in srgb, var(--color-primary) 16%, var(--color-card)); }
|
||||
.ha-share-btn:disabled { opacity: .5; cursor: not-allowed; }
|
||||
.ha-share-btn-primary { border-color: #ffffff; color: #ffffff; background: #000000; }
|
||||
.ha-share-btn-primary:hover:not(:disabled) { background: #1a1a1a; border-color: #67e8f9; color: #67e8f9; }
|
||||
.ha-share-hint { margin: 0; color: var(--color-muted-foreground); font-size: .76rem; line-height: 1.45; }
|
||||
@@ -0,0 +1,11 @@
|
||||
{
|
||||
"name": "hermes-achievements",
|
||||
"label": "Achievements",
|
||||
"description": "Steam-style achievements for vibe coding and agentic Hermes workflows.",
|
||||
"icon": "Star",
|
||||
"version": "0.4.0",
|
||||
"tab": { "path": "/achievements", "position": "after:analytics" },
|
||||
"entry": "dist/index.js",
|
||||
"css": "dist/style.css",
|
||||
"api": "plugin_api.py"
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,157 @@
|
||||
# Hermes Achievements Performance Implementation Plan
|
||||
|
||||
Status: Ready for execution after hackathon review window
|
||||
Constraint: Plugin remains frozen until judging is complete
|
||||
Decision: `/overview` and top-banner slots are out of scope and will be removed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — Baseline & Safety (no behavior change)
|
||||
|
||||
### Task 0.1: Add perf benchmark script (local)
|
||||
Objective: Repro baseline before/after.
|
||||
|
||||
Acceptance:
|
||||
- Can print endpoint timings for `/achievements` (3 runs each, cold + warm).
|
||||
|
||||
### Task 0.2: Define acceptance thresholds
|
||||
Objective: Lock success criteria now.
|
||||
|
||||
Acceptance:
|
||||
- Documented SLOs:
|
||||
- `/achievements` p95 < 1s (cached)
|
||||
- max active scan jobs = 1
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Remove unused overview/slot surface (highest certainty)
|
||||
|
||||
### Task 1.1: Remove `/overview` backend route
|
||||
Objective: Eliminate duplicate heavy endpoint path.
|
||||
|
||||
Acceptance:
|
||||
- `plugin_api.py` no longer exposes `/overview`.
|
||||
|
||||
### Task 1.2: Remove slot registration and SummarySlot frontend code
|
||||
Objective: Remove cross-tab banner fetch behavior.
|
||||
|
||||
Acceptance:
|
||||
- No `registerSlot(..."sessions:top"...)` or `registerSlot(..."analytics:top"...)`.
|
||||
- No frontend call to `api("/overview")`.
|
||||
|
||||
### Task 1.3: Update plugin manifest
|
||||
Objective: Reflect final UI scope.
|
||||
|
||||
Acceptance:
|
||||
- `manifest.json` removes `slots` declarations.
|
||||
- Tab registration remains intact.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Shared snapshot persistence + single-flight for `/achievements`
|
||||
|
||||
### Task 2.1: Introduce snapshot store abstraction + on-disk persistence
|
||||
Objective: Single source of truth for Achievements data that survives process restarts.
|
||||
|
||||
Acceptance:
|
||||
- One structure contains dataset consumed by `/achievements`.
|
||||
- Repeated requests do not recompute when cache is fresh.
|
||||
- Snapshot persisted at `~/.hermes/plugins/hermes-achievements/scan_snapshot.json`.
|
||||
|
||||
### Task 2.2: Single-flight scan coordinator
|
||||
Objective: Prevent concurrent recomputes.
|
||||
|
||||
Acceptance:
|
||||
- Simultaneous requests result in one compute run.
|
||||
|
||||
### Task 2.3: Refactor `/achievements` to read snapshot
|
||||
Objective: Remove direct repeated compute from request path.
|
||||
|
||||
Acceptance:
|
||||
- `/achievements` does not run independent full recompute per request when cache is valid.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Stale-While-Revalidate
|
||||
|
||||
### Task 3.1: TTL state (`FRESH`/`STALE`)
|
||||
Objective: Serve immediately when stale, refresh in background.
|
||||
|
||||
Acceptance:
|
||||
- Cached response returned quickly even when expired.
|
||||
- Refresh is asynchronous.
|
||||
|
||||
### Task 3.2: Add `scan-status` endpoint (optional)
|
||||
Objective: Let UI/ops inspect scan state.
|
||||
|
||||
Acceptance:
|
||||
- Returns state, last success time, last duration, last error.
|
||||
|
||||
### Task 3.3: Add metadata fields to `/achievements`
|
||||
Objective: Improve transparency.
|
||||
|
||||
Acceptance:
|
||||
- Response includes `generated_at`, `is_stale`, maybe `scan_id`.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Incremental Scanning (optional but recommended)
|
||||
|
||||
### Task 4.1: Add per-session checkpoint file
|
||||
Objective: Track session-level changes, not just global scan time.
|
||||
|
||||
Acceptance:
|
||||
- Checkpoint persisted at `~/.hermes/plugins/hermes-achievements/scan_checkpoint.json`.
|
||||
- For each session: `session_id`, fingerprint (`updated_at`/message_count/hash), and cached contribution.
|
||||
|
||||
### Task 4.2: Incremental aggregation
|
||||
Objective: Recompute only changed/new sessions and reuse unchanged contributions.
|
||||
|
||||
Acceptance:
|
||||
- Typical refresh time drops materially below full scan.
|
||||
- Aggregate rebuild uses: subtract old contribution + add new contribution for changed sessions.
|
||||
|
||||
### Task 4.3: Full rebuild fallback
|
||||
Objective: Preserve correctness.
|
||||
|
||||
Acceptance:
|
||||
- Manual full rescan always possible.
|
||||
- Schema/version changes invalidate checkpoint and force full rebuild.
|
||||
|
||||
---
|
||||
|
||||
## Test Plan
|
||||
|
||||
1. Unit tests
|
||||
- Snapshot lifecycle transitions
|
||||
- Dedupe logic under parallel requests
|
||||
- `/achievements` response compatibility
|
||||
|
||||
2. Integration tests
|
||||
- Opening Achievements repeatedly causes <=1 heavy scan while in-flight
|
||||
- `/achievements` warm-cache load is fast
|
||||
- manual rescan updates snapshot and timestamps
|
||||
|
||||
3. Manual benchmarks
|
||||
- Compare pre/post `/achievements` timings with same history dataset
|
||||
|
||||
---
|
||||
|
||||
## Rollout Plan
|
||||
|
||||
1. Release internal branch with Phase 1 (remove overview/slots).
|
||||
2. Validate no UI regression in Achievements tab.
|
||||
3. Add Phase 2 snapshot/dedupe.
|
||||
4. Add Phase 3 stale-while-revalidate + status metadata.
|
||||
5. Optional: incremental scanner.
|
||||
|
||||
Rollback: keep old compute path behind temporary feature flag for one release window.
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- Achievements tab remains fully functional (counts, latest, tiers, cards, filters).
|
||||
- No `/overview` endpoint or slot calls remain.
|
||||
- Repeated Achievements loads feel immediate after warm cache.
|
||||
- Metrics/unlocks remain unchanged versus baseline.
|
||||
@@ -0,0 +1,219 @@
|
||||
# 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)
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
```json
|
||||
{
|
||||
"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
|
||||
@@ -0,0 +1,174 @@
|
||||
# Hermes Achievements Performance Spec (Post-Hackathon)
|
||||
|
||||
Status: Draft (no code changes yet)
|
||||
Owner: hermes-achievements plugin
|
||||
Scope: `dashboard/plugin_api.py` + `dashboard/dist/index.js` request behavior
|
||||
Decision: **Drop `/overview` and top-banner slots**; keep only Achievements tab data path.
|
||||
|
||||
---
|
||||
|
||||
## 1) Problem Statement
|
||||
|
||||
Current plugin endpoints `/achievements` and `/overview` both execute a full history recomputation (`evaluate_all()`), which performs a full SessionDB scan each request.
|
||||
|
||||
Observed on this machine/repo:
|
||||
- ~83 sessions
|
||||
- ~7,125 messages
|
||||
- ~3,623 tool calls
|
||||
- `evaluate_all()` ~13–16s per call
|
||||
- `/achievements` ~13–15s per call
|
||||
- `/overview` ~12–15s per call
|
||||
- Overlap between endpoints increases perceived wait.
|
||||
|
||||
Given current product direction, `/overview` and cross-tab top-banner slots are not needed.
|
||||
|
||||
---
|
||||
|
||||
## 2) Goals
|
||||
|
||||
- Keep achievement correctness unchanged.
|
||||
- Keep all Achievements-tab UX/data (unlocked/discovered/secrets/highest/latest/cards).
|
||||
- Remove unused summary path (`/overview`) and slot wiring.
|
||||
- Make Achievements tab faster by avoiding duplicate endpoint pathways.
|
||||
- Ensure at most one heavy scan can run at a time.
|
||||
|
||||
Non-goals (phase 1):
|
||||
- Rewriting achievement rules.
|
||||
- Changing badge semantics/states.
|
||||
|
||||
---
|
||||
|
||||
## 3) Endpoint Semantics (Target)
|
||||
|
||||
### `GET /api/plugins/hermes-achievements/achievements`
|
||||
Single source endpoint for Achievements UI.
|
||||
Returns full payload used by the tab:
|
||||
- `achievements`
|
||||
- `unlocked_count`
|
||||
- `discovered_count`
|
||||
- `secret_count`
|
||||
- `total_count`
|
||||
- `error`
|
||||
|
||||
### `POST /api/plugins/hermes-achievements/rescan` (optional)
|
||||
Manual refresh trigger.
|
||||
Prefer async trigger + immediate status response.
|
||||
|
||||
### `GET /api/plugins/hermes-achievements/scan-status` (optional new)
|
||||
Reports scan state for UX/ops.
|
||||
|
||||
### Removed
|
||||
- `GET /api/plugins/hermes-achievements/overview`
|
||||
|
||||
---
|
||||
|
||||
## 4) UI Scope (Target)
|
||||
|
||||
Keep:
|
||||
- Achievements page/tab (`/achievements` in plugin tab manifest)
|
||||
- All existing Achievements tab stats/cards/filters
|
||||
|
||||
Remove:
|
||||
- Top-banner summary slot components using `sessions:top` and `analytics:top`
|
||||
- Any frontend call path to `/overview`
|
||||
|
||||
---
|
||||
|
||||
## 5) Runtime State Machine (for `/achievements`)
|
||||
|
||||
- `FRESH`: cached snapshot age <= TTL
|
||||
- `STALE`: snapshot exists but expired
|
||||
- `SCANNING`: background recompute running
|
||||
- `FAILED`: last recompute failed, last good snapshot still served
|
||||
|
||||
Rules:
|
||||
1. FRESH -> serve immediately.
|
||||
2. STALE + not scanning -> serve stale snapshot immediately and launch background refresh.
|
||||
3. SCANNING -> do not start another scan; join single-flight in-flight job.
|
||||
4. No snapshot yet -> allow one blocking bootstrap scan.
|
||||
|
||||
---
|
||||
|
||||
## 6) Caching & Invalidation
|
||||
|
||||
### Phase 1
|
||||
- In-memory cache + persisted snapshot file.
|
||||
- TTL: 60–180 seconds (configurable).
|
||||
- Single-flight dedupe for scan requests.
|
||||
- Persist plugin data under:
|
||||
- `~/.hermes/plugins/hermes-achievements/scan_snapshot.json`
|
||||
|
||||
### Phase 2
|
||||
- Incremental scan checkpoints with per-session fingerprints.
|
||||
- Persist checkpoint data under:
|
||||
- `~/.hermes/plugins/hermes-achievements/scan_checkpoint.json`
|
||||
- Checkpoint stores, per session:
|
||||
- `session_id`
|
||||
- fingerprint (`updated_at`, message_count, or hash)
|
||||
- cached per-session contribution used for aggregate recomposition
|
||||
- Scan policy:
|
||||
- First run: full scan and materialize snapshot + checkpoint.
|
||||
- Next runs: process only new/changed sessions, reuse unchanged contributions.
|
||||
- Full rebuild only on:
|
||||
- schema/version change
|
||||
- checkpoint corruption
|
||||
- explicit full rescan
|
||||
|
||||
---
|
||||
|
||||
## 7) Frontend Contract
|
||||
|
||||
- Achievements tab requests `/achievements` once on mount.
|
||||
- No slot-based summary fetches.
|
||||
- If response says `is_stale=true`, UI may display “Updating in background”.
|
||||
- Avoid duplicate mount-triggered calls and cancel stale requests on navigation.
|
||||
|
||||
---
|
||||
|
||||
## 8) SLO Targets
|
||||
|
||||
- `/achievements` p95 < 1s (cached)
|
||||
- Max concurrent heavy scans: 1
|
||||
- Background refresh should not block UI
|
||||
|
||||
---
|
||||
|
||||
## 9) Observability Requirements
|
||||
|
||||
Track:
|
||||
- scan count
|
||||
- scan duration avg/p95
|
||||
- dedupe hit count (joined in-flight scans)
|
||||
- stale-served count
|
||||
- failures + last error
|
||||
|
||||
Expose minimal diagnostics in `/scan-status`.
|
||||
|
||||
---
|
||||
|
||||
## 10) Backward Compatibility
|
||||
|
||||
- Keep `/achievements` response shape backward-compatible.
|
||||
- Removing `/overview` is acceptable because slot UI is intentionally removed.
|
||||
- If temporary compatibility is needed, `/overview` can return static deprecation response for one release.
|
||||
|
||||
---
|
||||
|
||||
## 11) Risks
|
||||
|
||||
- Stale data confusion -> mitigate with `generated_at` and explicit refresh status.
|
||||
- Cache invalidation bugs -> start with conservative TTL + manual rescan.
|
||||
- Concurrency bugs -> protect scan section with lock/single-flight guard.
|
||||
- Session mutation edge cases -> use per-session fingerprint invalidation (not global timestamp only).
|
||||
|
||||
---
|
||||
|
||||
## 12) Persistence Files (Explicit)
|
||||
|
||||
Plugin state directory:
|
||||
- `~/.hermes/plugins/hermes-achievements/`
|
||||
|
||||
Files:
|
||||
- `state.json` (existing): unlock tracking
|
||||
- `scan_snapshot.json` (new): latest materialized achievements payload
|
||||
- `scan_checkpoint.json` (new): per-session fingerprints + contributions for incremental refresh
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.4 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 1.3 MiB |
@@ -0,0 +1,156 @@
|
||||
import importlib.util
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
MODULE_PATH = Path(__file__).resolve().parents[1] / "dashboard" / "plugin_api.py"
|
||||
spec = importlib.util.spec_from_file_location("plugin_api", MODULE_PATH)
|
||||
plugin_api = importlib.util.module_from_spec(spec)
|
||||
spec.loader.exec_module(plugin_api)
|
||||
|
||||
|
||||
class AchievementEngineTests(unittest.TestCase):
|
||||
def test_tool_call_stats_detect_tool_names_and_errors(self):
|
||||
messages = [
|
||||
{"role": "assistant", "tool_calls": [{"function": {"name": "terminal"}}]},
|
||||
{"role": "tool", "tool_name": "terminal", "content": "Error: port 3000 already in use"},
|
||||
{"role": "assistant", "tool_calls": [{"function": {"name": "web_search"}}]},
|
||||
]
|
||||
|
||||
stats = plugin_api.analyze_messages("s1", "Fix dev server", messages)
|
||||
|
||||
self.assertEqual(stats["tool_call_count"], 2)
|
||||
self.assertEqual(stats["tool_names"], {"terminal", "web_search"})
|
||||
self.assertEqual(stats["error_count"], 1)
|
||||
self.assertIs(stats["port_conflict"], True)
|
||||
|
||||
def test_tiered_achievement_reaches_highest_matching_tier(self):
|
||||
definition = {
|
||||
"id": "let_him_cook",
|
||||
"threshold_metric": "max_tool_calls_in_session",
|
||||
"tiers": [
|
||||
{"name": "Copper", "threshold": 10},
|
||||
{"name": "Silver", "threshold": 25},
|
||||
{"name": "Gold", "threshold": 50},
|
||||
],
|
||||
}
|
||||
aggregate = {"max_tool_calls_in_session": 28}
|
||||
|
||||
result = plugin_api.evaluate_tiered(definition, aggregate)
|
||||
|
||||
self.assertIs(result["unlocked"], True)
|
||||
self.assertEqual(result["tier"], "Silver")
|
||||
self.assertEqual(result["progress"], 28)
|
||||
self.assertEqual(result["next_tier"], "Gold")
|
||||
|
||||
def test_tiered_achievement_can_be_discovered_without_unlocking(self):
|
||||
definition = {
|
||||
"id": "terminal_goblin",
|
||||
"threshold_metric": "total_terminal_calls",
|
||||
"tiers": [{"name": "Copper", "threshold": 50}],
|
||||
}
|
||||
aggregate = {"total_terminal_calls": 12}
|
||||
|
||||
result = plugin_api.evaluate_tiered(definition, aggregate)
|
||||
|
||||
self.assertIs(result["unlocked"], False)
|
||||
self.assertIs(result["discovered"], True)
|
||||
self.assertEqual(result["state"], "discovered")
|
||||
self.assertEqual(result["progress"], 12)
|
||||
self.assertEqual(result["next_threshold"], 50)
|
||||
|
||||
def test_secret_achievement_stays_hidden_without_progress(self):
|
||||
definition = {
|
||||
"id": "permission_denied_any_percent",
|
||||
"name": "Permission Denied Any%",
|
||||
"secret": True,
|
||||
"requirements": [{"metric": "permission_denied_events", "gte": 3}],
|
||||
}
|
||||
aggregate = {"permission_denied_events": 0}
|
||||
|
||||
result = plugin_api.evaluate_requirements(definition, aggregate)
|
||||
display = plugin_api.display_achievement({**definition, **result})
|
||||
|
||||
self.assertEqual(result["state"], "secret")
|
||||
self.assertEqual(display["name"], "???")
|
||||
self.assertNotIn("Permission", display["description"])
|
||||
|
||||
def test_multi_condition_unlock_requires_all_requirements(self):
|
||||
definition = {
|
||||
"id": "full_send",
|
||||
"requirements": [
|
||||
{"metric": "max_terminal_calls_in_session", "gte": 10},
|
||||
{"metric": "max_file_tool_calls_in_session", "gte": 5},
|
||||
{"metric": "max_web_calls_in_session", "gte": 2},
|
||||
],
|
||||
}
|
||||
|
||||
partial = plugin_api.evaluate_requirements(definition, {
|
||||
"max_terminal_calls_in_session": 12,
|
||||
"max_file_tool_calls_in_session": 2,
|
||||
"max_web_calls_in_session": 0,
|
||||
})
|
||||
complete = plugin_api.evaluate_requirements(definition, {
|
||||
"max_terminal_calls_in_session": 12,
|
||||
"max_file_tool_calls_in_session": 6,
|
||||
"max_web_calls_in_session": 2,
|
||||
})
|
||||
|
||||
self.assertEqual(partial["state"], "discovered")
|
||||
self.assertIs(partial["unlocked"], False)
|
||||
self.assertLess(partial["progress_pct"], 100)
|
||||
self.assertEqual(complete["state"], "unlocked")
|
||||
self.assertIs(complete["unlocked"], True)
|
||||
|
||||
def test_catalog_has_60_plus_unique_achievements(self):
|
||||
ids = [achievement["id"] for achievement in plugin_api.ACHIEVEMENTS]
|
||||
self.assertGreaterEqual(len(ids), 60)
|
||||
self.assertEqual(len(ids), len(set(ids)))
|
||||
|
||||
def test_model_provider_metrics_are_aggregated(self):
|
||||
sessions = [
|
||||
{"model_names": {"openai/gpt-5", "anthropic/claude-sonnet-4"}},
|
||||
{"model_names": {"google/gemini-pro", "mistral/large"}},
|
||||
{"model_names": {"qwen/qwen3"}},
|
||||
]
|
||||
|
||||
aggregate = plugin_api.aggregate_stats(sessions)
|
||||
|
||||
self.assertEqual(aggregate["distinct_model_count"], 5)
|
||||
self.assertEqual(aggregate["distinct_provider_count"], 5)
|
||||
result = plugin_api.evaluate_definition(
|
||||
next(a for a in plugin_api.ACHIEVEMENTS if a["id"] == "five_model_flight"),
|
||||
aggregate,
|
||||
)
|
||||
self.assertEqual(result["state"], "unlocked")
|
||||
self.assertEqual(result["tier"], "Copper")
|
||||
|
||||
def test_removed_noisy_achievements_are_not_in_catalog(self):
|
||||
ids = {achievement["id"] for achievement in plugin_api.ACHIEVEMENTS}
|
||||
self.assertNotIn("fallback_pilot", ids)
|
||||
self.assertNotIn("browser_sleuth", ids)
|
||||
self.assertNotIn("release_ritualist", ids)
|
||||
|
||||
def test_open_weights_pilgrim_counts_only_local_model_metadata(self):
|
||||
aggregate_mentions_only = plugin_api.aggregate_stats([
|
||||
{"model_names": {"openai/gpt-5"}, "local_model_events": 999},
|
||||
])
|
||||
aggregate_local_chat = plugin_api.aggregate_stats([
|
||||
{"model_names": {"openai/gpt-5"}},
|
||||
{"model_names": {"ollama/llama3"}},
|
||||
])
|
||||
definition = next(a for a in plugin_api.ACHIEVEMENTS if a["id"] == "open_weights_pilgrim")
|
||||
|
||||
self.assertEqual(aggregate_mentions_only["local_model_chat_sessions"], 0)
|
||||
self.assertEqual(plugin_api.evaluate_definition(definition, aggregate_mentions_only)["state"], "discovered")
|
||||
self.assertEqual(aggregate_local_chat["local_model_chat_sessions"], 1)
|
||||
self.assertEqual(plugin_api.evaluate_definition(definition, aggregate_local_chat)["state"], "unlocked")
|
||||
|
||||
def test_config_surgeon_ignores_generic_config_mentions(self):
|
||||
stats = plugin_api.analyze_messages("s1", "Config talk", [{"content": "config config configuration not configured"}])
|
||||
self.assertEqual(stats["config_events"], 0)
|
||||
stats = plugin_api.analyze_messages("s2", "Real config", [{"content": "edited config.yaml, manifest.json, and .env.local"}])
|
||||
self.assertGreaterEqual(stats["config_events"], 3)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user