package server import ( "context" "errors" "fmt" "log" "strings" "sync" "time" "git.a-wan.net/alan/pipelines/internal/opencode" "git.a-wan.net/alan/pipelines/internal/protocol" ) // The chat room is one session's shared live channel. Many clients attach to it // (the operator's phone, tablet and terminal) and every frame any turn produces // is fanned out to all of them, so each device sees the same conversation // including the other devices' prompts and the turn's streaming output. The room // owns the session's one broker stream and its one prompt queue, so a session is // never read-only for a client and two turns never interleave: a prompt that // arrives while a turn is in flight is queued (bounded) and its client is told so // in the ack. const ( // chatRoomSubscriberBuffer bounds one attached client's pending frames. A // client that falls this far behind is dropped rather than blocking the turn // or the other clients; it re-syncs from history when it reattaches. chatRoomSubscriberBuffer = 64 // chatRoomQueueLimit bounds the prompts one session may hold while a turn is // in flight. A prompt that would exceed it is refused with a visible error // instead of being silently dropped. chatRoomQueueLimit = 8 // chatClientLabelMax bounds the human-readable client label the server stores // and echoes, so a long device name cannot grow a frame without limit. chatClientLabelMax = 48 // chatClientLabelFallback labels a prompt whose sender did not name itself, so // a transcript always has something to attribute the message to. chatClientLabelFallback = "Another device" // chatRoomPendingLimit bounds how many unresolved approval requests one room // retains for replay to a client that attaches after they were raised, so a // long turn cannot grow the replay state without limit. chatRoomPendingLimit = 16 ) // chatSub is one client's attachment to a session's shared stream. Frames reach // it through a dedicated writer goroutine so a slow or broken client never stalls // the turn or the other subscribers; the buffered channel bounds how far behind // it may fall. type chatSub struct { hub *chatHub room *chatRoom clientID string label string ch chan protocol.Message done chan struct{} once sync.Once write func(protocol.Message) error } func (s *chatSub) run() { for { select { case <-s.done: return case msg := <-s.ch: if err := s.write(msg); err != nil { s.close() return } } } } func (s *chatSub) send(msg protocol.Message) { select { case <-s.done: return default: } select { case s.ch <- msg: default: // The client is not draining: drop it rather than block the fan-out. Its // next attach re-syncs from history. s.close() } } // close detaches the subscription and stops its writer goroutine exactly once. func (s *chatSub) close() { s.once.Do(func() { close(s.done) s.hub.detach(s.room.sessionID, s) }) } // chatQueuedPrompt is one prompt waiting for the session's in-flight turn to // finish. acked marks a prompt the handler already acknowledged as queued, so the // turn runner does not send a second (success) acknowledgement for the same // request id; write is kept either way so a later broker failure is still // reported to the client that sent it. type chatQueuedPrompt struct { text string requestID string write func(protocol.Message) error acked bool } type chatObservation struct { done chan struct{} err error // published by closing done; belongs to this attempt, not the next } // chatRoom is one session's shared live channel. Every field is guarded by the // owning chatHub's mutex. type chatRoom struct { sessionID string broker chatBroker ctx context.Context cancel context.CancelFunc subs map[string]*chatSub queue []*chatQueuedPrompt running bool streaming bool // observing is non-nil while one caller is attaching the shared broker // stream. It prevents concurrent subscribers from opening duplicate global // event streams before streaming can be published. observing *chatObservation shellReadback *opencode.ShellSnapshot // buffering holds the turn's frames until the prompting client's ack has been // written, so the ack always precedes the frames it acknowledges. It is set // only while the very first turn subscribes to the firehose. buffering bool buffered []protocol.ChatEventFrame // pending holds the room's unresolved approval requests, in the order they // were raised, replayed to a client that attaches after they were raised. A // request is removed once it is resolved. pending []protocol.ChatPermissionFrame pollerStarted bool wake chan struct{} turnDone chan struct{} } func newChatRoom(base context.Context, sessionID string) *chatRoom { if base == nil { base = context.Background() } roomCtx, cancel := context.WithCancel(base) return &chatRoom{ sessionID: sessionID, ctx: roomCtx, cancel: cancel, subs: map[string]*chatSub{}, wake: make(chan struct{}, 1), } } // roomLocked returns the session's room, creating it (and its turn runner) when // it is the first client to watch the session. Callers must hold h.mu. func (h *chatHub) roomLocked(sessionID string) *chatRoom { if h.rooms == nil { h.rooms = map[string]*chatRoom{} } if room := h.rooms[sessionID]; room != nil { return room } room := newChatRoom(h.baseCtx, sessionID) h.rooms[sessionID] = room go h.runRoom(room) return room } // ensureObserving starts the firehose even for a read-only subscriber, then // reconciles retained shells from the endpoint's authoritative list. A bounded // journal folds concurrent lifecycle events over that snapshot atomically. All // observers share this reconciliation, with no broker I/O under the hub mutex. func (h *chatHub) ensureObserving(room *chatRoom, broker chatBroker) error { if broker == nil { return errors.New("chat is not configured on this server") } h.mu.Lock() if err := room.ctx.Err(); err != nil { h.mu.Unlock() return err } if waiting := room.observing; waiting != nil { h.mu.Unlock() select { case <-waiting.done: return waiting.err case <-room.ctx.Done(): return room.ctx.Err() } } if room.streaming { h.mu.Unlock() return nil } room.observing = &chatObservation{done: make(chan struct{})} waiting := room.observing room.shellReadback = &opencode.ShellSnapshot{} h.mu.Unlock() var observeErr error defer func() { h.mu.Lock() room.shellReadback = nil waiting.err = observeErr room.observing = nil close(waiting.done) h.mu.Unlock() }() if err := h.startStream(room, broker); err != nil { observeErr = err return err } shells, err := broker.Shells(room.ctx, room.sessionID) h.mu.Lock() if room.ctx.Err() != nil || h.rooms[room.sessionID] != room { h.mu.Unlock() observeErr = context.Canceled return observeErr } if err == nil { shells, err = room.shellReadback.Merge(shells) } if err != nil { // The firehose remains useful when its authoritative shell readback is // temporarily unavailable. Do not turn that read failure into a chat // failure (or claim the last retained snapshot is current): clear the // replay cache and tell attached clients that shell visibility is limited. // Preserve events already folded during this read, but clear stale replay. live, mergeErr := room.shellReadback.Merge(nil) if mergeErr == nil { h.replaceShellsLocked(room.sessionID, live) } h.mu.Unlock() // Never log broker bodies/URLs: they may contain credentials or private output. log.Printf("chat shell readback session=%s failed (%T)", room.sessionID, err) h.fanout(room.sessionID, protocol.Message{Type: protocol.Error, Error: "background shell visibility is limited"}, "") return nil } h.replaceShellsLocked(room.sessionID, shells) room.shellReadback = nil h.mu.Unlock() return nil } // attach registers write as one client's subscription to sessionID's stream and // returns it, or the existing subscription when the same connection has already // attached. It is idempotent so a client may prompt and subscribe without // registering twice. func (h *chatHub) attach(sessionID, clientID, label string, broker chatBroker, write func(protocol.Message) error) *chatSub { if sessionID == "" || clientID == "" || write == nil { return nil } h.mu.Lock() room := h.roomLocked(sessionID) if room.broker == nil { room.broker = broker } if sub, ok := room.subs[clientID]; ok { if label != "" { sub.label = label } h.mu.Unlock() return sub } sub := &chatSub{ hub: h, room: room, clientID: clientID, label: label, ch: make(chan protocol.Message, chatRoomSubscriberBuffer), done: make(chan struct{}), write: write, } room.subs[clientID] = sub h.mu.Unlock() go sub.run() return sub } // detach drops one subscription. The room (and its broker stream and queue) is // released once its last client leaves, so a session with no watchers holds no // goroutine. func (h *chatHub) detach(sessionID string, sub *chatSub) { h.mu.Lock() room := h.rooms[sessionID] if room == nil || room.subs[sub.clientID] != sub { h.mu.Unlock() return } delete(room.subs, sub.clientID) if len(room.subs) == 0 { delete(h.rooms, sessionID) room.cancel() // ReleaseShells is a local identity-cache operation (no broker I/O). // Complete it before a reconnect can acquire this session's new room. if releaser, ok := room.broker.(chatShellReleaser); ok { releaser.ReleaseShells(sessionID) } } h.mu.Unlock() } // detachClient drops every chat subscription one connection holds; the read loop // calls it when the connection ends so no subscriber goroutine outlives it. func (h *chatHub) detachClient(clientID string) { if clientID == "" { return } h.mu.Lock() var subs []*chatSub for _, room := range h.rooms { if sub, ok := room.subs[clientID]; ok { subs = append(subs, sub) } } h.mu.Unlock() for _, sub := range subs { sub.close() } } // fanout delivers one frame to every client watching sessionID except the one // named by except (the sender, who already has it locally). func (h *chatHub) fanout(sessionID string, msg protocol.Message, except string) { h.mu.Lock() var targets []*chatSub if room := h.rooms[sessionID]; room != nil { for id, sub := range room.subs { if id == except { continue } targets = append(targets, sub) } } h.mu.Unlock() for _, sub := range targets { sub.send(msg) } } // broadcastUser retains a prompt as a user turn and pushes it live to every other // client watching the session, attributed to the sending client's label. The // sender already has the message locally, so it is excluded to keep its own // transcript from duplicating it. func (h *chatHub) broadcastUser(frame protocol.ChatEventFrame, exceptClientID string) { h.apply(frame) h.fanout(frame.SessionID, protocol.Message{Type: protocol.ChatEvent, ChatEvent: &frame}, exceptClientID) } // emit folds one broker frame into the retained state and fans it out. While the // first turn's ack is still pending the frames are buffered and flushed in order // once it is written. A step-ended frame finishes the turn, letting the queue // advance. func (h *chatHub) emit(frame protocol.ChatEventFrame) { h.emitRoom(nil, frame) } func (h *chatHub) emitRoom(source *chatRoom, frame protocol.ChatEventFrame) { h.mu.Lock() room := h.rooms[frame.SessionID] if source != nil && (source != room || source.ctx.Err() != nil) { h.mu.Unlock() return } h.applyLocked(frame) buffered := false var targets []*chatSub if room != nil { if room.buffering { room.buffered = append(room.buffered, frame) buffered = true } else { for _, sub := range room.subs { targets = append(targets, sub) } } } if room != nil && frame.Kind == protocol.ChatEventStep && frame.Step != nil && frame.Step.Status == protocol.ChatStepEnded { h.finishTurnLocked(room) } // Shell replay and live lifecycle delivery must enqueue in the same order // as folding. Otherwise an exit can overtake an older running replay. if frame.Kind == protocol.ChatEventShell && !buffered { msg := protocol.Message{Type: protocol.ChatEvent, ChatEvent: &frame} var slow []*chatSub for _, sub := range targets { if !enqueueChatLocked(sub, msg) { slow = append(slow, sub) } } h.mu.Unlock() for _, sub := range slow { sub.close() } return } h.mu.Unlock() if buffered { return } msg := protocol.Message{Type: protocol.ChatEvent, ChatEvent: &frame} for _, sub := range targets { sub.send(msg) } } // enqueueChatLocked never blocks or calls detach under the hub mutex. func enqueueChatLocked(sub *chatSub, msg protocol.Message) bool { select { case <-sub.done: return true default: } select { case sub.ch <- msg: return true default: return false } } func (h *chatHub) replayShells(sub *chatSub) { h.mu.Lock() slow := false if h.rooms[sub.room.sessionID] == sub.room && sub.room.subs[sub.clientID] == sub { turn := h.turnLocked(sub.room.sessionID) for _, id := range turn.shellOrder { shell := turn.shells[id] frame := protocol.ChatEventFrame{SessionID: sub.room.sessionID, Kind: protocol.ChatEventShell, Shell: &shell} if !enqueueChatLocked(sub, protocol.Message{Type: protocol.ChatEvent, ChatEvent: &frame}) { slow = true break } } } h.mu.Unlock() if slow { sub.close() } } // replaceShells reconciles a successful authoritative readback. It drops stale // retained entries (including exits missed while disconnected) and upserts the // verified running set without fabricating a lifecycle event for foreign shells. func (h *chatHub) replaceShells(sessionID string, shells []protocol.ChatShell) { h.mu.Lock() defer h.mu.Unlock() h.replaceShellsLocked(sessionID, shells) } func (h *chatHub) replaceShellsLocked(sessionID string, shells []protocol.ChatShell) { turn := h.turnLocked(sessionID) for _, shell := range turn.shells { turn.shrink(len(shell.Command)) } turn.shells = nil turn.shellOrder = nil for i := range shells { turn.applyShell(&shells[i]) } } // finishTurnLocked marks the room's turn finished and releases the turn runner's // wait. Callers must hold h.mu. func (h *chatHub) finishTurnLocked(room *chatRoom) { room.running = false if room.turnDone != nil { close(room.turnDone) room.turnDone = nil } } // turnInFlight reports whether sessionID has a turn in flight, so chat_close // knows whether to stop one through the broker interrupt before it records the // closed state. A room exists only while a client is watching the session, and // running is set by the turn runner for the whole turn (a prompt queued behind a // live turn leaves it set), so an idle or unwatched session reports false and no // interrupt is sent. It is one read under the hub mutex and mutates nothing. func (h *chatHub) turnInFlight(sessionID string) bool { h.mu.Lock() defer h.mu.Unlock() room := h.rooms[sessionID] return room != nil && room.running } // flushBuffered releases the frames held while the ack was pending and delivers // them in order. It is a no-op once the room is no longer buffering. func (h *chatHub) flushBuffered(sessionID string) { h.mu.Lock() room := h.rooms[sessionID] var pending []protocol.ChatEventFrame var targets []*chatSub if room != nil && room.buffering { room.buffering = false pending = room.buffered room.buffered = nil for _, sub := range room.subs { targets = append(targets, sub) } } var slow []*chatSub for i := range pending { frame := pending[i] msg := protocol.Message{Type: protocol.ChatEvent, ChatEvent: &frame} for _, sub := range targets { if !enqueueChatLocked(sub, msg) { slow = append(slow, sub) } } } h.mu.Unlock() for _, sub := range slow { sub.close() } } // submitPrompt accepts one prompt: it starts the turn runner immediately when no // turn is in flight, or queues it (bounded) when one is. It returns whether the // prompt was queued or refused. func (h *chatHub) submitPrompt(sessionID string, p *chatQueuedPrompt) (queued bool, refused bool) { h.mu.Lock() room := h.roomLocked(sessionID) if room.running || len(room.queue) > 0 { if len(room.queue) >= chatRoomQueueLimit { h.mu.Unlock() return false, true } // The client is acknowledged as queued by the handler, so the turn runner // must not acknowledge the same request again once it runs. The write is // still kept so a later broker failure reaches the client that sent it. p.acked = true room.queue = append(room.queue, p) signalWake(room.wake) h.mu.Unlock() return true, false } room.queue = append(room.queue, p) signalWake(room.wake) h.mu.Unlock() return false, false } // pendingFrames returns a copy of the room's unresolved approval requests so a // client that attaches after they were raised can be shown every one of them. It // returns nil when the room holds none. func (h *chatHub) pendingFrames(sessionID string) []protocol.ChatPermissionFrame { h.mu.Lock() defer h.mu.Unlock() room := h.rooms[sessionID] if room == nil || len(room.pending) == 0 { return nil } frames := make([]protocol.ChatPermissionFrame, len(room.pending)) copy(frames, room.pending) return frames } // pushPermission publishes one newly seen pending approval request to every // client watching the session and remembers it (bounded) for a client that // attaches later. A request already seen (or already resolved) is not pushed // again. func (h *chatHub) pushPermission(sessionID string, frame protocol.ChatPermissionFrame) { if frame.RequestID == "" || frame.Resolved { return } if !h.seenPermission(sessionID, frame.RequestID) { return } h.mu.Lock() var targets []*chatSub if room := h.rooms[sessionID]; room != nil { known := false for i := range room.pending { if room.pending[i].RequestID == frame.RequestID { room.pending[i] = frame known = true break } } if !known { room.pending = append(room.pending, frame) if len(room.pending) > chatRoomPendingLimit { room.pending = room.pending[len(room.pending)-chatRoomPendingLimit:] } } for _, sub := range room.subs { targets = append(targets, sub) } } h.mu.Unlock() msg := protocol.Message{Type: protocol.ChatPermission, ChatPermission: &frame} for _, sub := range targets { sub.send(msg) } } // runRoom is the session's turn runner: it takes queued prompts one at a time, // posts each to the broker and waits for the turn to end, so two prompts of one // session can never interleave. func (h *chatHub) runRoom(room *chatRoom) { for { p, done, ok := h.nextPrompt(room) if !ok { return } h.runTurn(room, p, done) } } // nextPrompt pops the next queued prompt, blocking until one arrives or the room // is released. It marks the room running and creates the turn's completion // channel so a stale signal from a previous turn can never end the next one. func (h *chatHub) nextPrompt(room *chatRoom) (*chatQueuedPrompt, chan struct{}, bool) { for { h.mu.Lock() if len(room.queue) > 0 { p := room.queue[0] room.queue = room.queue[1:] room.running = true room.turnDone = make(chan struct{}) done := room.turnDone h.mu.Unlock() return p, done, true } h.mu.Unlock() select { case <-room.ctx.Done(): return nil, nil, false case <-room.wake: } } } // runTurn subscribes to the broker stream when needed, posts one prompt, writes // its ack and waits for the turn to end. func (h *chatHub) runTurn(room *chatRoom, p *chatQueuedPrompt, done chan struct{}) { broker := h.roomBroker(room) first := false h.mu.Lock() if !room.streaming { first = true room.buffering = true } h.mu.Unlock() defer h.flushBuffered(room.sessionID) if broker == nil { h.failPrompt(room, p, errors.New("chat is not configured on this server")) return } if first { if err := h.ensureObserving(room, broker); err != nil { h.failPrompt(room, p, err) h.endRoomTurn(room) return } } if err := broker.Prompt(room.ctx, room.sessionID, p.text); err != nil { h.failPrompt(room, p, err) h.endRoomTurn(room) return } if h.registry != nil { if err := h.registry.TouchOperatorSession(room.ctx, room.sessionID); err != nil { log.Printf("touch operator session %s: %v", room.sessionID, err) } } if p.write != nil && !p.acked { _ = p.write(protocol.Message{Type: protocol.ChatPrompt, ID: p.requestID}) } h.flushBuffered(room.sessionID) // Start the approval poller once, after the first ack, so a pending request // is surfaced after the prompt is acknowledged and shared with every client. h.mu.Lock() startPoller := !room.pollerStarted room.pollerStarted = true h.mu.Unlock() if startPoller { go h.pollRoom(room, broker) } select { case <-done: case <-room.ctx.Done(): } } // endRoomTurn releases the turn slot after a prompt that never entered flight, // so the queue advances immediately instead of waiting for a step that never // comes. func (h *chatHub) endRoomTurn(room *chatRoom) { h.mu.Lock() h.finishTurnLocked(room) h.mu.Unlock() } // failPrompt reports a refused prompt to the client that sent it, so a prompt // that never reached the agent is visible on the device that sent it rather than // leaving its composer waiting. It is reported for a queued prompt too, whose // success ack was already sent but whose delivery may still fail. func (h *chatHub) failPrompt(room *chatRoom, p *chatQueuedPrompt, err error) { if p.write == nil || err == nil { return } _ = p.write(protocol.Message{Type: protocol.Error, ID: p.requestID, Error: err.Error()}) } // roomBroker returns the broker bound to the room. func (h *chatHub) roomBroker(room *chatRoom) chatBroker { h.mu.Lock() defer h.mu.Unlock() return room.broker } // startStream attaches the room to the broker firehose, waiting until the // subscription is ready so no delta emitted between subscribing and posting a // prompt is lost. The permission poller starts alongside it. func (h *chatHub) startStream(room *chatRoom, broker chatBroker) error { attached := make(chan struct{}) var once sync.Once result := make(chan error, 1) ctx := room.ctx go func() { result <- broker.Stream(ctx, room.sessionID, func() { once.Do(func() { close(attached) }) }, func(frame protocol.ChatEventFrame) error { h.emitRoom(room, frame) return nil }) }() select { case <-attached: case err := <-result: if err == nil { err = errors.New("chat stream ended before it was subscribed") } return err case <-ctx.Done(): return ctx.Err() } h.mu.Lock() room.streaming = true h.mu.Unlock() go h.drainStream(room, result) return nil } // drainStream reports the terminal error of a room's subscription and clears the // streaming flag so a later turn re-subscribes; it also releases a turn still // waiting on a stream that ended. func (h *chatHub) drainStream(room *chatRoom, result <-chan error) { err := <-result h.mu.Lock() room.streaming = false h.finishTurnLocked(room) h.mu.Unlock() if err != nil && room.ctx.Err() == nil { log.Printf("chat stream session=%s: %v", room.sessionID, err) } } // pollRoom polls the broker's pending-approval list for the room on a fixed // interval and pushes each newly seen request to every attached client. The // first poll runs immediately; the loop stops with the room's context. func (h *chatHub) pollRoom(room *chatRoom, broker chatBroker) { ticker := time.NewTicker(chatPermissionPollInterval) defer ticker.Stop() reported := false for { if err := h.pollPermissionsOnce(room.ctx, broker, room.sessionID); err != nil { if room.ctx.Err() != nil { return } if errors.Is(err, opencode.ErrPermissionUnsupported) { log.Printf("chat permission poll session=%s: %v", room.sessionID, err) return } if reported { log.Printf("chat permission poll session=%s: %v", room.sessionID, err) } else { reported = true h.fanout(room.sessionID, protocol.Message{Type: protocol.Error, Error: "chat permission poll: " + err.Error()}, "") } } select { case <-room.ctx.Done(): return case <-ticker.C: } } } // pollPermissionsOnce performs one poll and pushes each newly seen request of the // session to every client watching it. func (h *chatHub) pollPermissionsOnce(ctx context.Context, broker chatBroker, sessionID string) error { pending, err := broker.Permissions(ctx, sessionID) if err != nil { return err } for _, request := range pending { if request.SessionID != sessionID || request.RequestID == "" { continue } h.pushPermission(sessionID, request) } return nil } // signalWake nudges a room's turn runner without blocking. The channel is // buffered, so a signal already pending is enough. func signalWake(ch chan struct{}) { select { case ch <- struct{}{}: default: } } // sanitizeChatClientLabel cleans a client-supplied device label for storage and // echo: control characters are dropped, the length is bounded and a blank label // becomes the generic fallback, so a transcript can always attribute a message. func sanitizeChatClientLabel(label string) string { var b strings.Builder for _, r := range label { if r < 0x20 || r == 0x7f { continue } b.WriteRune(r) } out := strings.TrimSpace(b.String()) if len(out) > chatClientLabelMax { out = strings.TrimSpace(out[:chatClientLabelMax]) } if out == "" { return chatClientLabelFallback } return out } // permissionRefusal explains why a second answer to an already-answered request // is refused, naming the client that won so the operator sees what happened. func permissionRefusal(prior *chatResolution, requestID string) string { if prior == nil { return "permission request " + requestID + " is already resolved" } if prior.answered { return fmt.Sprintf("permission request %s was already answered by %s", requestID, prior.client) } return fmt.Sprintf("permission request %s is already being answered by %s", requestID, prior.client) }