nanw
4b202d1267
The agent source at /opt/hermes inside the container may contain a
.playwright/ directory with browser dependency files that have restricted
permissions. rsync fails with exit code 23 when attempting to read them,
which kills the container build ("Failed to stage hermes-agent source").
- Add --exclude=.playwright to rsync in docker_init.bash
- Add rm -rf .playwright to cp -a fallback path for symmetry
- Update test_docker_init_excludes_egg_info_during_staging to assert
both the rsync --exclude and a broad .playwright presence check
- Add a brief note in AGENTS.md Contribution style about mirroring
directory exclusions in both rsync and cp paths
Fixes #5315
93 lines
4.1 KiB
Markdown
93 lines
4.1 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.
|
|
- Do not edit `CHANGELOG.md` in ordinary contributor PRs. The release workflow
|
|
owns changelog updates through release commits. If a change is release-note
|
|
worthy, include concise release-note wording in the PR body instead.
|
|
- 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.
|
|
- For Docker build changes in `docker_init.bash`, mirror directory exclusions
|
|
in both the `rsync` and `cp -a` paths — `/opt/hermes` may contain subdirectories
|
|
with restricted permissions (e.g. `.playwright/`).
|
|
|
|
## 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.
|