90 lines
3.6 KiB
Go
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 }
|