package chat import ( "context" "errors" "fmt" "net/http" "strconv" "strings" "time" "unicode/utf8" "github.com/danielgtaylor/huma/v2" "github.com/google/uuid" "github.com/samcharles93/archie-core/internal/platform/httpapi" "github.com/samcharles93/archie-core/internal/platform/hub" "github.com/samcharles93/archie-core/modules/chat/internal/store" "github.com/samcharles93/archie-core/modules/governance" ) const ( sessionPage = 100 maxTextRunes = 32000 heartbeat = 15 * time.Second ) // Register adds the chat API. func (m *Module) Register(api huma.API) { tags := []string{"Chat"} httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindChatSession), huma.Operation{ OperationID: "list-chat-sessions", Method: http.MethodGet, Path: "/api/chat/sessions", Summary: "List conversations, most recently active first, with the model that answers", Tags: tags, }, m.listSessions) httpapi.Register(api, httpapi.Authorized(governance.ActionCreate, governance.KindChatSession), huma.Operation{ OperationID: "create-chat-session", Method: http.MethodPost, Path: "/api/chat/sessions", Summary: "Start a conversation", Tags: tags, DefaultStatus: http.StatusCreated, }, m.createSession) httpapi.Register(api, httpapi.Authorized(governance.ActionUpdate, governance.KindChatSession), huma.Operation{ OperationID: "rename-chat-session", Method: http.MethodPatch, Path: "/api/chat/sessions/{id}", Summary: "Rename a conversation", Tags: tags, }, m.renameSession) httpapi.Register(api, httpapi.Authorized(governance.ActionDelete, governance.KindChatSession), huma.Operation{ OperationID: "delete-chat-session", Method: http.MethodDelete, Path: "/api/chat/sessions/{id}", Summary: "Delete a conversation and its turns", Tags: tags, DefaultStatus: http.StatusNoContent, }, m.deleteSession) httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindChatSession), huma.Operation{ OperationID: "list-chat-turns", Method: http.MethodGet, Path: "/api/chat/sessions/{id}/turns", Summary: "List a conversation's turns with what each did", Tags: tags, }, m.listTurns) httpapi.Register(api, httpapi.Authorized(governance.ActionCreate, governance.KindChatSession), huma.Operation{ OperationID: "send-chat-turn", Method: http.MethodPost, Path: "/api/chat/sessions/{id}/turns", Summary: "Send a message; it is stored, then answered after the turns before it", Tags: tags, DefaultStatus: http.StatusAccepted, }, m.sendTurn) httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindChatSession), huma.Operation{ OperationID: "get-chat-turn", Method: http.MethodGet, Path: "/api/chat/turns/{id}", Summary: "Get one turn with what it did", Tags: tags, }, m.getTurn) httpapi.Register(api, httpapi.Authorized(governance.ActionUpdate, governance.KindChatSession), huma.Operation{ OperationID: "cancel-chat-turn", Method: http.MethodPost, Path: "/api/chat/turns/{id}/cancel", Summary: "Stop a turn that is queued or running", Tags: tags, }, m.cancelTurn) httpapi.Register(api, httpapi.Authorized(governance.ActionRead, governance.KindChatSession), huma.Operation{ OperationID: "stream-chat-turn", Method: http.MethodGet, Path: "/api/chat/turns/{id}/events", Summary: "Stream what a turn records, from a cursor, until it ends", Tags: tags, Responses: map[string]*huma.Response{"200": { Description: "Server-sent events, one data frame per recorded event: {\"seq\", \"type\", ...}. " + "Types are reasoning, delta, tool, navigate, approval, action, done, error and cancelled; " + "the stream ends after done, error or cancelled.", Content: map[string]*huma.MediaType{"text/event-stream": {Schema: &huma.Schema{Type: huma.TypeString}}}, }}, }, m.streamTurn) } // Sessions is the conversation list with the model that answers turns. type Sessions struct { Sessions []Session `json:"sessions"` ActiveModel string `json:"active_model"` ModelError string `json:"model_error,omitzero"` } // caller is the identity a request acts as: the owner of the conversations // it may see. A conversation of anyone else is not found. func caller(ctx context.Context) (string, error) { p, ok := governance.PrincipalFromContext(ctx) if !ok || p.IdentityID == "" { return "", huma.NewError(http.StatusUnauthorized, httpapi.ErrUnauthenticated.Error()) } return string(p.IdentityID), nil } func (m *Module) listSessions(ctx context.Context, _ *struct{}) (*httpapi.Reply[Sessions], error) { owner, err := caller(ctx) if err != nil { return nil, err } rows, err := m.store.Sessions(ctx, m.orgID, owner, sessionPage) if err != nil { m.log.ErrorContext(ctx, "list chat sessions", "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't list conversations") } out := Sessions{Sessions: make([]Session, 0, len(rows))} for _, r := range rows { out.Sessions = append(out.Sessions, sessionOf(r)) } if d, ok := m.uses(); ok { if model, err := d.Settings.AgentModelForAlias(ctx, ""); err != nil { out.ModelError = err.Error() } else { out.ActiveModel = model.Model } } return httpapi.OK(out), nil } func (m *Module) createSession(ctx context.Context, _ *struct{}) (*httpapi.Reply[Session], error) { owner, err := caller(ctx) if err != nil { return nil, err } s, err := m.store.CreateSession(ctx, m.orgID, owner, uuid.New()) if err != nil { m.log.ErrorContext(ctx, "create chat session", "error", err) return nil, huma.NewError(http.StatusInternalServerError, "couldn't start a conversation") } return httpapi.OK(sessionOf(s)), nil } type idInput struct { ID string `path:"id" format:"uuid"` } type renameInput struct { ID string `path:"id" format:"uuid"` Body struct { Title string `json:"title" maxLength:"120"` } } func (m *Module) renameSession(ctx context.Context, in *renameInput) (*httpapi.Reply[Session], error) { id, err := uuid.Parse(in.ID) if err != nil { return nil, huma.NewError(http.StatusBadRequest, "id is a conversation id") } owner, err := caller(ctx) if err != nil { return nil, err } if err := m.store.Rename(ctx, m.orgID, owner, id, strings.TrimSpace(in.Body.Title)); err != nil { return nil, m.failed(ctx, err, "rename the conversation") } s, err := m.store.Session(ctx, m.orgID, owner, id) if err != nil { return nil, m.failed(ctx, err, "read the conversation") } return httpapi.OK(sessionOf(s)), nil } func (m *Module) deleteSession(ctx context.Context, in *idInput) (*struct{}, error) { id, err := uuid.Parse(in.ID) if err != nil { return nil, huma.NewError(http.StatusBadRequest, "id is a conversation id") } owner, err := caller(ctx) if err != nil { return nil, err } turns, err := m.store.Turns(ctx, m.orgID, owner, id) if err != nil { return nil, m.failed(ctx, err, "read the conversation") } for _, t := range turns { if !finished(t.State) { return nil, huma.NewError(http.StatusConflict, "stop the conversation's turns before deleting it") } } if err := m.store.DeleteSession(ctx, m.orgID, owner, id); err != nil { return nil, m.failed(ctx, err, "delete the conversation") } return nil, nil } func (m *Module) listTurns(ctx context.Context, in *idInput) (*httpapi.Reply[[]Turn], error) { id, err := uuid.Parse(in.ID) if err != nil { return nil, huma.NewError(http.StatusBadRequest, "id is a conversation id") } owner, err := caller(ctx) if err != nil { return nil, err } if _, err := m.store.Session(ctx, m.orgID, owner, id); err != nil { return nil, m.failed(ctx, err, "read the conversation") } rows, err := m.store.Turns(ctx, m.orgID, owner, id) if err != nil { return nil, m.failed(ctx, err, "list the conversation's turns") } events, err := m.store.EventsOf(ctx, id, []string{kindTool, kindNavigate, kindApproval, kindAction}) if err != nil { return nil, m.failed(ctx, err, "list what the turns did") } byTurn := map[uuid.UUID][]store.Event{} for _, e := range events { byTurn[e.TurnID] = append(byTurn[e.TurnID], e) } out := make([]Turn, 0, len(rows)) for _, r := range rows { out = append(out, turnOf(r, byTurn[r.ID])) } return httpapi.OK(out), nil } func (m *Module) getTurn(ctx context.Context, in *idInput) (*httpapi.Reply[Turn], error) { id, err := uuid.Parse(in.ID) if err != nil { return nil, huma.NewError(http.StatusBadRequest, "id is a turn id") } owner, err := caller(ctx) if err != nil { return nil, err } t, err := m.store.Turn(ctx, m.orgID, owner, id) if err != nil { return nil, m.failed(ctx, err, "read the turn") } events, err := m.store.Events(ctx, id, 0) if err != nil { return nil, m.failed(ctx, err, "read what the turn did") } return httpapi.OK(turnOf(t, events)), nil } // turnOf is a turn with what its recorded events say it did. func turnOf(r store.Turn, events []store.Event) Turn { t := Turn{ ID: r.ID, SessionID: r.SessionID, Seq: r.Seq, State: r.State, Text: r.Text, Page: r.Page, PageLabel: r.PageLabel, Reply: r.Reply, Reasoning: r.Reasoning, Error: r.Error, CreatedAt: r.CreatedAt, Tools: []ToolCall{}, Approvals: []Approval{}, Actions: []ActionDone{}, Navigate: []Navigation{}, } if r.FinishedAt.Valid { t.FinishedAt = &r.FinishedAt.Time } for _, e := range events { var err error switch e.Kind { case kindTool: var v ToolCall if err = decodeData(e.Data, &v); err == nil { t.Tools = append(t.Tools, v) } case kindNavigate: var v Navigation if err = decodeData(e.Data, &v); err == nil { t.Navigate = append(t.Navigate, v) } case kindApproval: var v Approval if err = decodeData(e.Data, &v); err == nil { t.Approvals = append(t.Approvals, v) } case kindAction: var v ActionDone if err = decodeData(e.Data, &v); err == nil { t.Actions = append(t.Actions, v) } } } return t } type sendInput struct { ID string `path:"id" format:"uuid"` Body struct { Text string `json:"text" minLength:"1"` // Page is the dashboard path the operator asked from, and PageLabel // the name the page goes by. Page string `json:"page,omitempty" maxLength:"500"` PageLabel string `json:"page_label,omitempty" maxLength:"200"` } } func (m *Module) sendTurn(ctx context.Context, in *sendInput) (*httpapi.Reply[Turn], error) { id, err := uuid.Parse(in.ID) if err != nil { return nil, huma.NewError(http.StatusBadRequest, "id is a conversation id") } owner, err := caller(ctx) if err != nil { return nil, err } text := strings.TrimSpace(in.Body.Text) switch { case text == "": return nil, huma.NewError(http.StatusBadRequest, "a message needs text") case utf8.RuneCountInString(text) > maxTextRunes: return nil, huma.NewError(http.StatusBadRequest, fmt.Sprintf("a message is at most %d characters", maxTextRunes)) } t, err := m.store.AddTurn(ctx, m.orgID, owner, store.Turn{ ID: uuid.New(), SessionID: id, Text: text, Page: in.Body.Page, PageLabel: in.Body.PageLabel, }) if err != nil { return nil, m.failed(ctx, err, "send the message") } m.poke() return httpapi.OK(turnOf(t, nil)), nil } func (m *Module) cancelTurn(ctx context.Context, in *idInput) (*httpapi.Reply[Turn], error) { id, err := uuid.Parse(in.ID) if err != nil { return nil, huma.NewError(http.StatusBadRequest, "id is a turn id") } owner, err := caller(ctx) if err != nil { return nil, err } wasQueued, err := m.store.RequestCancel(ctx, m.orgID, owner, id) if err != nil { return nil, m.failed(ctx, err, "stop the turn") } if wasQueued { m.record(ctx, id, kindCancelled, map[string]any{"text": ""}) } m.mu.Lock() stop := m.running[id] m.mu.Unlock() if stop != nil { stop() } t, err := m.store.Turn(ctx, m.orgID, owner, id) if err != nil { return nil, m.failed(ctx, err, "read the turn") } return httpapi.OK(turnOf(t, nil)), nil } type streamInput struct { ID string `path:"id" format:"uuid"` After string `query:"after" doc:"Only events after this seq; every event by default"` } // streamTurn replays a turn's recorded events after the cursor, then follows // new ones until the turn ends. A reader that reconnects passes its last seq // and misses nothing. func (m *Module) streamTurn(ctx context.Context, in *streamInput) (*huma.StreamResponse, error) { id, err := uuid.Parse(in.ID) if err != nil { return nil, huma.NewError(http.StatusBadRequest, "id is a turn id") } var after int64 if in.After != "" { if after, err = strconv.ParseInt(in.After, 10, 64); err != nil || after < 0 { return nil, huma.NewError(http.StatusBadRequest, "after is an event seq") } } owner, err := caller(ctx) if err != nil { return nil, err } if _, err := m.store.Turn(ctx, m.orgID, owner, id); err != nil { return nil, m.failed(ctx, err, "read the turn") } return &huma.StreamResponse{Body: func(hc huma.Context) { m.serveEvents(hc, id, after) }}, nil //nolint:contextcheck // a stream takes its context from the response it writes, which ends with the request } // serveEvents streams a turn's events to one reader. func (m *Module) serveEvents(hc huma.Context, id uuid.UUID, after int64) { ctx := hc.Context() w := hc.BodyWriter() flusher, ok := w.(http.Flusher) if !ok { hc.SetStatus(http.StatusInternalServerError) return } notes, stop := m.hub.Subscribe(topic(id)) defer stop() hc.SetHeader("Content-Type", "text/event-stream") hc.SetHeader("Cache-Control", "no-store") hc.SetStatus(http.StatusOK) flusher.Flush() m.follow(ctx, id, after, notes, func(frame string) bool { if _, err := fmt.Fprint(w, frame); err != nil { return false } flusher.Flush() return true }) } // follow writes a turn's events after the cursor until the turn ends, the // reader leaves or a write fails. func (m *Module) follow(ctx context.Context, id uuid.UUID, after int64, notes <-chan hub.Note, write func(string) bool) { tick := time.NewTicker(heartbeat) defer tick.Stop() for { events, err := m.store.Events(ctx, id, after) if err != nil { if ctx.Err() == nil { m.log.ErrorContext(ctx, "read chat events", "turn", id, "error", err) } return } for _, e := range events { after = e.Seq if !write(frame(e)) { return } if e.Kind == kindDone || e.Kind == kindError || e.Kind == kindCancelled { return } } select { case <-ctx.Done(): return case _, ok := <-notes: if !ok { return } case <-tick.C: if !write(": keepalive\n\n") { return } } } } // frame is one event as a server-sent event: its data with its seq and type. func frame(e store.Event) string { data := strings.TrimSpace(string(e.Data)) head := fmt.Sprintf(`{"seq":%d,"type":%q`, e.Seq, e.Kind) if data != "{}" && strings.HasPrefix(data, "{") { head += "," + data[1:] } else { head += "}" } return "id: " + strconv.FormatInt(e.Seq, 10) + "\ndata: " + head + "\n\n" } func (m *Module) failed(ctx context.Context, err error, what string) error { if errors.Is(err, store.ErrNotFound) { return huma.NewError(http.StatusNotFound, "not found") } m.log.ErrorContext(ctx, "chat: "+what, "error", err) return huma.NewError(http.StatusInternalServerError, "couldn't "+what) }