1// Package notify defines domain notification types for agent events.
 2// These types are decoupled from UI concerns so the agent can publish
 3// events without importing UI packages.
 4package notify
 5
 6// Type identifies the kind of agent notification.
 7type Type string
 8
 9const (
10	// TypeAgentFinished indicates the agent has completed its turn.
11	TypeAgentFinished Type = "agent_finished"
12	// TypeReAuthenticate indicates the agent encountered an
13	// authentication error and the user needs to re-authenticate.
14	TypeReAuthenticate Type = "re_authenticate"
15	// TypeAgentError indicates the agent's turn terminated with an
16	// error. The error text is carried in Notification.Message.
17	TypeAgentError Type = "error"
18)
19
20// Notification represents a domain event published by the agent.
21type Notification struct {
22	SessionID    string
23	SessionTitle string
24	Type         Type
25	ProviderID   string
26	// Message carries the error text for TypeAgentError. Other
27	// notification types ignore it.
28	Message string
29}
30
31// RunComplete is the authoritative end-of-run signal for a session.
32// It is published exactly once per top-level agent run (per
33// [sessionAgent.Run] invocation that actually executed) after all
34// message updates for the turn have been flushed via
35// message.Service.FlushAll. Carries the final assistant text and
36// message ID so non-interactive clients can reconcile stdout even if
37// SSE events arrive out of order or are dropped by the broker. Error
38// is non-empty when the run terminated with an error; Cancelled is
39// true when the run terminated due to context cancellation. The two
40// are mutually exclusive in the success case but may overlap when a
41// cancel triggers a downstream error.
42//
43// RunID identifies the specific request that produced this event.
44// It is the value the caller set on `proto.AgentMessage.RunID` (or
45// equivalently propagated via agent.WithRunID on the context that
46// reaches the coordinator); empty when no caller set one. Filtering
47// by RunID lets a client correlate a SendMessage call with its
48// terminal event even when the session is busy and other turns are
49// finishing on the same session.
50type RunComplete struct {
51	SessionID string
52	RunID     string
53	MessageID string
54	Text      string
55	Error     string
56	Cancelled bool
57}