agent-helm/doc/plan.md

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.

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