Files
samandCopilot cf6108ad14 feat(chat): conversations belong to their person and act with their access (#2065)
Sessions carry an owner; every chat route serves only the caller's own
conversations (others are 404). Each turn and each approved held action
acts as its owner's principal, checked against the access rules before
judgement, so an operator's chat can't do what the operator can't. Chat is
open to any signed-in person, and the stream sends chat updates only to
the owner.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-20 19:05:20 +11:00

448 lines
14 KiB
Go

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"}
huma.Register(api, httpapi.SignedIn(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)
huma.Register(api, httpapi.SignedIn(huma.Operation{
OperationID: "create-chat-session", Method: http.MethodPost, Path: "/api/chat/sessions",
Summary: "Start a conversation", Tags: tags, DefaultStatus: http.StatusCreated,
}), m.createSession)
huma.Register(api, httpapi.SignedIn(huma.Operation{
OperationID: "rename-chat-session", Method: http.MethodPatch, Path: "/api/chat/sessions/{id}",
Summary: "Rename a conversation", Tags: tags,
}), m.renameSession)
huma.Register(api, httpapi.SignedIn(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)
huma.Register(api, httpapi.SignedIn(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)
huma.Register(api, httpapi.SignedIn(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)
huma.Register(api, httpapi.SignedIn(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)
huma.Register(api, httpapi.SignedIn(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)
huma.Register(api, httpapi.SignedIn(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)
}