Files
pipelines/internal/protocol/attention_acks.go
T

90 lines
3.6 KiB
Go

package protocol
import (
"fmt"
"regexp"
"sort"
)
// Attention acknowledgements are the operator's in-app "I have seen this"
// state, shared by every connected client so clearing on one device clears
// everywhere. A client reads the whole set with {"type":"attention_acks"} and
// adds to it with
//
// {"type":"ack_attention","attention_acks":{"dismissed":["42:Failed"],"chat_seen":{"ses_x":1730000000000}}}
//
// Both reply with type "attention_acks" carrying the whole stored set. After an
// accepted ack, every other connection receives an unsolicited
// {"type":"attention_acks_changed","attention_acks":{...}} frame holding only
// what that ack changed. The set only grows (dismissals are added, watermarks
// only advance), so applying frames in any order or twice is harmless.
//
// A dismissal identity is "<run id>:<Decision|Failed>", the Needs-you entry
// identity. Clear all is a batch of the identities the client showed, so an
// entry that appears later is never hidden by an earlier clear. A chat_seen
// value is the chat session's updated_at (epoch milliseconds) the operator has
// read up to.
const (
GetAttentionAcks = "attention_acks"
AckAttention = "ack_attention"
AttentionAcksReply = "attention_acks"
AttentionAcksChanged = "attention_acks_changed"
)
// MaxAttentionAckItems bounds the dismissals plus watermarks one ack may carry.
const MaxAttentionAckItems = 500
// AttentionAcks is the wire form of the acknowledgement set (or a delta of it).
type AttentionAcks struct {
Dismissed []string `json:"dismissed"`
ChatSeen map[string]int64 `json:"chat_seen"`
}
var attentionKeyPattern = regexp.MustCompile(`^[1-9][0-9]{0,18}:(Decision|Failed)$`)
// chatSeenIDPattern mirrors the server's chat session id shapes (OpenCode
// ses_…, Codex/Claude UUIDs).
var chatSeenIDPattern = regexp.MustCompile(`^(?:ses_[A-Za-z0-9_]+|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$`)
// ValidAttentionKey reports whether key is a "<run id>:<kind>" identity.
func ValidAttentionKey(key string) bool { return attentionKeyPattern.MatchString(key) }
// ValidateAttentionAck checks one ack request: at least one item, at most
// MaxAttentionAckItems, every dismissal a valid identity, and every watermark a
// valid chat session id with a positive millisecond value. It returns the
// dismissals deduplicated and sorted.
func ValidateAttentionAck(ack *AttentionAcks) (AttentionAcks, error) {
if ack == nil || len(ack.Dismissed)+len(ack.ChatSeen) == 0 {
return AttentionAcks{}, fmt.Errorf("attention_acks must name at least one dismissal or chat_seen watermark")
}
if len(ack.Dismissed)+len(ack.ChatSeen) > MaxAttentionAckItems {
return AttentionAcks{}, fmt.Errorf("attention_acks may carry at most %d items", MaxAttentionAckItems)
}
seen := make(map[string]struct{}, len(ack.Dismissed))
result := AttentionAcks{Dismissed: []string{}, ChatSeen: map[string]int64{}}
for _, key := range ack.Dismissed {
if !ValidAttentionKey(key) {
return AttentionAcks{}, fmt.Errorf("invalid attention identity %q", key)
}
if _, dup := seen[key]; dup {
continue
}
seen[key] = struct{}{}
result.Dismissed = append(result.Dismissed, key)
}
sort.Strings(result.Dismissed)
for id, at := range ack.ChatSeen {
if !chatSeenIDPattern.MatchString(id) {
return AttentionAcks{}, fmt.Errorf("invalid chat session id %q", id)
}
if at <= 0 {
return AttentionAcks{}, fmt.Errorf("chat_seen %q must be a positive epoch-millisecond time", id)
}
result.ChatSeen[id] = at
}
return result, nil
}
// Empty reports whether the set carries nothing.
func (a AttentionAcks) Empty() bool { return len(a.Dismissed) == 0 && len(a.ChatSeen) == 0 }