mirror of
https://github.com/nesquena/hermes-webui.git
synced 2026-07-15 12:10:19 +00:00
nesquena-hermes
e775fb3355
* stage-3908: supported local pytest runner + symlink-guard on venv create/clear (Codex CORE fix) Rebased rodboev/franksong2702 #3908 onto v0.51.434. Adds scripts/test.sh dev runner + requirements-dev.txt + test_ci_hygiene.py + conftest version guard. Defensive fix on the authoritative gate: create_or_rebuild_venv refuses a symlinked .venv so 'python -m venv --clear' can't wipe the symlink target (same symlink-hardening class as #4217/#4234/#4240). Locked by a hygiene test. * Release OV: supported local pytest runner (#3908) scripts/test.sh + requirements-dev.txt + conftest version guard + hygiene tests. Self-rebased franksong2702's #3908 onto v0.51.434; full Codex+Opus+suite gate. Codex CORE fix applied: refuse to create/--clear a virtualenv through a symlinked .venv (symlink-hardening class, #4217/#4234/#4240), locked by a hygiene assertion. Co-authored-by: franksong2702 <franksong2702@users.noreply.github.com> --------- Co-authored-by: nesquena-hermes <agent@nesquena-hermes> Co-authored-by: franksong2702 <franksong2702@users.noreply.github.com>
89 lines
3.7 KiB
Markdown
89 lines
3.7 KiB
Markdown
# Agent instructions for Hermes WebUI
|
|
|
|
This file is the shared entry point for AI assistants working in this
|
|
repository. Keep it project-specific and safe to publish. Do not put personal
|
|
machine setup, private network details, credentials, tokens, or local-only
|
|
workflow notes here.
|
|
|
|
## Read first
|
|
|
|
Before making changes, read:
|
|
|
|
1. `README.md`
|
|
2. `CONTRIBUTING.md`
|
|
3. `docs/CONTRACTS.md`
|
|
4. `CHANGELOG.md`
|
|
|
|
For architecture, testing, or setup work, also read the matching reference:
|
|
|
|
- `ARCHITECTURE.md` for design constraints and current module layout
|
|
- `TESTING.md` for local verification commands and manual test guidance
|
|
- `docs/onboarding.md` for first-run onboarding behavior
|
|
- `docs/troubleshooting.md` for diagnostic flows
|
|
- `docs/rfcs/README.md` for larger RFCs and state/durability contracts
|
|
|
|
For UI or UX work, read `docs/UIUX-GUIDE.md` and `DESIGN.md` before
|
|
changing layout, interaction flow, themes, chat rendering, or composer chrome.
|
|
|
|
## Onboarding and reinstall support
|
|
|
|
If the task involves install, reinstall, bootstrap, first-run onboarding,
|
|
provider setup, local model server setup, Docker onboarding, WSL onboarding, or
|
|
support for a failed first run, read `docs/onboarding-agent-checklist.md`
|
|
before running commands or inspecting logs.
|
|
|
|
Follow that checklist's safety rules:
|
|
|
|
- use isolated `HERMES_HOME` and `HERMES_WEBUI_STATE_DIR` for trials unless the
|
|
human explicitly asks to use real state
|
|
- do not delete or overwrite a real `~/.hermes` directory without explicit
|
|
approval
|
|
- do not print API keys, OAuth tokens, cookies, full `.env` files, full
|
|
`auth.json` files, or password hashes
|
|
- collect non-secret status and log evidence before recommending a fix
|
|
|
|
## Contribution style
|
|
|
|
- Keep one logical change per PR; split unrelated refactors or cleanup.
|
|
- Read `docs/CONTRACTS.md` and the linked contract/RFC for the touched
|
|
subsystem before editing.
|
|
- For local pytest runs, use `./scripts/test.sh` instead of bare `python3`,
|
|
`python -m pytest`, or `pytest`. The script creates/uses the repo `.venv`,
|
|
pins execution to Python 3.11-3.13, and installs missing dev test dependencies.
|
|
`HERMES_WEBUI_TEST_PYTHON` selects the supported base interpreter used to
|
|
create or rebuild `.venv`; it must not install test dependencies into a
|
|
system/Homebrew interpreter directly.
|
|
If a direct pytest invocation reports an unsupported interpreter, rerun through
|
|
`./scripts/test.sh` before debugging product code.
|
|
- Prefer the existing Python + vanilla JavaScript structure. Do not add
|
|
dependencies, build tools, frameworks, or long-lived processes without clear
|
|
justification and a rollback story.
|
|
- Update docs when changing setup, onboarding, runtime behavior, architecture,
|
|
testing guidance, or user-facing workflows.
|
|
- Update `CHANGELOG.md` for user-visible behavior, setup, workflow, or
|
|
documentation changes that should be release-note ready.
|
|
- For UI or UX changes, include before/after evidence and test relevant
|
|
desktop, narrow, and mobile states.
|
|
- For behavior changes, add or update automated tests where practical and list
|
|
the manual verification performed.
|
|
- For runtime, streaming, recovery, replay, compression, or sidebar metadata
|
|
changes, name the state layer being mutated and prove the relevant invariant.
|
|
|
|
## Local state and secrets
|
|
|
|
Hermes WebUI can read and write real agent state, sessions, workspaces,
|
|
credentials, and cron data. Treat local validation as potentially destructive
|
|
unless you have confirmed the active state directories.
|
|
|
|
Prefer isolated trial state for experiments:
|
|
|
|
```bash
|
|
HERMES_HOME=/tmp/hermes-webui-agent-home \
|
|
HERMES_WEBUI_STATE_DIR=/tmp/hermes-webui-agent-state \
|
|
HERMES_WEBUI_PORT=8789 \
|
|
python3 bootstrap.py
|
|
```
|
|
|
|
Do not include private machine instructions in this tracked file. Use a
|
|
git-ignored local note for personal workflow details.
|