feat: implement error handling for agent events

Author: 35C4n0r

chat/src/app/layout.tsx

@@ -29,7 +29,7 @@ export default function RootLayout({
           disableTransitionOnChange
         >
           {children}
-          <Toaster richColors />
+          <Toaster richColors closeButton />
         </ThemeProvider>
       </body>
     </html>

chat/src/components/chat-provider.tsx

@@ -36,6 +36,12 @@ interface StatusChangeEvent {
   agent_type: string;
 }
 
+interface ErrorEventData {
+  message: string;
+  level: string;
+  time: string;
+}
+
 interface APIErrorDetail {
   location: string;
   message: string;
@@ -215,6 +221,25 @@ export function ChatProvider({ children }: PropsWithChildren) {
         setAgentType(data.agent_type === "" ? "unknown" : data.agent_type as AgentType);
       });
 
+      // Handle agent error events
+      eventSource.addEventListener("agent_error", (event) => {
+        const messageEvent = event as MessageEvent;
+        try {
+          const data: ErrorEventData = JSON.parse(messageEvent.data);
+
+          // Display error as toast notification that persists until manually dismissed
+          if (data.level === "error") {
+            toast.error(data.message, { duration: Infinity });
+          } else if (data.level === "warning") {
+            toast.warning(data.message, { duration: Infinity });
+          } else {
+            toast.info(data.message, { duration: Infinity });
+          }
+        } catch (e) {
+          console.error("Failed to parse agent_error event data:", e);
+        }
+      });
+
       // Handle connection open (server is online)
       eventSource.onopen = () => {
         // Connection is established, but we'll wait for status_change event

lib/httpapi/events.go

@@ -18,6 +18,7 @@ const (
 	EventTypeMessageUpdate EventType = "message_update"
 	EventTypeStatusChange  EventType = "status_change"
 	EventTypeScreenUpdate  EventType = "screen_update"
+	EventTypeError         EventType = "agent_error"
 )
 
 type AgentStatus string
@@ -52,6 +53,12 @@ type ScreenUpdateBody struct {
 	Screen string `json:"screen"`
 }
 
+type ErrorBody struct {
+	Message string    `json:"message" doc:"Error message"`
+	Level   string    `json:"level" doc:"Error level: 'warning' or 'error'"`
+	Time    time.Time `json:"time" doc:"Timestamp when the error occurred"`
+}
+
 type Event struct {
 	Type    EventType
 	Payload any
@@ -66,6 +73,7 @@ type EventEmitter struct {
 	chanIdx             int
 	subscriptionBufSize uint
 	screen              string
+	errors              []ErrorBody
 }
 
 func convertStatus(status st.ConversationStatus) AgentStatus {
@@ -194,6 +202,22 @@ func (e *EventEmitter) EmitScreen(newScreen string) {
 	e.screen = newScreen
 }
 
+func (e *EventEmitter) EmitError(message string, level string) {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+
+	errorBody := ErrorBody{
+		Message: message,
+		Level:   level,
+		Time:    time.Now(),
+	}
+
+	// Store the error so new subscribers can receive all errors
+	e.errors = append(e.errors, errorBody)
+
+	e.notifyChannels(EventTypeError, errorBody)
+}
+
 // Assumes the caller holds the lock.
 func (e *EventEmitter) currentStateAsEvents() []Event {
 	events := make([]Event, 0, len(e.messages)+2)
@@ -211,6 +235,15 @@ func (e *EventEmitter) currentStateAsEvents() []Event {
 		Type:    EventTypeScreenUpdate,
 		Payload: ScreenUpdateBody{Screen: strings.TrimRight(e.screen, mf.WhiteSpaceChars)},
 	})
+
+	// Include all error events
+	for _, err := range e.errors {
+		events = append(events, Event{
+			Type:    EventTypeError,
+			Payload: err,
+		})
+	}
+
 	return events
 }
 

lib/httpapi/server.go

@@ -396,6 +396,7 @@ func (s *Server) registerRoutes() {
 		// Mapping of event type name to Go struct for that event.
 		"message_update": MessageUpdateBody{},
 		"status_change":  StatusChangeBody{},
+		"agent_error":    ErrorBody{},
 	}, s.subscribeEvents)
 
 	sse.Register(s.api, huma.Operation{

lib/screentracker/conversation.go

@@ -80,6 +80,7 @@ type Emitter interface {
 	EmitMessages([]ConversationMessage)
 	EmitStatus(ConversationStatus)
 	EmitScreen(string)
+	EmitError(message string, level string)
 }
 
 type ConversationMessage struct {

lib/screentracker/pty_conversation.go

@@ -125,8 +125,8 @@ type PTYConversation struct {
 	firstStableSnapshot string
 	// userSentMessageAfterLoadState tracks if the user has sent their first message after we load the state
 	userSentMessageAfterLoadState bool
-	// loadStateSuccessful indicates whether conversation state was successfully restored from file.
-	loadStateSuccessful bool
+	// loadStateAttempted indicates whether we have attempted to load conversation state from file (regardless of success).
+	loadStateAttempted bool
 	// initialPromptReady is set to true when ReadyForInitialPrompt returns true.
 	// Checked inline in the snapshot loop on each tick.
 	initialPromptReady bool
@@ -141,6 +141,7 @@ type noopEmitter struct{}
 func (noopEmitter) EmitMessages([]ConversationMessage) {}
 func (noopEmitter) EmitStatus(ConversationStatus)      {}
 func (noopEmitter) EmitScreen(string)                  {}
+func (noopEmitter) EmitError(_ string, _ string)       {}
 
 func NewPTY(ctx context.Context, cfg PTYConversationConfig, emitter Emitter) *PTYConversation {
 	if cfg.Clock == nil {
@@ -168,7 +169,7 @@ func NewPTY(ctx context.Context, cfg PTYConversationConfig, emitter Emitter) *PT
 		dirty:                         false,
 		firstStableSnapshot:           "",
 		userSentMessageAfterLoadState: false,
-		loadStateSuccessful:           false,
+		loadStateAttempted:            false,
 	}
 	if c.cfg.ReadyForInitialPrompt == nil {
 		c.cfg.ReadyForInitialPrompt = func(string) bool { return true }
@@ -192,11 +193,13 @@ func (c *PTYConversation) Start(ctx context.Context) {
 			c.initialPromptReady = true
 		}
 
-		if c.initialPromptReady && !c.loadStateSuccessful && c.cfg.StatePersistenceConfig.LoadState {
+		var loadStateErr error
+		if c.initialPromptReady && !c.loadStateAttempted && c.cfg.StatePersistenceConfig.LoadState {
 			if err := c.loadStateLocked(); err != nil {
 				c.cfg.Logger.Error("Failed to load state", "error", err)
+				loadStateErr = err
 			}
-			c.loadStateSuccessful = true
+			c.loadStateAttempted = true
 		}
 
 		// Enqueue initial prompt once after agent is ready (and after state is potentially loaded)
@@ -219,6 +222,9 @@ func (c *PTYConversation) Start(ctx context.Context) {
 		c.emitter.EmitStatus(status)
 		c.emitter.EmitMessages(messages)
 		c.emitter.EmitScreen(screen)
+		if loadStateErr != nil {
+			c.emitter.EmitError(fmt.Sprintf("Failed to restore previous session: %v", loadStateErr), "warning")
+		}
 		return nil
 	}, "snapshot")
 
@@ -282,7 +288,7 @@ func (c *PTYConversation) updateLastAgentMessageLocked(screen string, timestamp
 	if c.cfg.FormatMessage != nil {
 		agentMessage = c.cfg.FormatMessage(agentMessage, lastUserMessage.Message)
 	}
-	if c.loadStateSuccessful {
+	if c.loadStateAttempted {
 		agentMessage = c.adjustScreenAfterStateLoad(agentMessage)
 	}
 	if c.cfg.FormatToolCall != nil {
@@ -601,7 +607,7 @@ func (c *PTYConversation) loadStateLocked() error {
 	stateFile := c.cfg.StatePersistenceConfig.StateFile
 	loadState := c.cfg.StatePersistenceConfig.LoadState
 
-	if !loadState || c.loadStateSuccessful {
+	if !loadState || c.loadStateAttempted {
 		return nil
 	}
 
@@ -656,7 +662,7 @@ func (c *PTYConversation) loadStateLocked() error {
 		c.firstStableSnapshot = c.cfg.FormatMessage(strings.TrimSpace(snapshots[len(snapshots)-1].screen), "")
 	}
 
-	c.loadStateSuccessful = true
+	c.loadStateAttempted = true
 	c.dirty = false
 
 	c.cfg.Logger.Info("Successfully loaded state", "path", stateFile, "messages", len(c.messages))

lib/screentracker/pty_conversation_test.go

@@ -56,6 +56,7 @@ type testEmitter struct{}
 func (testEmitter) EmitMessages([]st.ConversationMessage) {}
 func (testEmitter) EmitStatus(st.ConversationStatus)      {}
 func (testEmitter) EmitScreen(string)                     {}
+func (testEmitter) EmitError(_ string, _ string)          {}
 
 // advanceFor is a shorthand for advanceUntil with a time-based condition.
 func advanceFor(ctx context.Context, t *testing.T, mClock *quartz.Mock, total time.Duration) {

openapi.json

@@ -19,6 +19,30 @@
         "title": "ConversationRole",
         "type": "string"
       },
+      "ErrorBody": {
+        "additionalProperties": false,
+        "properties": {
+          "level": {
+            "description": "Error level: 'warning' or 'error'",
+            "type": "string"
+          },
+          "message": {
+            "description": "Error message",
+            "type": "string"
+          },
+          "time": {
+            "description": "Timestamp when the error occurred",
+            "format": "date-time",
+            "type": "string"
+          }
+        },
+        "required": [
+          "level",
+          "message",
+          "time"
+        ],
+        "type": "object"
+      },
       "ErrorDetail": {
         "additionalProperties": false,
         "properties": {
@@ -326,6 +350,32 @@
                   "description": "Each oneOf object in the array represents one possible Server Sent Events (SSE) message, serialized as UTF-8 text according to the SSE specification.",
                   "items": {
                     "oneOf": [
+                      {
+                        "properties": {
+                          "data": {
+                            "$ref": "#/components/schemas/ErrorBody"
+                          },
+                          "event": {
+                            "const": "agent_error",
+                            "description": "The event name.",
+                            "type": "string"
+                          },
+                          "id": {
+                            "description": "The event ID.",
+                            "type": "integer"
+                          },
+                          "retry": {
+                            "description": "The retry time in milliseconds.",
+                            "type": "integer"
+                          }
+                        },
+                        "required": [
+                          "data",
+                          "event"
+                        ],
+                        "title": "Event agent_error",
+                        "type": "object"
+                      },
                       {
                         "properties": {
                           "data": {