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 ":", 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 ":" 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 }