# 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** (`packages/web`): porta till helmd-API:t.
   - Sessionslista, skärmvy (poll + SSE), promptfält, frågekort med
     knappar, läges-/inställningsvy.
   - Delningsflik: html/md renderas, png/jpg visas, md till html.
   - Uppdaterad look. Serveras statiskt av helmd (embed) eller nginx.
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.

## 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.)