theo-agent-dashboard

Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs | README

AGENTS.md (2815B)

      1 # AGENTS.md — Theo Agent Dashboard
      2 
      3 ## What
      4 React + FastAPI dashboard for managing Hermes agent sessions. Topics, chat with tool-call rendering, attachments, branching, model picker, search.
      5 
      6 ## Stack
      7 - **Backend**: Python 3.13, FastAPI, SQLite (WAL), aiohttp
      8 - **Frontend**: React 19, TypeScript, Vite 6, Tailwind CSS 4, Zustand
      9 - **Deploy**: systemd + Caddy at dash.packetloaf.privatedns.org
     10 
     11 ## Commands
     12 ```
     13 # Backend
     14 cd backend && .venv/bin/pytest tests/ -q
     15 cd backend && .venv/bin/pytest tests/ --cov=app --cov-report=term-missing
     16 
     17 # Frontend  
     18 cd frontend && npx vitest run
     19 cd frontend && npx vitest run --coverage
     20 
     21 # Build + Deploy
     22 cd frontend && npm run build && cp -r dist/* ../backend/static/
     23 sudo systemctl restart theo-agent-dashboard  # REQUIRED for backend code changes
     24 ```
     25 
     26 **Deploy rules:**
     27 - Frontend-only changes (JS/CSS): `cp -r dist/* ../backend/static/` — no restart needed (served from disk)
     28 - Backend changes (Python): MUST `sudo systemctl restart theo-agent-dashboard` — compiled modules (regexes, constants) are loaded at import time and won't update on disk change alone
     29 - Both: do both steps
     30 
     31 ## Architecture
     32 - Backend proxies ALL session/message/model operations to Hermes API at localhost:8642
     33 - Topics + topic-session mapping stored locally in SQLite (not in Hermes)
     34 - WebSocket chat bridges client ↔ Hermes via SSE stream
     35 - Auth: single-user, argon2id password, JWT in HttpOnly cookie
     36 - Frontend served as static files from backend in production
     37 
     38 ## Key Files
     39 - `backend/app/hermes_client.py` — async HTTP client for Hermes API
     40 - `backend/app/routes/chat.py` — WebSocket → SSE proxy
     41 - `frontend/src/components/Chat/ChatView.tsx` — main chat UI
     42 - `frontend/src/store/` — Zustand stores (auth, chat, session, topic, theme)
     43 
     44 ## Mutation Testing
     45 - Backend hermes_client.py: fully mutation-tested (90.3%), mocks aiohttp
     46 - Other backend files: excluded via `# pragma: no mutate: block` (proxy architecture)
     47 - `docs/mutation-exclusions.md` documents all exclusions
     48 - Constitution requires reevaluation when non-proxy logic is added
     49 
     50 ## Gotchas
     51 - Hermes API server MUST be running at localhost:8642 for chat to work
     52 - SSE endpoint is `/api/sessions/{id}/chat/stream` (not `/v1/runs`)
     53 - Attachments: all files (images included) sent as disk paths to Hermes (not base64)
     54 - Test hermes_client by mocking aiohttp, NOT by mocking `_request`
     55 - New route modules with DB access MUST wire `set_db()` from `main.py` lifespan (attachments.py had `_db=None` until fix-002)
     56 - `main.py` lifespan: `set_db` (topics) + `set_attachment_db` (attachments) + `app.state.db = _DB` (sessions route queries attachments) — all three required
     57 - Attachments uploaded before session creation use `session_id='default'` and won't match on reload — always create session before uploading (fix-003)