Files
archie/internal/webui/chat.go
T

686 lines
23 KiB
Go

package webui
import (
"context"
"encoding/json"
"errors"
"fmt"
"log/slog"
"net/http"
"path/filepath"
"strings"
"sync"
"time"
"github.com/google/uuid"
"github.com/samcharles93/archie-core/internal/domain/lifecycle"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/releaseupdate"
)
// ChatService is the shared conversational surface exposed to the dashboard.
// Handlers depend on the Gateway-owned contract and never retain Gateway
// implementation objects.
type ChatService struct {
Contract messaging.ChatContract
Updates ChatUpdateService
updateMu sync.Mutex
updateInProgress bool
}
// ChatUpdateService is the shared release workflow used by chat gateways.
// The web adapter uses recipient zero for the locally authenticated operator.
type ChatUpdateService interface {
Check(context.Context, int64) (releaseupdate.Snapshot, error)
Defer(context.Context, int64, releaseupdate.Snapshot) error
Install(context.Context, releaseupdate.Snapshot, releaseupdate.InstallMeta, func(string)) (releaseupdate.Result, error)
CanInstall() bool
}
type chatMessageRequest struct {
ChannelID string `json:"channel_id"`
SourceID string `json:"source_id"`
Text string `json:"text"`
// Page is the dashboard route the operator is on (e.g. "/tasks"). It is
// set by the web chat so the agent's system prompt can state where the
// operator is looking and point them somewhere relevant.
Page string `json:"page,omitempty"`
// Voice is a recorded clip, transcribed by the Gateway like a Telegram
// voice note. Base64 in JSON.
Voice *chatVoice `json:"voice,omitempty"`
}
type chatVoice struct {
Data []byte `json:"data"`
MIMEType string `json:"mime_type"`
}
// maxVoiceBytes bounds a recorded clip: about ten minutes of Opus.
const maxVoiceBytes = 10 << 20
// chatMessageView is one entry of a session's history as the dashboard
// reads it. The persisted record is messaging.Message; this is the shape
// the browser has always been served, kept here so the HTTP response owns
// its own field names rather than exposing a domain struct's.
type chatMessageView struct {
MessageID string
SourceID string
From string
Text string
At time.Time
// Tagged, alone among these fields: a transcript written before
// attachments persisted must keep the payload it has always had, so a
// message with no media omits the key rather than serving null.
Media []chatMediaView `json:"media,omitempty"`
}
// chatMediaView is a stored message attachment as the dashboard reads it.
type chatMediaView struct {
Type string `json:"type"`
FileName string `json:"file_name,omitempty"`
MIMEType string `json:"mime_type,omitempty"`
FileSize *int64 `json:"file_size,omitempty"`
Width *int `json:"width,omitempty"`
Height *int `json:"height,omitempty"`
Duration *int `json:"duration,omitempty"`
URL string `json:"url,omitempty"`
}
// chatMediaViews maps a message's stored attachments onto the transcript
// view, keeping the descriptive fields a reader needs to know a file was
// there.
func chatMediaViews(media []messaging.MediaAttachment) []chatMediaView {
if len(media) == 0 {
return nil
}
views := make([]chatMediaView, 0, len(media))
for _, attachment := range media {
views = append(views, chatMediaView{
Type: attachment.Type,
FileName: attachment.FileName,
MIMEType: attachment.MIMEType,
FileSize: attachment.FileSize,
Width: attachment.Width,
Height: attachment.Height,
Duration: attachment.Duration,
URL: attachment.URL,
})
}
return views
}
type chatCancelRequest struct {
SessionID string `json:"session_id"`
}
type chatUpdateRequest struct {
Snapshot releaseupdate.Snapshot `json:"snapshot"`
}
type chatTurnView struct {
TurnID string `json:"turn_id"`
InputMessageID string `json:"input_message_id,omitempty"`
AssistantMessageID string `json:"assistant_message_id,omitempty"`
Status messaging.TurnStatus `json:"status"`
Error string `json:"error,omitempty"`
ToolCalls []chatToolView `json:"tool_calls,omitempty"`
}
type chatToolView struct {
ID string `json:"id,omitempty"`
Name string `json:"name"`
Parameters string `json:"parameters,omitempty"`
Summary string `json:"summary"`
Failed bool `json:"failed"`
DurationMS int64 `json:"duration_ms,omitempty"`
TextOffset int `json:"text_offset,omitempty"`
}
// chatAPI owns the /api/chat routes and the state they share: questions
// waiting for the browser's answer and files a turn offered for download.
type chatAPI struct {
chat *ChatService
log *slog.Logger
updateReportPath string
configSource func() ConfigViewSource
asks chatAsks
files chatFiles
}
func newChatAPI(s *Server) *chatAPI {
return &chatAPI{chat: s.Chat, log: s.Log, updateReportPath: s.UpdateReportPath, configSource: s.configSource}
}
func (a *chatAPI) register(mux *http.ServeMux) {
mux.HandleFunc("GET /api/chat/sessions", a.handleChatSessions)
mux.HandleFunc("GET /api/chat/sessions/{id}/messages", a.handleChatMessages)
mux.HandleFunc("GET /api/chat/sessions/{id}/turns", a.handleChatTurns)
mux.HandleFunc("POST /api/chat/stream", a.handleChatStream)
mux.HandleFunc("POST /api/chat/cancel", a.handleChatCancel)
mux.HandleFunc("POST /api/chat/answer", a.handleChatAnswer)
mux.HandleFunc("GET /api/chat/file/{token}", a.handleChatFile)
mux.HandleFunc("GET /api/chat/update", instanceOnly(a.handleChatUpdate))
mux.HandleFunc("POST /api/chat/update/defer", instanceOnly(a.handleChatUpdateDefer))
mux.HandleFunc("POST /api/chat/update/install", instanceOnly(a.handleChatUpdateInstall))
}
func (a *chatAPI) chatReady(w http.ResponseWriter) (*ChatService, bool) {
if a.chat == nil || a.chat.Contract == nil {
http.Error(w, "chat is not configured", http.StatusNotImplemented)
return nil, false
}
return a.chat, true
}
// chatFailureText is what the browser sees when a chat backend call fails.
// The cause can carry SQL, gRPC status details or host paths, so failChat
// logs it server-side and sends this sentence instead, in the same plain
// wording the gateway gives chat readers for a failed turn.
const chatFailureText = "something went wrong on Archie's side. Try again; the server log has the cause."
// failChat logs the real cause with the request's trace and answers with the
// plain sentence. A nil logger is tolerated, as tests build servers without one.
func (a *chatAPI) failChat(ctx context.Context, w http.ResponseWriter, status int, err error) {
if a.log != nil {
a.log.ErrorContext(ctx, "chat endpoint failed", "error", err, "status", status)
}
http.Error(w, chatFailureText, status)
}
func chatUpdateServiceConfigured(updates ChatUpdateService) bool {
return !lifecycle.IsNil(updates)
}
func (a *chatAPI) handleChatSessions(w http.ResponseWriter, r *http.Request) {
chat, ok := a.chatReady(w)
if !ok {
return
}
snapshot, err := chat.Contract.Snapshot(r.Context())
if err != nil {
a.failChat(r.Context(), w, http.StatusInternalServerError, err)
return
}
out := make([]messaging.SessionContext, 0, len(snapshot.Sessions))
for _, session := range snapshot.Sessions {
if a.ownsChatSession(r.Context(), session) {
out = append(out, session)
}
}
writeJSON(w, map[string]any{
"sessions": out,
"models": snapshot.Models,
"models_by_provider": snapshot.ModelsByProvider,
"providers": snapshot.Providers,
"active_model": snapshot.ActiveModel,
"active_provider": snapshot.ActiveProvider,
"voice_available": snapshot.VoiceAvailable,
"commands": chatCommandSpecs(chat),
})
}
func chatCommandSpecs(chat *ChatService) []messaging.CommandSpec {
specs := messaging.LocalCommandSpecs()
return specs
}
func (a *chatAPI) handleChatMessages(w http.ResponseWriter, r *http.Request) {
chat, ok := a.chatReady(w)
if !ok {
return
}
sessionID := r.PathValue("id")
session, found, err := chat.Contract.GetSession(r.Context(), sessionID)
if err != nil {
a.failChat(r.Context(), w, http.StatusInternalServerError, err)
return
}
if !found || !a.ownsChatSession(r.Context(), session) {
http.Error(w, "session not found", http.StatusNotFound)
return
}
messages, err := chat.Contract.RecentMessages(r.Context(), sessionID, 200)
if err != nil {
a.failChat(r.Context(), w, http.StatusInternalServerError, err)
return
}
views := make([]chatMessageView, 0, len(messages))
for _, message := range messages {
views = append(views, chatMessageView{
MessageID: string(message.ID), SourceID: message.SourceID,
From: message.Sender, Text: message.Text, At: message.At,
Media: chatMediaViews(message.Media),
})
}
writeJSON(w, views)
}
func (a *chatAPI) handleChatTurns(w http.ResponseWriter, r *http.Request) {
chat, ok := a.chatReady(w)
if !ok {
return
}
sessionID := r.PathValue("id")
session, found, err := chat.Contract.GetSession(r.Context(), sessionID)
if err != nil {
a.failChat(r.Context(), w, http.StatusInternalServerError, err)
return
}
if !found || !a.ownsChatSession(r.Context(), session) {
http.Error(w, "session not found", http.StatusNotFound)
return
}
turns, err := chat.Contract.RecentTurns(r.Context(), sessionID, 200)
if err != nil {
a.failChat(r.Context(), w, http.StatusInternalServerError, err)
return
}
views := make([]chatTurnView, 0, len(turns))
for _, turn := range turns {
view := chatTurnView{
TurnID: turn.TurnID, InputMessageID: turn.InputMessageID, AssistantMessageID: turn.AssistantMessageID,
Status: turn.Status, Error: turn.Error,
ToolCalls: make([]chatToolView, 0, len(turn.ToolCalls)),
}
for _, tool := range turn.ToolCalls {
view.ToolCalls = append(view.ToolCalls, chatToolView{
ID: tool.ID, Name: tool.Name, Parameters: tool.Parameters,
Summary: tool.Summary(), Failed: tool.Err != "", DurationMS: tool.DurationMS, TextOffset: tool.TextOffset,
})
}
views = append(views, view)
}
writeJSON(w, views)
}
func (a *chatAPI) decodeChatMessage(w http.ResponseWriter, r *http.Request) (messaging.Inbound, bool) {
var req chatMessageRequest
// Base64 makes a clip a third larger than its bytes.
if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, maxVoiceBytes*3/2)).Decode(&req); err != nil {
http.Error(w, "invalid chat message", http.StatusBadRequest)
return messaging.Inbound{}, false
}
req.Text = strings.TrimSpace(req.Text)
var media []messaging.MediaAttachment
if req.Voice != nil {
if len(req.Voice.Data) == 0 || len(req.Voice.Data) > maxVoiceBytes {
http.Error(w, "voice clip is empty or too long", http.StatusBadRequest)
return messaging.Inbound{}, false
}
media = append(media, messaging.MediaAttachment{Type: messaging.MediaTypeVoice, MIMEType: req.Voice.MIMEType, Data: req.Voice.Data})
if err := messaging.ValidateAuthoredInbound(media[0]); err != nil {
http.Error(w, err.Error(), http.StatusBadRequest)
return messaging.Inbound{}, false
}
if req.Text == "" {
req.Text = "[voice message]"
}
}
if req.Text == "" || req.ChannelID == "" {
http.Error(w, "text and channel_id are required", http.StatusBadRequest)
return messaging.Inbound{}, false
}
if req.SourceID == "" {
req.SourceID = newChatSourceID()
}
// The browser has no threading, so the conversation is the channel
// alone. Page is the route the operator is looking at, and stays out
// of the record.
return messaging.Inbound{
Message: messaging.Message{
SourceID: req.SourceID,
ConversationID: messaging.ConversationID{ChannelID: req.ChannelID, ThreadID: chatUser(r.Context())},
SenderID: chatUser(r.Context()),
Sender: "web",
Role: messaging.RoleUser,
Text: req.Text,
},
Media: media,
Page: req.Page,
// The dashboard names the channel it carries; see the platform field's
// note in internal/domain/messaging/inbound.go.
Platform: "web",
}, true
}
// chatStreamEvent is one frame of the chat stream. Text is always emitted.
type chatStreamEvent struct {
Type string `json:"type"`
Text string `json:"text"`
Tool string `json:"tool,omitempty"`
ToolCallID string `json:"tool_call_id,omitempty"`
Parameters string `json:"parameters,omitempty"`
Failed bool `json:"failed,omitempty"`
DurationMS int64 `json:"duration_ms,omitempty"`
TextOffset int `json:"text_offset,omitempty"`
SessionID string `json:"session_id,omitempty"`
// Path and Label carry a dashboard_navigate result so the browser can
// render a clickable chip that routes the operator to the page. Present
// only on a navigate event.
Path string `json:"path,omitempty"`
Label string `json:"label,omitempty"`
// Ask is a question the turn waits on; answered by POST /api/chat/answer.
Ask *chatAsk `json:"ask,omitempty"`
}
// chatStreamSink writes turn text and tool activity to the browser stream.
// showToolCalls is fixed for the stream.
type chatStreamSink struct {
write func(chatStreamEvent)
showToolCalls bool
// files hands out downloads for the local files a turn sends.
files *chatFiles
owner string
}
func (s chatStreamSink) ToolCall(event messaging.ToolCallEvent) {
// A dashboard_navigate call is an explicit point-the-operator-there
// result, not tool narration, so it renders a clickable chip even when
// ShowToolCalls is off. Parse the resolved path/label from the tool's
// JSON result and emit a dedicated navigate frame.
if event.Name == "dashboard_navigate" && event.Err == "" {
var result messaging.DashboardNavigateResult
if err := json.Unmarshal([]byte(event.Output), &result); err == nil && result.Path != "" {
s.write(chatStreamEvent{
Type: "navigate",
Tool: event.Name,
ToolCallID: event.ID,
Path: result.Path,
Label: result.Label,
})
return
}
}
if !s.showToolCalls || event.Name == "" {
return
}
s.write(chatStreamEvent{
Type: "tool",
Tool: event.Name,
ToolCallID: event.ID,
Parameters: event.Parameters,
Text: event.Summary(),
Failed: event.Err != "",
DurationMS: event.DurationMS,
TextOffset: event.TextOffset,
})
}
// Media is sent as a link in the text stream; a local file is reported as
// undelivered.
func (s chatStreamSink) Media(event messaging.MediaEvent) {
att := event.Attachment
switch {
case att.URL != "":
s.write(chatStreamEvent{Type: "delta", Text: "\n\n📎 " + att.Type + ": " + att.URL})
case att.Path != "" && s.files != nil:
name := att.FileName
if name == "" {
name = filepath.Base(att.Path)
}
s.write(chatStreamEvent{Type: "delta", Text: "\n\n📎 [" + name + "](" + chatFileURL(s.files.offerFor(att.Path, att.FileName, s.owner)) + ")"})
}
}
// chatShowToolCalls reports config.ChatConfig.ShowToolCalls, false when no
// config is available.
func (a *chatAPI) chatShowToolCalls(ctx context.Context) bool {
view, found, err := a.configSource()(ctx)
if err != nil || !found {
return false
}
return view.Chat.ShowToolCalls
}
const chatKeepaliveInterval = 15 * time.Second
func (a *chatAPI) handleChatStream(w http.ResponseWriter, r *http.Request) {
chat, ok := a.chatReady(w)
if !ok {
return
}
msg, ok := a.decodeChatMessage(w, r)
if !ok {
return
}
flusher, ok := w.(http.Flusher)
if !ok {
http.Error(w, "streaming unsupported", http.StatusInternalServerError)
return
}
w.Header().Set("Content-Type", "text/event-stream")
w.Header().Set("Cache-Control", "no-cache")
w.Header().Set("X-Accel-Buffering", "no")
// An ask is written from the gateway client's goroutine while this one
// writes the turn's events.
var writeMu sync.Mutex
writeChatEvent := func(event chatStreamEvent, sessionID string) {
writeMu.Lock()
defer writeMu.Unlock()
event.SessionID = sessionID
payload, _ := json.Marshal(event)
_, _ = fmt.Fprintf(w, "data: %s\n\n", payload)
flusher.Flush()
}
// A tool can run for minutes without a frame; a comment line keeps the
// browser's idle timer and any proxy from cutting the stream.
stopKeepalive := make(chan struct{})
keepaliveDone := make(chan struct{})
defer func() {
close(stopKeepalive)
<-keepaliveDone
}()
go func() {
defer close(keepaliveDone)
tick := time.NewTicker(chatKeepaliveInterval)
defer tick.Stop()
for {
select {
case <-stopKeepalive:
return
case <-tick.C:
writeMu.Lock()
_, _ = fmt.Fprint(w, ": keepalive\n\n")
flusher.Flush()
writeMu.Unlock()
}
}
}()
asker := dashboardAsker{asks: &a.asks, write: func(frame chatStreamEvent) { writeChatEvent(frame, "") }}
events, err := chat.Contract.Stream(withDashboardAsks(r.Context(), asker), msg)
if err != nil {
a.failChatStream(r.Context(), writeChatEvent, err)
return
}
sink := chatStreamSink{showToolCalls: a.chatShowToolCalls(r.Context()), files: &a.files, owner: chatUser(r.Context())}
for event := range events {
sink.write = func(frame chatStreamEvent) { writeChatEvent(frame, event.SessionID) }
switch event.Kind {
case "tool":
sink.ToolCall(event.Tool)
case "media":
sink.Media(event.Media)
default:
writeChatEvent(chatStreamEvent{Type: event.Kind, Text: event.Text}, event.SessionID)
}
}
}
// failChatStream answers a stream that never opened with the plain sentence
// as its error frame, logging the real cause server-side.
func (a *chatAPI) failChatStream(ctx context.Context, write func(chatStreamEvent, string), err error) {
if a.log != nil {
a.log.ErrorContext(ctx, "chat stream failed to start", "error", err)
}
write(chatStreamEvent{Type: "error", Text: chatFailureText}, "")
}
func (a *chatAPI) handleChatCancel(w http.ResponseWriter, r *http.Request) {
chat, ok := a.chatReady(w)
if !ok {
return
}
snapshot, err := chat.Contract.Snapshot(r.Context())
if err != nil {
a.failChat(r.Context(), w, http.StatusInternalServerError, err)
return
}
if !snapshot.CancellationAvailable {
http.Error(w, "chat cancellation is not configured", http.StatusNotImplemented)
return
}
var req chatCancelRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil || req.SessionID == "" {
http.Error(w, "session_id is required", http.StatusBadRequest)
return
}
session, found, err := chat.Contract.GetSession(r.Context(), req.SessionID)
if err != nil {
a.failChat(r.Context(), w, http.StatusInternalServerError, err)
return
}
if !found || !a.ownsChatSession(r.Context(), session) {
http.Error(w, "session not found", http.StatusNotFound)
return
}
result, err := chat.Contract.Cancel(r.Context(), req.SessionID)
if err != nil {
a.failChat(r.Context(), w, http.StatusInternalServerError, err)
return
}
writeJSON(w, map[string]any{"cancelled": result.Cancelled, "dropped": result.Dropped})
}
// writeUpdateCheckError answers an unset check command as not configured, which
// the dashboard shows as such rather than as a failure.
func writeUpdateCheckError(w http.ResponseWriter, err error) {
if errors.Is(err, releaseupdate.ErrNotConfigured) {
http.Error(w, "updates are not configured", http.StatusNotImplemented)
return
}
http.Error(w, err.Error(), http.StatusBadGateway)
}
// failUpdateCheck is the chat endpoints' version of writeUpdateCheckError: any
// other cause can carry registry URLs or host paths, so it gets the plain
// sentence and the log rather than the raw error.
func (a *chatAPI) failUpdateCheck(ctx context.Context, w http.ResponseWriter, err error) {
if errors.Is(err, releaseupdate.ErrNotConfigured) {
http.Error(w, "updates are not configured", http.StatusNotImplemented)
return
}
a.failChat(ctx, w, http.StatusBadGateway, err)
}
func (a *chatAPI) handleChatUpdate(w http.ResponseWriter, r *http.Request) {
chat, ok := a.chatReady(w)
if !ok {
return
}
if !chatUpdateServiceConfigured(chat.Updates) {
http.Error(w, "updates are not configured", http.StatusNotImplemented)
return
}
snapshot, err := chat.Updates.Check(r.Context(), 0)
if err != nil {
a.failUpdateCheck(r.Context(), w, err)
return
}
writeJSON(w, map[string]any{
"snapshot": snapshot,
"available": snapshot.Available(),
"can_install": chat.Updates.CanInstall(),
})
}
func (a *chatAPI) handleChatUpdateDefer(w http.ResponseWriter, r *http.Request) {
chat, ok := a.chatReady(w)
if !ok {
return
}
if !chatUpdateServiceConfigured(chat.Updates) {
http.Error(w, "updates are not configured", http.StatusNotImplemented)
return
}
var req chatUpdateRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
http.Error(w, "invalid update snapshot", http.StatusBadRequest)
return
}
if err := chat.Updates.Defer(r.Context(), 0, req.Snapshot); err != nil {
a.failChat(r.Context(), w, http.StatusConflict, err)
return
}
writeJSON(w, map[string]bool{"ok": true})
}
func (a *chatAPI) handleChatUpdateInstall(w http.ResponseWriter, r *http.Request) {
chat, ok := a.chatReady(w)
if !ok {
return
}
if !chatUpdateServiceConfigured(chat.Updates) || !chat.Updates.CanInstall() {
http.Error(w, "update installation is not configured", http.StatusNotImplemented)
return
}
var req chatUpdateRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil || len(req.Snapshot.Available()) == 0 {
http.Error(w, "the displayed update snapshot is required", http.StatusBadRequest)
return
}
fresh, err := chat.Updates.Check(r.Context(), 0)
if err != nil {
a.failUpdateCheck(r.Context(), w, err)
return
}
if !releaseupdate.SameAvailable(fresh, req.Snapshot) {
http.Error(w, "available releases changed; check again", http.StatusConflict)
return
}
chat.updateMu.Lock()
if chat.updateInProgress {
chat.updateMu.Unlock()
http.Error(w, "an update is already in progress", http.StatusConflict)
return
}
chat.updateInProgress = true
chat.updateMu.Unlock()
defer func() {
chat.updateMu.Lock()
chat.updateInProgress = false
chat.updateMu.Unlock()
}()
progress := make([]string, 0, 4)
meta := releaseupdate.InstallMeta{Channel: "webui", ReportPath: a.updateReportPath}
result, err := chat.Updates.Install(r.Context(), fresh, meta, func(message string) { progress = append(progress, message) })
if err != nil {
a.failChat(r.Context(), w, http.StatusBadGateway, err)
return
}
writeJSON(w, map[string]any{"ok": true, "progress": progress, "result": result})
}
func newChatSourceID() string {
id, err := uuid.NewV7()
if err != nil {
return "web-" + uuid.NewString()
}
return "web-" + id.String()
}
// The server supplies the person thread; browser-supplied conversation IDs
// cannot select another person's history.
func chatUser(ctx context.Context) string {
if value, ok := ActingIdentity(ctx); ok {
return string(value.ID)
}
return ""
}
func (a *chatAPI) ownsChatSession(ctx context.Context, session messaging.SessionContext) bool {
return session.Source.Platform == "web" && session.Source.ThreadID == chatUser(ctx)
}