@bitseek/hermes-webui 0.1.0-beta.0

package/vendor/agent-frontend-shell/CONTRIBUTING.md

@@ -0,0 +1,205 @@
+# Contributing to Hermes WebUI
+
+Thanks for contributing.
+
+Hermes WebUI is intentionally simple to work on: Python on the server, vanilla JS in the browser, no build step, no bundler, no frontend framework. The best pull requests preserve that simplicity while solving a real problem cleanly.
+
+## Before You Start
+
+- Read [`AGENTS.md`](AGENTS.md) if an AI assistant is doing or helping with the
+  change.
+- Read [`docs/CONTRACTS.md`](docs/CONTRACTS.md) and any linked contract/RFC for
+  the subsystem you will touch.
+- For UI or UX work, read [`docs/UIUX-GUIDE.md`](docs/UIUX-GUIDE.md)
+  and [`DESIGN.md`](DESIGN.md).
+- For runtime, streaming, recovery, replay, compression, context reconstruction,
+  or session metadata work, start with [`docs/rfcs/README.md`](docs/rfcs/README.md)
+  and the relevant RFC listed there.
+
+Use those documents as review guardrails: keep the change scoped, preserve the
+no-build-step architecture, update docs/changelog when behavior changes, include
+UI evidence for UI changes, and add tests for behavior changes where practical.
+
+### Contract-affecting PRs
+
+A contract-affecting PR is any change that updates a public contract document,
+an RFC, a contributor guide, a product-semantics test, or behavior that those
+documents already describe. These PRs need an explicit `Contract Routing` section
+in the PR body that names the touched contract family and the evidence used.
+See [`docs/CONTRACTS.md#contract-routing`](docs/CONTRACTS.md#contract-routing)
+for the short routing shape and [`docs/CONTRACTS.md#contract-changes`](docs/CONTRACTS.md#contract-changes)
+for intentional contract changes.
+
+If the PR intentionally changes an existing contract, add a `Contract Change`
+section that states the old rule, the new rule, and why the change is justified.
+Do not silently redefine product behavior by changing tests alone; update the
+corresponding docs in the same PR.
+
+A release batch should call out included contract-affecting PRs separately
+from ordinary fixes, even when the code diff is small and CI is green.
+
+## Two Paths to a Strong Pull Request
+
+### Path 1: Small, Focused Changes
+
+This is the fastest path to review and merge.
+
+- Fix one clear bug or add one tightly scoped improvement
+- Touch the fewest files you can
+- Avoid drive-by refactors mixed into functional changes
+- Run the relevant tests locally before opening the PR
+- Keep the PR description concise and specific
+
+These are the changes that are easiest to review and safest to merge quickly.
+
+### Path 2: Bigger Changes
+
+If you want to change architecture, reshape a workflow, add a substantial UI feature, or alter core behavior, align on direction first.
+
+- Open an issue, start a discussion, or open a draft PR early
+- Explain the problem you are solving, not just the implementation you want
+- Call out tradeoffs, migration risk, and any alternatives you considered
+- Keep the final PR easy to review by separating unrelated work
+
+Large changes are welcome, but surprise rewrites are hard to review well.
+
+## What We Expect in Every PR
+
+### 1. One Logical Change Per PR
+
+Keep each PR focused. A small related group of fixes is fine. A bug fix plus a CSS cleanup plus a refactor plus a docs rewrite is not.
+
+### 2. Local Verification
+
+Run the test suite locally:
+
+```bash
+pytest tests/ -v --timeout=60
+```
+
+CI also runs this suite on Python `3.11`, `3.12`, and `3.13`.
+
+If your change affects browser behavior, also run the relevant manual checks from [TESTING.md](TESTING.md).
+
+### 3. Clear PR Description
+
+There is currently no PR template in this repo, so include the important sections yourself:
+
+- Thinking Path
+- What Changed
+- Why It Matters
+- Verification
+- Risks / Follow-ups
+- Model Used
+
+If the change is user-visible, include screenshots or a short video.
+
+For UI or UX changes, before/after images are required. PRs that change the interface or interaction flow without before/after images may not receive meaningful review until that evidence is added.
+
+### 4. AI Usage Disclosure
+
+If AI helped produce the change, say so in the PR description.
+
+Include:
+
+- Provider
+- Exact model name or ID
+- Any notable mode or tool use that mattered
+
+If no AI was used, write: `None — human-authored`.
+
+### 5. Keep the Docs Honest
+
+If your change alters behavior, architecture, testing, setup, or user-facing workflows, update the relevant docs in the same PR.
+
+Common files:
+
+- [README.md](README.md) for setup, usage, and contributor-facing commands
+- [ROADMAP.md](ROADMAP.md) for shipped features and sprint history
+- [ARCHITECTURE.md](ARCHITECTURE.md) for implementation details and design constraints
+- [TESTING.md](TESTING.md) for manual and automated verification guidance
+- [CHANGELOG.md](CHANGELOG.md) when maintainers want release-note-ready entries
+
+## Project-Specific Guidelines
+
+### Preserve the Design Constraints
+
+Hermes WebUI is deliberately:
+
+- No build step
+- No bundler
+- No frontend framework
+- Easy to modify from a terminal
+
+Do not introduce new infrastructure or dependencies unless the gain is clear and the tradeoff is justified.
+
+### Match the Existing Shape of the Codebase
+
+- Server logic belongs in `api/` with `server.py` staying thin
+- Frontend behavior belongs in the existing `static/*.js` modules
+- Prefer extending current patterns over introducing parallel abstractions
+- Keep changes legible to future contributors working directly from the repo in a terminal
+
+### Be Careful With User-Facing Changes
+
+This project is heavily UI-driven. If you change interaction flows, session behavior, workspace browsing, onboarding, or mobile layouts:
+
+- test the happy path
+- test reload behavior where relevant
+- test narrow/mobile layouts where relevant
+- include before/after images in the PR
+
+### Security and Safety Matter
+
+This app can expose workspace contents, run agent actions, and optionally sit behind a reverse proxy or Docker deployment. Treat auth, path handling, uploads, streaming, and environment handling as high-risk areas.
+
+If your PR touches security-sensitive behavior, say so explicitly in the PR description and explain how you verified it.
+
+## Writing a Good PR Message
+
+Start with a short Thinking Path that explains the chain from project goal to the specific fix.
+
+Example:
+
+> - Hermes WebUI aims for near 1:1 parity with the Hermes CLI in a browser
+> - Long-running chat turns rely on SSE streaming and session recovery
+> - Reloading during an in-flight turn can leave the UI in an inconsistent state
+> - The bug was that recovered sessions restored messages but not the live stream state
+> - This PR fixes the recovery path so in-flight turns reconnect cleanly after reload
+> - The benefit is that users can refresh or reconnect without losing visibility into active work
+
+Another example:
+
+> - Hermes WebUI is intentionally a simple Python + vanilla JS application
+> - The right panel is used for workspace browsing and previews
+> - On mobile, panel state changes need to be obvious and touch-friendly
+> - The existing close affordance was inconsistent with the bottom-nav flow
+> - This PR fixes the mobile panel close behavior and aligns it with the current navigation model
+> - The result is fewer dead-end UI states on phones
+
+After that, cover:
+
+- what you changed
+- why you changed it
+- how you verified it
+- what risks remain
+
+## Review Tips
+
+Want the smoothest review?
+
+- Keep diffs tight
+- Name things clearly
+- Avoid unnecessary rewrites
+- Add short comments only where the code would otherwise be hard to follow
+- Respond directly to review feedback and update the PR description if the scope changes
+
+## Development References
+
+- [README.md](README.md)
+- [ARCHITECTURE.md](ARCHITECTURE.md)
+- [TESTING.md](TESTING.md)
+- [ROADMAP.md](ROADMAP.md)
+- [SPRINTS.md](SPRINTS.md)
+
+Questions are best raised early, before a large change is finished.

package/vendor/agent-frontend-shell/CONTRIBUTORS.md

@@ -0,0 +1,107 @@
+# Contributors
+
+Hermes WebUI is a community project. **194 people** have shipped code that landed in a release tag — including the long tail of folks whose work was salvaged into batch releases or absorbed via Co-authored-by trailers. This file is the canonical credit roll.
+
+A contributor's PR count is the number of distinct PRs they get credit for: PRs they authored that merged directly, PRs they authored that were closed-but-absorbed into a release commit (batch merges, salvage rewrites, cherry-picked-and-attributed work), and PRs where they were explicitly attributed in `CHANGELOG.md`. All count the same.
+
+**Total contributors tracked:** 194
+**Total PR credits:** 843
+**Last refreshed:** v0.51.192, 2026-05-31
+
+Generated by `scripts/regen_contributors.py` in the maintainer workspace, which unions three sources: the GitHub merged-PR list, `CHANGELOG.md` attribution lines, and `Co-authored-by:` trailers on commits that landed on master (the canonical signal for a CLOSED PR whose commits were cherry-picked in and attributed). If your name is missing or wrong, open a PR against `CONTRIBUTORS.md` — we cross-check against the changelog on each release.
+
+---
+
+## Top contributors (5+ PRs landed)
+
+| # | Contributor | PRs | First release | Latest release |
+|---|---|---:|---|---|
+| 1 | [@franksong2702](https://github.com/franksong2702) | 148 | `v0.49.3` | `v0.51.153` |
+| 2 | [@Michaelyklam](https://github.com/Michaelyklam) | 117 | `v0.50.240` | `v0.51.139` |
+| 3 | [@bergeouss](https://github.com/bergeouss) | 70 | `v0.48.0` | `v0.51.46` |
+| 4 | [@ai-ag2026](https://github.com/ai-ag2026) | 67 | `v0.50.279` | `v0.51.190` |
+| 5 | [@dso2ng](https://github.com/dso2ng) | 25 | `v0.50.227` | `v0.51.153` |
+| 6 | [@AJV20](https://github.com/AJV20) | 24 | `v0.51.93` | `v0.51.188` |
+| 7 | [@starship-s](https://github.com/starship-s) | 19 | `v0.50.123` | `v0.51.153` |
+| 8 | [@jasonjcwu](https://github.com/jasonjcwu) | 16 | `v0.50.227` | `v0.51.132` |
+| 9 | [@dobby-d-elf](https://github.com/dobby-d-elf) | 15 | `v0.51.38` | `v0.51.161` |
+| 10 | [@Jordan-SkyLF](https://github.com/Jordan-SkyLF) | 12 | `v0.50.18` | `v0.51.66` |
+| 11 | [@aronprins](https://github.com/aronprins) | 10 | `v0.44.0` | `v0.51.45` |
+| 12 | [@JKJameson](https://github.com/JKJameson) | 10 | `v0.50.198` | `v0.51.31` |
+| 13 | [@ccqqlo](https://github.com/ccqqlo) | 9 | `v0.44.0` | `v0.50.270` |
+| 14 | [@24601](https://github.com/24601) | 8 | `v0.50.189` | `v0.51.5` |
+| 15 | [@LumenYoung](https://github.com/LumenYoung) | 8 | `v0.51.47` | `v0.51.99` |
+| 16 | [@Sanjays2402](https://github.com/Sanjays2402) | 8 | `v0.50.292` | `v0.51.158` |
+| 17 | [@armorbreak001](https://github.com/armorbreak001) | 7 | `v0.50.47` | `v0.50.50` |
+| 18 | [@NocGeek](https://github.com/NocGeek) | 7 | `v0.50.251` | `v0.50.252` |
+| 19 | [@Hinotoi-agent](https://github.com/Hinotoi-agent) | 6 | `v0.50.10` | `v0.51.44` |
+| 20 | [@iRonin](https://github.com/iRonin) | 6 | `v0.41.0` | `v0.41.0` |
+| 21 | [@bsgdigital](https://github.com/bsgdigital) | 5 | `v0.50.159` | `v0.51.31` |
+| 22 | [@cloudyun888](https://github.com/cloudyun888) | 5 | `v0.50.47` | `v0.50.140` |
+| 23 | [@fxd-jason](https://github.com/fxd-jason) | 5 | `v0.50.245` | `v0.50.250` |
+| 24 | [@george-andraws](https://github.com/george-andraws) | 5 | `v0.51.139` | `v0.51.153` |
+| 25 | [@happy5318](https://github.com/happy5318) | 5 | `v0.50.238` | `v0.51.31` |
+
+## Sustained contributors (3–4 PRs landed)
+
+| Contributor | PRs | First release | Latest release |
+|---|---:|---|---|
+| [@AlexeyDsov](https://github.com/AlexeyDsov) | 4 | `v0.50.267` | `v0.51.139` |
+| [@fecolinhares](https://github.com/fecolinhares) | 4 | `v0.50.238` | `v0.50.250` |
+| [@frap129](https://github.com/frap129) | 4 | `v0.50.140` | `v0.50.233` |
+| [@Isla-Liu](https://github.com/Isla-Liu) | 4 | `v0.51.100` | `v0.51.142` |
+| [@KingBoyAndGirl](https://github.com/KingBoyAndGirl) | 4 | `v0.50.238` | `v0.50.240` |
+| [@qxxaa](https://github.com/qxxaa) | 4 | `v0.50.210` | `v0.51.37` |
+| [@renheqiang](https://github.com/renheqiang) | 4 | `v0.50.61` | `v0.50.95` |
+| [@Thanatos-Z](https://github.com/Thanatos-Z) | 4 | `v0.50.257` | `v0.50.278` |
+| [@deboste](https://github.com/deboste) | 3 | `v0.17.1` | `v0.50.297` |
+| [@dutchaiagency](https://github.com/dutchaiagency) | 3 | `v0.50.281` | `v0.50.286` |
+| [@espokaos-ops](https://github.com/espokaos-ops) | 3 | `v0.51.92` | `v0.51.94` |
+| [@lucasrc](https://github.com/lucasrc) | 3 | `v0.51.57` | `v0.51.57` |
+| [@mccxj](https://github.com/mccxj) | 3 | `v0.51.75` | `v0.51.148` |
+| [@mysoul12138](https://github.com/mysoul12138) | 3 | `v0.51.161` | `v0.51.185` |
+| [@pamnard](https://github.com/pamnard) | 3 | `v0.51.186` | `v0.51.191` |
+| [@pavolbiely](https://github.com/pavolbiely) | 3 | `v0.50.159` | `v0.50.233` |
+
+## Two-PR contributors (17)
+
+[@aliceisjustplaying](https://github.com/aliceisjustplaying), [@allenliang2022](https://github.com/allenliang2022), [@andrewkangkr](https://github.com/andrewkangkr), [@Carry00](https://github.com/Carry00), [@eleboucher](https://github.com/eleboucher), [@insecurejezza](https://github.com/insecurejezza), [@junjunjunbong](https://github.com/junjunjunbong), [@linuxid10t](https://github.com/linuxid10t), [@michael-dg](https://github.com/michael-dg), [@mmartial](https://github.com/mmartial), [@MrFant](https://github.com/MrFant), [@plerohellec](https://github.com/plerohellec), [@renatomott](https://github.com/renatomott), [@swftwolfzyq](https://github.com/swftwolfzyq), [@vcavichini](https://github.com/vcavichini), [@xz-dev](https://github.com/xz-dev), [@zichen0116](https://github.com/zichen0116).
+
+## Single-PR contributors (136)
+
+Each of these folks landed exactly one PR that shipped — a bug fix, a locale, a security hardening, a doc improvement, an infrastructure tweak. Every one moved the project forward.
+
+[@29n](https://github.com/29n), [@86cloudyun-afk](https://github.com/86cloudyun-afk), [@AdoneyGalvan](https://github.com/AdoneyGalvan), [@amlyczz](https://github.com/amlyczz), [@andrewy-wizard](https://github.com/andrewy-wizard), [@Argonaut790](https://github.com/Argonaut790), [@arshkumarsingh](https://github.com/arshkumarsingh), [@ashbuildslife](https://github.com/ashbuildslife), [@Asunfly](https://github.com/Asunfly), [@ayushere](https://github.com/ayushere), [@bengdan](https://github.com/bengdan), [@betamod](https://github.com/betamod), [@bjb2](https://github.com/bjb2), [@Bobby9228](https://github.com/Bobby9228), [@bschmidy10](https://github.com/bschmidy10), [@carlytwozero](https://github.com/carlytwozero), [@Charanis](https://github.com/Charanis), [@ChaseFlorell](https://github.com/ChaseFlorell), [@chwps](https://github.com/chwps), [@colin-chang](https://github.com/colin-chang), [@cyberdyne187](https://github.com/cyberdyne187), [@darkopetrovic](https://github.com/darkopetrovic), [@davidsben](https://github.com/davidsben), [@DavidSchuchert](https://github.com/DavidSchuchert), [@DelightRun](https://github.com/DelightRun), [@dev-rehaann](https://github.com/dev-rehaann), [@dotBeeps](https://github.com/dotBeeps), [@DrMaks22](https://github.com/DrMaks22), [@eba8](https://github.com/eba8), [@emanon312](https://github.com/emanon312), [@eov128](https://github.com/eov128), [@Fail-Safe](https://github.com/Fail-Safe), [@FrancescoFarinola](https://github.com/FrancescoFarinola), [@gabogabucho](https://github.com/gabogabucho), [@galvani](https://github.com/galvani), [@gavinssr](https://github.com/gavinssr), [@GeoffBao](https://github.com/GeoffBao), [@georgebdavis](https://github.com/georgebdavis), [@GiggleSamurai](https://github.com/GiggleSamurai), [@hacker1e7](https://github.com/hacker1e7), [@hacker2005](https://github.com/hacker2005), [@halmisen](https://github.com/halmisen), [@hermes-gimmethebeans](https://github.com/hermes-gimmethebeans), [@hi-friday](https://github.com/hi-friday), [@hualong1009](https://github.com/hualong1009), [@huangzt](https://github.com/huangzt), [@indigokarasu](https://github.com/indigokarasu), [@intellectronica](https://github.com/intellectronica), [@jeffscottward](https://github.com/jeffscottward), [@Jellypowered](https://github.com/Jellypowered), [@jimdawdy-hub](https://github.com/jimdawdy-hub), [@JinYue-GitHub](https://github.com/JinYue-GitHub), [@joaompfp](https://github.com/joaompfp), [@jundev0001](https://github.com/jundev0001), [@KayZz69](https://github.com/KayZz69), [@kcclaw001](https://github.com/kcclaw001), [@kevin-ho](https://github.com/kevin-ho), [@koshikai](https://github.com/koshikai), [@kowenhaoai](https://github.com/kowenhaoai), [@lawrencel1ng](https://github.com/lawrencel1ng), [@leap233](https://github.com/leap233), [@legeantbleu](https://github.com/legeantbleu), [@likawa3b](https://github.com/likawa3b), [@lost9999](https://github.com/lost9999), [@lucky-yonug](https://github.com/lucky-yonug), [@lx3133584](https://github.com/lx3133584), [@MacLeodMike](https://github.com/MacLeodMike), [@malulian](https://github.com/malulian), [@mangodxd](https://github.com/mangodxd), [@mariosam95](https://github.com/mariosam95), [@MatzAgent](https://github.com/MatzAgent), [@mbac](https://github.com/mbac), [@migueltavares](https://github.com/migueltavares), [@MinhoJJang](https://github.com/MinhoJJang), [@mittyok](https://github.com/mittyok), [@mslovy](https://github.com/mslovy), [@mvanhorn](https://github.com/mvanhorn), [@nanookclaw](https://github.com/nanookclaw), [@ng-technology-llc](https://github.com/ng-technology-llc), [@nickgiulioni1](https://github.com/nickgiulioni1), [@octo-patch](https://github.com/octo-patch), [@OneFat3](https://github.com/OneFat3), [@PINKIIILQWQ](https://github.com/PINKIIILQWQ), [@rhelmer](https://github.com/rhelmer), [@rickchew](https://github.com/rickchew), [@RobertoVillegas](https://github.com/RobertoVillegas), [@ruxme](https://github.com/ruxme), [@ryan-remeo](https://github.com/ryan-remeo), [@ryansombraio](https://github.com/ryansombraio), [@s905060](https://github.com/s905060), [@Saik0s](https://github.com/Saik0s), [@samuelgudi](https://github.com/samuelgudi), [@SaulgoodMan-C](https://github.com/SaulgoodMan-C), [@sbe27](https://github.com/sbe27), [@shaoxianbilly](https://github.com/shaoxianbilly), [@sheng-di](https://github.com/sheng-di), [@shruggr](https://github.com/shruggr), [@sixianli](https://github.com/sixianli), [@skspade](https://github.com/skspade), [@smurmann](https://github.com/smurmann), [@snuffxxx](https://github.com/snuffxxx), [@someaka](https://github.com/someaka), [@spektro33](https://github.com/spektro33), [@Stampede](https://github.com/Stampede), [@stocky789](https://github.com/stocky789), [@suinia](https://github.com/suinia), [@sunilkumarvalmiki](https://github.com/sunilkumarvalmiki), [@sunnysktsang](https://github.com/sunnysktsang), [@TaraTheStar](https://github.com/TaraTheStar), [@tgaalman](https://github.com/tgaalman), [@thadreber-web](https://github.com/thadreber-web), [@the-own-lab](https://github.com/the-own-lab), [@theh4v0c](https://github.com/theh4v0c), [@theseussss](https://github.com/theseussss), [@tiansiyuan](https://github.com/tiansiyuan), [@tomaioo](https://github.com/tomaioo), [@trucuit](https://github.com/trucuit), [@ts2111](https://github.com/ts2111), [@v2psv](https://github.com/v2psv), [@vansour](https://github.com/vansour), [@vCillusion](https://github.com/vCillusion), [@vikarag](https://github.com/vikarag), [@waldmanz](https://github.com/waldmanz), [@wali-reheman](https://github.com/wali-reheman), [@watzon](https://github.com/watzon), [@weidzhou](https://github.com/weidzhou), [@weiwei83](https://github.com/weiwei83), [@wind-chant](https://github.com/wind-chant), [@wirtsi](https://github.com/wirtsi), [@woaijiadanoo](https://github.com/woaijiadanoo), [@xingyue52077](https://github.com/xingyue52077), [@xolom](https://github.com/xolom), [@yunyunyunyun-yun](https://github.com/yunyunyunyun-yun), [@yzp12138](https://github.com/yzp12138), [@zapabob](https://github.com/zapabob), [@zenc-cp](https://github.com/zenc-cp).
+
+---
+
+## How credit is tracked
+
+Most PRs in this repo land via one of four paths:
+
+1. **Direct merge** — your PR is reviewed and merged on its own. Author shows up directly in `git log` and on the PR's `merged_at` timestamp.
+2. **Squash into a batch release** — your PR is merged together with several other contributor PRs into a single release commit (e.g. `release: v0.51.55 — 9-PR contributor batch`). The original PR closes (not merges) on GitHub but the squashed release commit carries a `Co-authored-by: <you>` trailer plus an entry in `CHANGELOG.md` crediting you by username and PR number.
+3. **Salvaged from a larger PR** — when a PR mixes one good change with several unrelated or risky ones, we split it: the good parts ship in a clean follow-up PR, you get credit in the CHANGELOG entry, and the original PR is closed with a salvage map showing what went where.
+4. **Auto-rebase + auto-fix** — for merge-ready contributor PRs with mechanical blockers (CHANGELOG conflicts, lint, drifted tests), a maintainer rebases the contributor's branch, fixes the blockers, and force-pushes back. The `Co-authored-by` trailer preserves your authorship.
+
+All four paths count as a contribution. GitHub's `merged_at` field only catches path 1; paths 2-4 show as "closed" on the contributor's PR even though the work is live in master. That's why this file consults the CHANGELOG attribution lines, not just GitHub's merged-PR list.
+
+## Special thanks
+
+- **[@aronprins](https://github.com/aronprins)** — `v0.50.0` UI overhaul (PR #242). The CSS-only redesign that defined the design tokens, theme architecture, and three-panel layout that the rest of the app builds on. PR #242 didn't merge as-is, but it is the design language of the app.
+- **[@franksong2702](https://github.com/franksong2702)** — most prolific external contributor across the project's history. 148 PRs spanning the session sidebar, mobile/responsive layout, workspace state machine, profile context, slash autocomplete, breadcrumb navigation, streaming-session exemption, cron output preservation, embedded terminal, the manual-compress async start/status endpoint pair, the worktree status surface (PR #2109) + guarded remove (PR #2156) for the lifecycle umbrella #2057, session post-render dedup (PR #2166), the `/api/session` native-WebUI fast path (PR #2170), tail-window response trim (PR #2171), the second-wave stale-stream guard extension (PR #2158), CSP report collector (PR #2160), and the long tail of polish.
+- **[@Michaelyklam](https://github.com/Michaelyklam)** — most prolific contributor of late-2025/early-2026. 117 PRs covering Docker hardening, profile-scoped skills, KaTeX delimiter parsing, Codex quota surfacing, Goal command, Kanban polish, auto-compression toast lifetime, the localization parity backfills, the v0.51.51 mobile Insights bucketing/layout pair (PRs #2120/#2121), the Hermes run adapter RFC (PR #2105 for #1925), the fork-from-here absolute-index fix (PR #2198 for #2184), and the opencode-go custom-provider overlap routing fix (PR #2204 for #1894).
+- **[@bergeouss](https://github.com/bergeouss)** — provider-management UI, OAuth status, two-container Docker docs, profile isolation hardening, Reveal-in-Finder, the OpenRouter free-tier live fetch, and most of Settings → Providers. 70 PRs.
+- **[@ai-ag2026](https://github.com/ai-ag2026)** — autonomous-AI contributor (Hermes Agent-driven). 67 PRs focused on session recovery (state.db sidecar reconciliation, orphan `.bak` recovery, audit + safe-repair endpoints), workspace/run lifecycle health, the crash-safe turn-journal RFC, the append-only turn-journal helper (PR #2059), the matching lifecycle-events layer (PR #2062), the `Content-Security-Policy-Report-Only` header (PR #2084), and the per-cron toast notification toggle (PR #2100).
+- **[@Jordan-SkyLF](https://github.com/Jordan-SkyLF)** — Live streaming, session recovery, workspace fallback, and a recent burst of presentation polish: the manual "Refresh usage" button on the Provider quota card (PR #2150), cancelled-turn status classification (PR #2151), Firefox sidebar scroll stabilization (PR #2200), early provisional session titles (PR #2202), target-aware "What's new?" links (PR #2207), and MCP tools overflow fix in Settings (PR #2210). 12 PRs total.
+- **[@LumenYoung](https://github.com/LumenYoung)** — contributor focused on the streaming hot path's correctness. 8 PRs including the original stale-stream writeback guard (PR #2136 — the bug class the next two releases extended), gateway-state alive-null classification (PR #2075), compression-banner anchor alignment (PR #2182), and context-progress ring auto-refresh on compression complete (PR #2188).
+- **[@iRonin](https://github.com/iRonin)** — security hardening sprint (PRs #196–#204): session memory leak fix, CSP + Permissions-Policy headers, slow-client connection timeout, optional HTTPS/TLS, upstream branch tracking, CLI session file-browser support. Six consecutive, focused, high-quality security PRs.
+- **[@indigokarasu](https://github.com/indigokarasu)** — visual redesign proposal (PR #213). Icon rail sidebar, design token system, 7 themes. Didn't merge as-is but shaped the design language that landed in v0.50.0.
+- **[@zenc-cp](https://github.com/zenc-cp)** — anti-hallucination guard for the ReAct loop (PR #133). Three-layer approach (ephemeral prompt, live token filtering, session-history cleanup) that the streaming pipeline still uses.
+- **[@deboste](https://github.com/deboste)** — reverse-proxy auth, mobile responsive layout, model routing (PRs #3, #4, #5). Three of the very first community PRs. Early foundation work.
+- **[@Hinotoi-agent](https://github.com/Hinotoi-agent)** — security fixes spanning profile `.env` isolation (PR #351), session-import workspace validation (PR #2048), and bandit B105 hardening. Subtle, high-leverage credential and path-traversal fixes.
+- **[@lucasrc](https://github.com/lucasrc)** — auth-hardening trilogy in v0.51.57 (PRs #2191/#2192/#2193): thread-safe login rate limiter with PBKDF2 key separation, password-hash cache invalidation on settings change, and the full 64-char HMAC-SHA256 session signature with backwards-compatible migration bridge. Three coordinated security PRs that landed together.
+- **[@jasonjcwu](https://github.com/jasonjcwu)** — composer and transcript polish, 16 PRs. Recent: silent compress-status during session switch (PR #2185), concurrent-send loss fix (PR #2186), in-transcript steer message badge (PR #2187), plus sidebar collapse via active-rail click (PR #2054).
+- **[@dobby-d-elf](https://github.com/dobby-d-elf)** — frontend reliability and motion polish: workspace fallback on deleted directories (PR #2138), iPhone PWA bottom-scroll fix (PR #2143), the new "Activity: X tools" composer footer animation (PR #2203) and its follow-up tuning (PR #2212).
+
+If you've contributed and aren't here, **open a PR**. We cross-check the CHANGELOG on every release, but if a credit fell through (a Co-authored-by trailer that didn't make it into the changelog entry, an attribution in a PR comment that should be in the release notes), this list is the right place to fix it.

package/vendor/agent-frontend-shell/DESIGN.md

@@ -0,0 +1,173 @@
+---
+version: alpha
+name: Hermes Calm Console
+description: "A restrained agent control surface: conversational content first, tool traces as quiet metadata, minimal chrome."
+colors:
+  primary: "#EAE0D5"
+  secondary: "#C6AC8F"
+  tertiary: "#C6AC8F"
+  neutral: "#0A0908"
+  surface: "#22333B"
+  surfaceSubtle: "#11100E"
+  borderSubtle: "#3B4A50"
+  ink: "#0A0908"
+  success: "#86C08B"
+  warning: "#E0B15D"
+  error: "#F87171"
+typography:
+  body-md:
+    fontFamily: "Georgia, Times New Roman, serif"
+    fontSize: 15px
+    fontWeight: 400
+    lineHeight: 1.68
+  body-sm:
+    fontFamily: "-apple-system, BlinkMacSystemFont, Segoe UI, Inter, system-ui, sans-serif"
+    fontSize: 12px
+    fontWeight: 400
+    lineHeight: 1.45
+  user-message:
+    fontFamily: "-apple-system, BlinkMacSystemFont, Segoe UI, Inter, system-ui, sans-serif"
+    fontSize: 14px
+    fontWeight: 400
+    lineHeight: 1.55
+  mono-xs:
+    fontFamily: "SF Mono, ui-monospace, monospace"
+    fontSize: 11px
+    fontWeight: 500
+    lineHeight: 1.55
+rounded:
+  sm: 4px
+  md: 8px
+  lg: 12px
+  pill: 999px
+spacing:
+  xs: 4px
+  sm: 8px
+  md: 12px
+  lg: 16px
+components:
+  app-shell:
+    backgroundColor: "{colors.neutral}"
+    textColor: "{colors.primary}"
+    rounded: "{rounded.sm}"
+    padding: 16px
+  panel:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.primary}"
+    rounded: "{rounded.lg}"
+    padding: 16px
+  border-line:
+    backgroundColor: "{colors.borderSubtle}"
+    textColor: "{colors.primary}"
+    rounded: "{rounded.sm}"
+    padding: 4px
+  state-success:
+    backgroundColor: "{colors.success}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.sm}"
+    padding: 4px
+  state-warning:
+    backgroundColor: "{colors.warning}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.sm}"
+    padding: 4px
+  state-error:
+    backgroundColor: "{colors.error}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.sm}"
+    padding: 4px
+  tool-call-group:
+    backgroundColor: "{colors.neutral}"
+    textColor: "{colors.secondary}"
+    rounded: "{rounded.md}"
+    padding: 4px
+  tool-card:
+    backgroundColor: "{colors.surfaceSubtle}"
+    textColor: "{colors.secondary}"
+    rounded: "{rounded.md}"
+    padding: 8px
+  user-message:
+    backgroundColor: "{colors.tertiary}"
+    textColor: "{colors.ink}"
+    rounded: "{rounded.lg}"
+    padding: 12px
+---
+
+## Overview
+
+Hermes WebUI should feel like a calm developer console, not a demo page assembled from colorful cards. The primary artifact is the conversation. Tool calls, thinking traces, context compaction records, token usage, and runtime status are useful, but they are transcript metadata and should sit below the visual priority of user and assistant prose.
+
+The desired direction is Linear/Vercel precision with a little Claude-style conversational warmth: quiet surfaces, clear spacing, restrained accent use, and progressive disclosure for debugging detail.
+
+## Colors
+
+- **Primary (#EAE0D5):** main text on dark surfaces. The warm parchment should feel readable and grounded, not like bright white terminal text.
+- **Secondary/Tertiary (#C6AC8F):** metadata and restrained accent. Use sparingly for active state, focus, user bubbles, and quiet emphasis.
+- **Neutral (#0A0908):** app background and ink. This gives the WebUI depth without returning to the previous navy/gold theme.
+- **Surface (#22333B):** panels, sidebar, and stronger interactive surfaces. It should carry the structure while the conversation remains primary.
+- **Light surfaces (#EAE0D5 / #F4EEE7):** light mode uses the palette's parchment as the field and a slightly lifted derived surface for panels.
+- **Semantic colors:** success/warning/error/info are state colors only, not decorative palette choices.
+
+## Typography
+
+Use Claude-like split typography: assistant prose gets an editorial serif stack (Georgia as the available substitute for Anthropic Serif), while user bubbles and functional UI stay in a crisp sans stack. This keeps the bot voice calmer and more readable without making controls feel bookish. Use monospace only for code, file paths, commands, tool names, and compact metadata. Avoid making whole cards feel like terminal output unless they actually are logs.
+
+Scale should stay tight: 11px metadata, 12px labels, 14px body, 16–18px headings. Do not proliferate 10px/10.5px/12.5px one-offs unless there is a real layout constraint.
+
+## Layout
+
+Conversation rhythm:
+
+1. User message — right aligned, compact bubble.
+2. Assistant content — left aligned, prose-first, no heavy bubble.
+3. Tool/thinking/context traces — quiet disclosure rows inside the assistant turn.
+4. Raw logs/details — hidden until explicitly expanded.
+
+Metadata should not break the reading flow. A turn that used ten tools should read as one assistant turn with one compact `Used 10 tools` disclosure, not ten content cards.
+
+## Elevation & Depth
+
+Use almost no shadows in the transcript. Shadows are reserved for popovers, dropdowns, modal dialogs, and floating controls. Cards inside chat should use either a subtle border or a subtle tint, not both aggressively.
+
+## Shapes
+
+- Rows/list items: `4–8px` radius.
+- Cards/panels: `8–12px` radius.
+- Pills: only true chips/badges use `999px`.
+- Avoid stacks of nested rounded rectangles. If a card contains another card, one of them is probably unnecessary.
+
+## Components
+
+### Tool/thinking activity group
+
+Collapsed by default in settled history and during live runs unless the user has explicitly opened that Activity row before. Persist open/closed disclosure state per chat and per turn, so switching away from a chat and coming back preserves the mode the user left it in. Summary line uses one disclosure for internals and stays intentionally terse, e.g. `Activity: 4 tools`. It should not repeat the always-present thinking area, list individual tool names, or add a second trailing count badge. Expanding reveals thinking and individual tool cards together. Thinking and tools should not create separate transcript rows unless there is an error or approval state that needs attention.
+
+### Tool card
+
+A tool card is a debug event row, not a chat message. Show icon, name, short target/preview, and status. Arguments and result snippets stay behind expansion. Result snippets should be truncated; full logs belong behind “show more”.
+
+### Thinking/context cards
+
+Same visual family as tool-call metadata. They should be quieter than assistant prose and should not use bright tinted full cards unless the user expands them.
+
+### Composer
+
+The composer is the command surface. Keep it legible and focused: modest radius, subtle border, transparent inactive chips, no theatrical hover scaling.
+
+## Do's and Don'ts
+
+Do:
+
+- Collapse noisy agent internals by default.
+- Use one accent color at a time.
+- Prefer neutral borders and restrained surfaces.
+- Make debug traces accessible and inspectable without making them visually dominant.
+- Add stable class/data hooks for future visual regression tests.
+
+Don't:
+
+- Render every tool call as a first-class chat card.
+- Mix gold, cyan, purple, orange, red, and green as decorative colors in the same viewport.
+- Add new hardcoded radius/color values when a token exists.
+- Use shadows, gradients, and hover transforms for routine controls.
+- Hide important error or approval states; those are allowed to be prominent because they require action.

package/vendor/agent-frontend-shell/Dockerfile

@@ -0,0 +1,91 @@
+FROM python:3.12-slim
+
+LABEL maintainer="nesquena"
+LABEL description="Hermes Web UI — browser interface for Hermes Agent"
+
+# Install system packages
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Make use of apt-cacher-ng if available
+RUN if [ "A${BUILD_APT_PROXY:-}" != "A" ]; then \
+        echo "Using APT proxy: ${BUILD_APT_PROXY}"; \
+        printf 'Acquire::http::Proxy "%s";\n' "$BUILD_APT_PROXY" > /etc/apt/apt.conf.d/01proxy; \
+    fi \
+    && apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates wget gnupg \
+    && rm -rf /var/lib/apt/lists/* \
+    && apt-get clean
+
+RUN apt-get update -y --fix-missing --no-install-recommends \
+    && apt-get install -y --no-install-recommends \
+    apt-utils \
+    locales \
+    ca-certificates \
+    curl \
+    rsync \
+    openssh-client \
+    git \
+    xz-utils \
+    && apt-get upgrade -y \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# UTF-8
+RUN localedef -i en_US -c -f UTF-8 -A /usr/share/locale/locale.alias en_US.UTF-8
+ENV LANG=en_US.utf8
+ENV LC_ALL=C
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PYTHONIOENCODING=utf-8
+
+WORKDIR /apptoo
+
+# Create the unprivileged runtime user. The entrypoint starts as root only for
+# UID/GID alignment and filesystem preparation, then execs the server as this user.
+RUN groupadd -g 1024 hermeswebui \
+    && useradd -u 1024 -d /home/hermeswebui -g hermeswebui -G users -s /bin/bash -m hermeswebui \
+    && mkdir -p /app /uv_cache /workspace \
+    && chown -R hermeswebui:hermeswebui /home/hermeswebui /app /uv_cache /workspace \
+    && chmod 0755 /home/hermeswebui \
+    && chmod 1777 /app /uv_cache /workspace
+
+COPY --chmod=555 docker_init.bash /hermeswebui_init.bash
+
+RUN touch /.within_container
+
+# Remove APT proxy configuration and clean up APT downloaded files
+RUN rm -rf /var/lib/apt/lists/* /etc/apt/apt.conf.d/01proxy \
+    && apt-get clean
+
+USER root
+
+# Pre-install uv system-wide so the container doesn't need internet access at runtime.
+# Installing as root places uv in /usr/local/bin, available to all users.
+# The init script will skip the download when uv is already on PATH.
+RUN curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin sh
+
+COPY --chown=root:root . /apptoo
+
+# Bake the git version tag into the image so the settings badge works even
+# when .git is not present (it is excluded by .dockerignore).
+# CI passes: --build-arg HERMES_VERSION=$(git describe --tags --always)
+# Local builds that omit the arg get "unknown" as the fallback.
+ARG HERMES_VERSION=unknown
+RUN echo "__version__ = '${HERMES_VERSION}'" > /apptoo/api/_version.py
+
+# Default to binding all interfaces (required for container networking)
+ENV HERMES_WEBUI_HOST=0.0.0.0
+ENV HERMES_WEBUI_PORT=8787
+
+EXPOSE 8787
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD curl -f http://localhost:8787/health || exit 1
+
+# docker_init.bash performs root-only bind-mount setup, then drops to hermeswebui
+# before starting the WebUI server. The production image does not ship sudo.
+USER root
+CMD ["/hermeswebui_init.bash"]
+

package/vendor/agent-frontend-shell/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hermes Web UI 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.