# agent-helm v2 — plan

## Mål

Fjärrstyra CLI-agenter (agy i första hand) som "claude-desktop-appen
fast för Googles agent": se sessionen, skicka prompts, svara på
frågor/godkännanden, byta läge, ändra inställningar och ta emot delade
filer — från webb och Android, utan att exponera något publikt.

## Varför v2

v1 (Node: daemon→server-på-Pi5→web, Gemini-hooks) dog med Gemini
CLI:s OAuth-nedläggning, och hook-integrationen visade sig skör per
agent. v2 vänder på det: **tmux är sanningskällan**. Servern läser
skärmen och skickar tangenter — då spelar det ingen roll vilken agent
som kör eller hur dess hooks ser ut.

## Arkitektur

```
Android (egen SSH-tunnel) ─┐
webb-PWA (LAN/tunnel) ─────┼──► helmd :8788 (Go, REST+SSE, token) ──tmux──► agy
                           │        │
                           └────────┴──► ntfy.brasse-pc.eu (topics: agent-helm, claude)
```

- **Ingen publik exponering**: bind 127.0.0.1 eller LAN; utifrån via
  SSH-tunnel (mobilklienten sätter upp sin egen mot Pi5 → vidare till
  värddatorn, alt. helmd på Pi5 direkt).
- v1-koden (packages/) ligger kvar tills webbklienten är portad.

## Steg

1. ✅ **helmd** (`helmd/`): Go-server, enskild statisk binär.
   - tmux-hantering: skapa/adoptera/döda sessioner (`helm-*`),
     paste+Enter för prompts, tangenter, skärmdump med/utan ANSI.
   - Frågedetektor (`question.go`): agy-godkännanden, trust-prompts,
     numrerade/onumrerade listor; stabil hash per fråga; testad mot
     riktiga agy-dumpar + mock.
   - REST+SSE-API, bearer-token, fildelning (`helmd share`), ntfy
     (event-pushar + `POST /api/notify`, topics `agent-helm`/`claude`).
   - Isolerat integrationstest i Docker (26 tester), CI-release
     `helmd-latest` (x64 + arm64).
2. ✅ **Webbklient v2** (`helmd/web/`): **ramverksfri** ES-modul-SPA,
   inbäddad i binären med `go:embed` — hela v2 är fortfarande EN fil,
   ingen Node-toolchain i CI. (Beslut: vanilla i stället för Vue-port —
   UI-ytan är liten, eslint/byggkedjan försvinner, agenter underhåller
   koden lättare.)
   - Token-login (localStorage), sessionslista med status/❓-badge,
     ANSI-färgad skärmvy (SSE + poll-fallback), promptfält,
     **frågekort med knappar**, tangent-verktygsrad (Esc/pilar/Enter/
     ^C/Läge), delningsflik (bilder, sandboxad HTML-iframe, egen
     md-renderare), inställningsvy mot `PUT /api/config`.
   - Browser-verifierad mot riktig agy: prompt → godkännandefråga →
     svar via kort → kommandot kört; delningar renderade.
   - Deploy på Pi5: docker-stack `helmd` (arm64-image via
     `.gitea/workflows/helmd-image.yaml` → `localhost:5000/helmd`),
     **LAN-only — ingen NPM-vhost**; sessioner kör bash/agenter i
     containern.
3. ⬜ **Android-klient**: nytt projekt eller Capacitor-port av PWA:n.
   - Egen SSH-tunnel (t.ex. sshj/JSch) → Pi5 → helmd; token +
     värdprofil i appen; push via ntfy-appen eller UnifiedPush.
4. 🔨 **Hub på Pi5** (påbörjad 2026-08-06): central server som alla
   agenter ansluter utåt till (delad agent-nyckel, inga konton) och
   där web-/CLI-klienter loggar in (lokalt admin-konto →
   `Authenticator`-interface för LDAP senare) och styr alla agenters
   sessioner. Full design: **[hub-plan.md](hub-plan.md)**.

## Beslut

- **REST + SSE, inte GraphQL/WS** i v1 — enklast att testa med curl,
  räcker för kort-UI. WS-terminal kan läggas till senare.
- **Go, statisk binär** — samma modell som agent-tools; trivial
  cross-compile till Pi (arm64).
- **tmux-scraping i stället för hooks** — agentoberoende, överlever
  omstarter (adoption), fallback är alltid rå tangentkanal.
- ntfy-topics: `agent-helm` (serverhändelser), `claude` (Claudes
  direktnotiser). Allowlist i config.

## Öppna frågor

- Verifiera agy:s lägesbytes-tangent (Shift+Tab antas).
- Webbklient: behålla Vue 3 eller byta till ren Vite+TS utan ramverk?
- Android: Capacitor-wrap av PWA:n (snabbast) vs native Kotlin
  (bäst tunnel-kontroll). Lutar åt Capacitor + termux-liknande
  tunnel-lib.
- helmd på Pi5 i container med tmux? (Kör agenter direkt på Pi:n.)