feat(adminapi): streaming chat with multimodal, regenerate, routing override

Rebuild the Chat tab on top of Server-Sent Events so tokens render live,
tool calls appear as chips the moment the agent invokes them, and the
input stays free while the assistant is thinking. Reuses the existing
agent.ProcessStream + router.ChatStream stack; no provider changes
needed.

- Admin API: POST /chat/stream (SSE: token/tool_call/done/error +
  15s heartbeat), POST /chat/pop (drop last user turn, return text);
  per-user chat_id from X-authentik-username (FNV-64 hash, falls back
  to -1 under bearer auth); 25 MB body cap for base64 attachments.
- Routing: llm.WithForcedRole ctx override, consulted by Router.pick
  before the global override so per-request role pins don't mutate
  shared state.
- Store: TruncatableStore interface + SQLite/Postgres impls for
  LastUserMessage + TruncateAfter; agent.PopLastUserTurn helper.
- Client: fetch + ReadableStream SSE consumer (no htmx/EventSource),
  typing dots, tool chips, Stop/Esc abort, drag-drop/paste images,
  Edit/Regenerate on last bubbles, code-block copy, localStorage
  draft, role dropdown, smart scroll.

Author: Alexey Panfilov

CLAUDE.md

@@ -321,8 +321,14 @@ Routes:
 - `POST /slots/<slot>/assign` (form: `model_id=...`) — `Router.SetProviderModel` with caps from the store; returns refreshed `routing` partial
 - `POST /routing/<role>/set` (form: `slot=...`) — `Router.SetRole` (maps `default` → `primary`); returns refreshed `routing` partial
 - `POST /refresh` — `llm.FetchOpenRouterModels` + upsert; returns refreshed `models_tbody` partial
+- `GET /chat` — chat page; history scoped to the caller's per-user chat id (FNV-64 hash of `X-authentik-username`, mapped to negative range; falls back to `-1` under bearer-token auth)
+- `POST /chat/stream` — SSE endpoint. Body: `message`, optional `image[]` (base64 data URIs), optional `role` (simple/default/complex). Drives `agent.ProcessStream`; emits events `token` (`{delta}`), `tool_call` (`{name}`), `done` (`{model, tools, text}`), `error` (`{message}`), plus `:ping` comments every 15 s. Body capped at 25 MB; per-request routing override via `llm.WithForcedRole(ctx, role)`
+- `POST /chat/pop` — drops the last user turn (via `agent.PopLastUserTurn` → `store.TruncatableStore`) and returns `{ok, text}`. UI uses this for Regenerate (pop + re-stream with returned text) and Edit (pop + put text back into the input)
+- `POST /chat/clear` — resets session via `store.ClearHistory` for the caller's chat id; returns empty message container
 - `GET /healthz` — unauthenticated liveness probe
 
+**Chat tab notes:** `WriteTimeout: 0` on the admin HTTP server (long agent chains). Client is a fetch + `ReadableStream` SSE consumer (not htmx / `EventSource`) so the same endpoint can drive a future native app. Typing indicator is three bouncing dots until the first `token` event; tool-call chips (🔧) appear inline in the bot bubble meta; `Esc` or the Stop button abort via `AbortController`. Markdown rendered client-side via `marked.js` (CDN) on each `done` event, with copy-buttons hydrated on `<pre>` blocks. Draft persisted in `localStorage`. Hover actions (Edit on last user bubble, Regenerate on last bot bubble) call `/chat/pop`. Images pasted or dropped into the form are attached as `image_url` parts in a multimodal `llm.Message`.
+
 The admin API never imports the Authentik library — it only _trusts_ the forwarded header. All actual authentication happens upstream in Traefik via the `authentik-auth` middleware. When running without authentik (local dev), the bearer token flow is the default.
 
 ### Persistent settings (`kv_settings`)

internal/adminapi/chat.go

@@ -2,28 +2,47 @@ package adminapi
 
 import (
 	"context"
-	"html"
+	"encoding/json"
+	"fmt"
+	"hash/fnv"
 	"net/http"
 	"strings"
+	"sync"
 	"time"
 
 	"telegram-agent/internal/llm"
 )
 
-// adminChatID is the dedicated chat ID for the admin web UI — negative so it
-// never collides with real Telegram user IDs.
-const adminChatID int64 = -1
+// defaultAdminChatID is used when no forward-auth user is present (local dev
+// via bearer token). Negative so it never collides with real Telegram user IDs.
+const defaultAdminChatID int64 = -1
 
 // ChatAgent is the subset of agent.Agent the chat handler needs.
 type ChatAgent interface {
 	Process(ctx context.Context, chatID int64, userMsg llm.Message, onToolCall func(string)) (string, error)
+	ProcessStream(ctx context.Context, chatID int64, userMsg llm.Message, onToolCall func(string), onChunk func(string)) (string, error)
 	GetChatHistory(chatID int64) []llm.Message
 	ClearChatHistory(chatID int64)
+	PopLastUserTurn(chatID int64) (string, bool)
 }
 
 // SetAgent wires the agent so the Chat tab can process messages.
 func (s *Server) SetAgent(a ChatAgent) { s.agent = a }
 
+// chatIDFor derives a per-user chat_id from the forward-auth username when
+// available, otherwise returns the shared dev sentinel. Mapped to the negative
+// range so it never collides with positive Telegram user IDs; offset by -2 so
+// it also can't collide with the dev sentinel (-1).
+func (s *Server) chatIDFor(r *http.Request) int64 {
+	user := strings.TrimSpace(r.Header.Get(s.cfg.ForwardAuthHeader))
+	if user == "" {
+		return defaultAdminChatID
+	}
+	h := fnv.New64a()
+	_, _ = h.Write([]byte(user))
+	return -int64(h.Sum64()&0x7FFFFFFFFFFFFFFF) - 2
+}
+
 // routedModel returns the actual model ID used on the last router call,
 // falling back to the slot name when the provider doesn't expose CurrentModel.
 func routedModel(r interface {
@@ -54,7 +73,8 @@ type chatData struct {
 func (s *Server) handleChat(w http.ResponseWriter, r *http.Request) {
 	data := chatData{ActiveTab: "chat"}
 	if s.agent != nil {
-		for _, m := range s.agent.GetChatHistory(adminChatID) {
+		chatID := s.chatIDFor(r)
+		for _, m := range s.agent.GetChatHistory(chatID) {
 			if m.Role != "user" && m.Role != "assistant" {
 				continue
 			}
@@ -67,40 +87,163 @@ func (s *Server) handleChat(w http.ResponseWriter, r *http.Request) {
 	}
 }
 
-func (s *Server) handleChatSend(w http.ResponseWriter, r *http.Request) {
+// handleChatStream is a Server-Sent Events endpoint that streams the
+// agent's response back to the client. Event types:
+//
+//	token       — {"delta": "..."} incremental assistant text
+//	tool_call   — {"name": "..."} a tool is being invoked
+//	done        — {"model": "...", "tools": [...], "text": "..."} final reply
+//	error       — {"message": "..."} unrecoverable failure
+//
+// The endpoint also emits ":ping" comment lines every 15 s to keep the
+// connection alive through reverse proxies.
+func (s *Server) handleChatStream(w http.ResponseWriter, r *http.Request) {
 	if r.Method != http.MethodPost {
 		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
 		return
 	}
+	flusher, ok := w.(http.Flusher)
+	if !ok {
+		http.Error(w, "streaming unsupported", http.StatusInternalServerError)
+		return
+	}
+	// Allow up to 25 MB of request body so base64-encoded images fit.
+	r.Body = http.MaxBytesReader(w, r.Body, 25*1024*1024)
 	if err := r.ParseForm(); err != nil {
-		http.Error(w, "bad request", http.StatusBadRequest)
+		http.Error(w, "bad request: "+err.Error(), http.StatusBadRequest)
 		return
 	}
 	text := strings.TrimSpace(r.FormValue("message"))
-	if text == "" {
-		w.WriteHeader(http.StatusOK)
+	images := r.Form["image"]
+	if text == "" && len(images) == 0 {
+		http.Error(w, "empty message", http.StatusBadRequest)
 		return
 	}
 	if s.agent == nil {
-		writeChatFragment(w, text, "", nil, "agent not configured", "")
+		http.Error(w, "agent not configured", http.StatusServiceUnavailable)
 		return
 	}
 
+	userMsg := buildUserMessage(text, images)
+	chatID := s.chatIDFor(r)
+
+	// Per-request routing role override from the UI dropdown.
+	ctxRole := strings.TrimSpace(r.FormValue("role"))
+	switch ctxRole {
+	case "", "simple", "default", "complex":
+		// valid (empty = auto-route)
+	default:
+		ctxRole = ""
+	}
+
+	w.Header().Set("Content-Type", "text/event-stream")
+	w.Header().Set("Cache-Control", "no-cache")
+	w.Header().Set("Connection", "keep-alive")
+	w.Header().Set("X-Accel-Buffering", "no") // disable nginx/traefik buffering
+	w.WriteHeader(http.StatusOK)
+	flusher.Flush()
+
 	ctx, cancel := context.WithTimeout(r.Context(), 10*time.Minute)
 	defer cancel()
+	if ctxRole != "" {
+		ctx = llm.WithForcedRole(ctx, ctxRole)
+	}
 
+	// All writes to w go through sendMu. ProcessStream calls callbacks on its
+	// goroutine; the heartbeat goroutine ticks on another; serialising is
+	// cheaper than a funnel channel for this low rate.
+	var sendMu sync.Mutex
+	write := func(event, data string) {
+		sendMu.Lock()
+		defer sendMu.Unlock()
+		writeSSE(w, flusher, event, data)
+	}
+
+	// Heartbeat keeps the connection open through idle-timeout proxies.
+	hbStop := make(chan struct{})
+	go func() {
+		ticker := time.NewTicker(15 * time.Second)
+		defer ticker.Stop()
+		for {
+			select {
+			case <-ctx.Done():
+				return
+			case <-hbStop:
+				return
+			case <-ticker.C:
+				sendMu.Lock()
+				_, _ = fmt.Fprint(w, ": ping\n\n")
+				flusher.Flush()
+				sendMu.Unlock()
+			}
+		}
+	}()
+	defer close(hbStop)
+
+	var toolsMu sync.Mutex
 	var tools []string
-	resp, err := s.agent.Process(ctx, adminChatID, llm.Message{Role: "user", Content: text}, func(tool string) {
-		tools = append(tools, tool)
-	})
 
-	errStr := ""
+	var lastLen int
+	onChunk := func(accumulated string) {
+		if len(accumulated) <= lastLen {
+			return
+		}
+		delta := accumulated[lastLen:]
+		lastLen = len(accumulated)
+		b, _ := json.Marshal(map[string]string{"delta": delta})
+		write("token", string(b))
+	}
+	onToolCall := func(name string) {
+		toolsMu.Lock()
+		tools = append(tools, name)
+		toolsMu.Unlock()
+		b, _ := json.Marshal(map[string]string{"name": name})
+		write("tool_call", string(b))
+		// Each tool_call resets the streaming buffer on the client (the agent
+		// will re-run the LLM after executing tools, producing a new text
+		// stream). Reset the server-side length tracker so we don't clip the
+		// next assistant text.
+		lastLen = 0
+	}
+
+	resp, err := s.agent.ProcessStream(ctx, chatID, userMsg, onToolCall, onChunk)
+
 	if err != nil {
-		errStr = err.Error()
+		b, _ := json.Marshal(map[string]string{"message": err.Error()})
+		write("error", string(b))
+		return
 	}
 
-	model := routedModel(s.router)
-	writeChatFragment(w, text, resp, tools, errStr, model)
+	toolsMu.Lock()
+	finalTools := append([]string(nil), tools...)
+	toolsMu.Unlock()
+	payload := map[string]any{
+		"model": routedModel(s.router),
+		"tools": finalTools,
+		"text":  resp,
+	}
+	b, _ := json.Marshal(payload)
+	write("done", string(b))
+}
+
+// handleChatPop drops the last user turn and returns the removed text. The
+// UI uses this for Edit — the text goes back into the input field so the user
+// can revise and resubmit. For Regenerate the UI calls this then immediately
+// calls /chat/stream with the same text.
+func (s *Server) handleChatPop(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	if s.agent == nil {
+		http.Error(w, "agent not configured", http.StatusServiceUnavailable)
+		return
+	}
+	text, ok := s.agent.PopLastUserTurn(s.chatIDFor(r))
+	w.Header().Set("Content-Type", "application/json")
+	payload := map[string]any{"ok": ok, "text": text}
+	b, _ := json.Marshal(payload)
+	_, _ = w.Write(b)
 }
 
 func (s *Server) handleChatClear(w http.ResponseWriter, r *http.Request) {
@@ -109,60 +252,46 @@ func (s *Server) handleChatClear(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 	if s.agent != nil {
-		s.agent.ClearChatHistory(adminChatID)
+		s.agent.ClearChatHistory(s.chatIDFor(r))
 	}
 	w.Header().Set("Content-Type", "text/html; charset=utf-8")
-	w.Write([]byte(`<div id="chat-messages" class="chat-messages"></div>`)) //nolint:errcheck
+	_, _ = w.Write([]byte(`<div id="chat-messages" class="chat-messages"></div>`))
 }
 
-func writeChatFragment(w http.ResponseWriter, userText, botText string, tools []string, errStr, model string) {
-	w.Header().Set("Content-Type", "text/html; charset=utf-8")
-	ts := time.Now().Format("15:04")
-
-	var sb strings.Builder
-
-	// User bubble.
-	sb.WriteString(`<div class="chat-msg chat-msg--user">`)
-	sb.WriteString(`<div class="chat-msg__meta">You &middot; `)
-	sb.WriteString(ts)
-	sb.WriteString(`</div><div class="chat-msg__body">`)
-	sb.WriteString(html.EscapeString(userText))
-	sb.WriteString(`</div></div>`)
-
-	// Assistant bubble.
-	sb.WriteString(`<div class="chat-msg chat-msg--bot">`)
-	// Meta line: model + tools.
-	sb.WriteString(`<div class="chat-msg__meta">`)
-	if model != "" {
-		sb.WriteString(html.EscapeString(model))
-		sb.WriteString(` &middot; `)
-	}
-	sb.WriteString(ts)
-	if len(tools) > 0 {
-		sb.WriteString(` &middot; <span class="chat-tools">`)
-		for i, t := range tools {
-			if i > 0 {
-				sb.WriteString(`, `)
-			}
-			sb.WriteString(html.EscapeString(t))
+// buildUserMessage packs text + any attached images into an llm.Message.
+// When images are present we build a multimodal Parts payload; otherwise
+// we stick with plain Content so non-vision providers see a simple string.
+// Accepts data URIs ("data:image/...;base64,...") or raw http(s) URLs.
+func buildUserMessage(text string, images []string) llm.Message {
+	if len(images) == 0 {
+		return llm.Message{Role: "user", Content: text}
+	}
+	parts := make([]llm.ContentPart, 0, len(images)+1)
+	if text != "" {
+		parts = append(parts, llm.ContentPart{Type: "text", Text: text})
+	}
+	for _, url := range images {
+		url = strings.TrimSpace(url)
+		if url == "" {
+			continue
 		}
-		sb.WriteString(`</span>`)
+		parts = append(parts, llm.ContentPart{
+			Type:     "image_url",
+			ImageURL: &llm.ImageURL{URL: url},
+		})
 	}
-	sb.WriteString(`</div>`)
+	return llm.Message{Role: "user", Parts: parts}
+}
 
-	// Body: raw markdown stored in data-md, rendered by marked.js on the client.
-	if errStr != "" {
-		sb.WriteString(`<div class="chat-msg__body"><span class="chat-error">Error: `)
-		sb.WriteString(html.EscapeString(errStr))
-		sb.WriteString(`</span></div>`)
-	} else {
-		sb.WriteString(`<div class="chat-msg__body md" data-md="`)
-		sb.WriteString(html.EscapeString(botText))
-		sb.WriteString(`"></div>`)
+// writeSSE emits one SSE event. Multi-line data payloads are split into
+// separate `data: ` lines per the SSE spec.
+func writeSSE(w http.ResponseWriter, f http.Flusher, event, data string) {
+	if event != "" {
+		_, _ = fmt.Fprintf(w, "event: %s\n", event)
 	}
-
-	sb.WriteString(`</div>`) // .chat-msg--bot
-	sb.WriteString(`<div class="chat-scroll-sentinel"></div>`)
-
-	w.Write([]byte(sb.String())) //nolint:errcheck
+	for _, line := range strings.Split(data, "\n") {
+		_, _ = fmt.Fprintf(w, "data: %s\n", line)
+	}
+	_, _ = fmt.Fprint(w, "\n")
+	f.Flush()
 }

internal/adminapi/server.go

@@ -133,7 +133,8 @@ func (s *Server) registerRoutes(mux *http.ServeMux) {
 	mux.Handle("/mcp", authed(http.HandlerFunc(s.handleMCP)))
 	mux.Handle("/mcp/", authed(http.HandlerFunc(s.handleMCPRouter))) // dispatches {name}/set | {name}/delete
 	mux.Handle("/chat", authed(http.HandlerFunc(s.handleChat)))
-	mux.Handle("/chat/send", authed(http.HandlerFunc(s.handleChatSend)))
+	mux.Handle("/chat/stream", authed(http.HandlerFunc(s.handleChatStream)))
+	mux.Handle("/chat/pop", authed(http.HandlerFunc(s.handleChatPop)))
 	mux.Handle("/chat/clear", authed(http.HandlerFunc(s.handleChatClear)))
 }