EPIC: Hyperia Agent configuration pane — providers, curated local models, services, chat wiring

[kordless]

What (distilled from spoken spec, 2026-07-01)

A dedicated Hyperia Agent configuration pane, reached from the picker's install view (Hyperia → configure) — and still reachable after setup (configured = listed; unconfigure = drops out of the agent list).

Providers & models

• Providers: Anthropic, OpenAI, Grok, Gemini (BYO API key, "you're going to burn tokens" warning in setup) + Ollama (local) + the future Sailfish container (Ollama/OpenAI-compatible endpoint, optimized Gemma stack, tool-capable — API specs TBD, not stood up yet).
• Default per provider = best-in-class cheapest agentic runner, user-changeable.
• Model catalog: fetch https://nemesis8.nuts.services/models (same source nemesis8 uses; live today: claude 10 / codex 70 / gemini 39 / grok 9 / ollama 35, ttl 3600). Multi-toggle UX: pick provider → pick model.
• Ollama list heavily curated: small fast models only — prefer gemma3n:e4b-class + Ornith; E2B considered broken/poorly quantized, exclude. Also include the strong Ollama cloud models in the curated list.
• GPU-size gating: detect VRAM; hide models the card can't run. No Ollama → show install instructions; Docker + ≥16 GB card → offer the Sailfish container pull (once stood up).

Keys & config

• API keys pasted in the pane → OS secure storage (API keys need OS secure storage — safeStorage/keyring; config-file plaintext is interim #130 — not implemented yet; interim = config file per user direction).
• A hand-editable config always exists alongside the UI (config.agent.* in the shared Hyperia config).

Services section

• Shivvr (embeddings), Grub crawler (local container — setup instructions), transcription service (must register a callback endpoint to call in when done — wire later), nuts.services login — replicate Meridian's pattern (../meridian/electron/main.js:108-214): system-browser magic-link/OAuth → local HTTP callback catches ?token= → JWT persisted (userData file), expiry-checked, Bearer on service calls.

Agent chat pane (once configured)

• Chat box, thinking indicator, tool runs displayed, streaming — largely EXISTS in sidecar/static/shell.html (ghost SSE: text_delta/tool_start/tool_result/thinking + show_input/show_button/show_picker blocking widgets). Verify the inline multi-choice picker flow (tool asks → options render in-chat → click or reply) end-to-end.
• Token burn display (GhostEvent::Stats exists; meter = feat(chat): context length meter — show token usage in Ghost chat panel #43).
• Theme/style tool for the agent, locked to basics (background, font colors, highlight colors) with readability guardrails (no white-on-white) — overlaps Ghost theme tooling + widget GUI upgrade (color themes) #124.
• Maximus: with a frontier model selected, allow toggling the local extraction model (Ollama w/ correct model or deployed container); prefer E4B/Ornith-class, curated.

Relation to #129 (agent harness & display)

This pane is the config front-door for the same agent; #129's phases (structured events, SSE feed, token meter) feed its runtime display. #53 (settings agent) is adjacent.

Phases

• P1 — Config surface: sidecar GET /agent/config page + GET/POST /api/agent/config (provider/model/keys via config file until API keys need OS secure storage — safeStorage/keyring; config-file plaintext is interim #130), models proxy GET /api/agent/models (nuts.services, 1h cache), curated Ollama allowlist. Picker configure → opens the pane; configured Hyperia appears in the agent pulldown.
• P2 — nuts.services login (Meridian pattern) + services section (Shivvr/Grub/Transcription stubs w/ instructions).
• P3 — GPU VRAM detection + model gating; Ollama install / Sailfish pull paths.
• P4 — Chat pane verification + token meter + inline picker polish (with EPIC: Agent harness & display — structured events, live feed, chat panel upgrades #129/feat(chat): context length meter — show token usage in Ghost chat panel #43).
• P5 — Theme tool w/ guardrails (Ghost theme tooling + widget GUI upgrade (color themes) #124), Maximus local-model toggle, transcription callback registration.