toor
cc644c59f6
Adds the checks that make the constraints from Phase 001-007 mechanical
instead of tribal knowledge, and clears the legacy brand text that was still
reachable at runtime.
New red-line tests:
- no-legacy-brand mirrors the harness scan under vitest, and asserts its
allow-list has not drifted from harness-check.mjs
- hermes-db-readonly classifies every new DatabaseSync call site by
following the path it opens, and fails if a state.db handle drops
readOnly. It also pins the one legitimately writable database.
- i18n-parity compares the raw zh/en locale objects both ways. The
existing coverage test merged en into zh at import time, so a key
missing from zh could never fail there.
harness:check gains the four missing gates from the phase brief - retired
package directories, retired package scripts, a single UI library, and the
required root files. Each was verified to fail by mutating the repo.
The online-update channel had hardcoded upstream URLs. It now reads
HERMES_WEB_UI_VERSION_MANIFEST_URL and friends and degrades with a named
error, because a reimplementation has nowhere to pull releases from.
The remaining legacy strings are deliberate and each carries a reason in the
allow-list: the global-agent relay address and the OpenRouter referer are
load-bearing, the socket role identifier is a wire contract, and the pre-rename
DB filenames would orphan existing deployments if changed. AGENTS.md now says
so explicitly, so a future agent does not "clean them up".
Also removes a dead electron mock alias, an i18n exemption that had stopped
exempting anything, and a teardown race in plugins-view.test.ts where a-spin
animation frames outlived the jsdom environment.
Verified self-contained: with reference_code/ moved aside, harness:check,
build, test and test:e2e all pass, so the directory can now be deleted.
79 lines
3.7 KiB
Markdown
79 lines
3.7 KiB
Markdown
# Agent Map
|
|
|
|
This file is a short map for coding agents. Keep detailed guidance in `docs/`
|
|
and keep this file small enough to fit into every task context.
|
|
|
|
## First Reads
|
|
|
|
- `DEVELOPMENT.md` - project commands, coding rules, test rules, and PR shape.
|
|
- `ARCHITECTURE.md` - package boundaries, data ownership, and runtime flow.
|
|
- `docs/harness/README.md` - how this repository is prepared for agent work.
|
|
- `docs/harness/validation.md` - which checks to run for each change type.
|
|
- `docs/harness/worktree-runbook.md` - isolated local dev and test setup.
|
|
- `docs/harness/pr-review.md` - self-review checklist before pushing.
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
npm ci --ignore-scripts
|
|
npm run harness:check
|
|
npm run test
|
|
npm run test:e2e
|
|
npm run build
|
|
```
|
|
|
|
Use the smallest relevant check while iterating. Before a broad PR, run
|
|
`npm run harness:check`, `npm run test:coverage`, `npm run test:e2e`, and
|
|
`npm run build`.
|
|
|
|
## Code Ownership Map
|
|
|
|
- `packages/client/src` - Vue 3 client, stores, routes, i18n, API helpers.
|
|
- `packages/server/src` - Koa API, Socket.IO, persistence, Hermes integration.
|
|
- `packages/skills` - built-in skills injected into the Hermes skills directory.
|
|
- `tests/client`, `tests/server`, `tests/shared` - Vitest coverage.
|
|
- `tests/e2e` - Playwright browser coverage with mocked backend services.
|
|
- `.github/workflows` - CI, release, and Docker packaging automation.
|
|
|
|
## Hard Rules
|
|
|
|
- Keep routes thin: put request handling in controllers and reusable behavior in services.
|
|
- Keep Web UI state under `HERMES_WEB_UI_HOME` or `HERMES_WEBUI_STATE_DIR`.
|
|
- Keep Hermes Agent state separate from Web UI state.
|
|
- Register local API routes before proxy catch-all routes.
|
|
- Use structured APIs and argument arrays instead of shell string construction.
|
|
- Add user-facing strings to every locale file.
|
|
- Do not mix unrelated refactors into a bug fix.
|
|
|
|
## Red Lines
|
|
|
|
- `packages/server/src/services/hermes/agent-bridge/python/` is read-only vendored code.
|
|
- The `/chat-run` Socket.IO event contract must not change event names, field names,
|
|
field types, or emission timing. Adding optional fields is allowed.
|
|
- Hermes `state.db` is read-only. Node-side code must never open it; read session
|
|
history through the bridge's `getHistory`/`getOutput` instead.
|
|
- `services/hermes/group-chat/`, `lib/context-compressor/`, and
|
|
`services/hermes/context-engine/` are the chat chain: changes require a
|
|
`docs/chat-chain-changes/<date>-<slug>.md` fragment.
|
|
- `packages/desktop` and `packages/website` are removed; do not reintroduce them.
|
|
- This repo is a reimplementation. A few upstream service addresses are load-bearing
|
|
and are deliberately kept, each with a whitelist entry in
|
|
`scripts/harness-check.mjs`: the global-agent relay (`api.hermes-studio.ai`), the
|
|
OpenRouter referer, and the ESP32 purchase link. Do not "clean them up" as legacy
|
|
brand text — removing them breaks those features. Do not read the relay address as
|
|
project identity: this deployment is not affiliated with the upstream operator.
|
|
- The online-update channel (`runtime-version-manager.ts`) has no default URL. It reads
|
|
`HERMES_WEB_UI_VERSION_MANIFEST_URL` / `HERMES_WEB_UI_DOWNLOAD_BASE_URL` /
|
|
`HERMES_WEB_UI_GITHUB_REPO` and degrades with a named error when unset. Do not
|
|
reintroduce a hardcoded upstream URL.
|
|
- ArkScope vendor (`packages/client/src/vendor/arkscore/`) is decorative only:
|
|
login-page title, Journey graph background, first-load / empty states. Never in
|
|
chat, forms, tables, or click-dense areas. Decorative layers must be
|
|
`pointer-events: none` and carry no information or interaction.
|
|
|
|
## When The Agent Gets Stuck
|
|
|
|
Improve the harness instead of repeating the same prompt. Add missing docs,
|
|
tests, logs, scripts, or CI checks so the next agent can see and verify the
|
|
constraint directly.
|