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	// RunID, when non-empty, is the caller-supplied correlator
27	// (proto.AgentMessage.RunID) for the run that produced this
28	// notification. It lets observers attribute a TypeAgentError to a
29	// specific request rather than to any in-flight run on the
30	// session. Empty when no caller set one.
31	RunID string
32	// Message carries the error text for TypeAgentError. Other
33	// notification types ignore it.
34	Message string
35}
36
37// RunComplete is the authoritative end-of-run signal for a session.
38// It is published exactly once per top-level agent run (per
39// [sessionAgent.Run] invocation that actually executed) after all
40// message updates for the turn have been flushed via
41// message.Service.FlushAll. Carries the final assistant text and
42// message ID so non-interactive clients can reconcile stdout even if
43// SSE events arrive out of order or are dropped by the broker. Error
44// is non-empty when the run terminated with an error; Cancelled is
45// true when the run terminated due to context cancellation. The two
46// are mutually exclusive in the success case but may overlap when a
47// cancel triggers a downstream error.
48//
49// RunID identifies the specific request that produced this event.
50// It is the value the caller set on `proto.AgentMessage.RunID` (or
51// equivalently propagated via agent.WithRunID on the context that
52// reaches the coordinator); empty when no caller set one. Filtering
53// by RunID lets a client correlate a SendMessage call with its
54// terminal event even when the session is busy and other turns are
55// finishing on the same session.
56type RunComplete struct {
57	SessionID string
58	RunID     string
59	MessageID string
60	Text      string
61	Error     string
62	Cancelled bool
63}