feat: improve SSE client reliability and performance

- Add enhanced SSE client wrapper with immediate EOF detection
- Implement adaptive health checks and connection monitoring
- Add debounced config writes with content hash detection
- Reduce log verbosity for Fx events

Author: michiosw

internal/cursor/manager.go

@@ -8,6 +8,7 @@ import (
 	"os/user"
 	"path/filepath"
 	"sync"
+	"time"
 
 	"github.com/co-browser/agent-browser/internal/events"
 	"github.com/co-browser/agent-browser/internal/log"
@@ -18,6 +19,7 @@ const (
 	agentBrowserURL       = "http://localhost:8087/sse" // Default local agent MCP URL
 	cursorConfigDir       = ".cursor"
 	cursorMCPFile         = "mcp.json"
+	debounceDelay         = 2 * time.Second // Debounce delay for config rewrites
 )
 
 // ServerEntry defines the structure for server entries within mcp.json
@@ -32,9 +34,12 @@ type MCPServersConfig struct {
 
 // CursorConfigManager handles reading and writing the Cursor mcp.json file.
 type CursorConfigManager struct {
-	logger   log.Logger
-	filePath string
-	mu       sync.Mutex // Mutex to protect file writes
+	logger        log.Logger
+	filePath      string
+	mu            sync.Mutex // Mutex to protect file writes
+	debounceTimer *time.Timer
+	pendingWrite  bool
+	configHash    string // Used to detect actual changes
 }
 
 // NewCursorConfigManager creates a new manager instance.
@@ -52,11 +57,22 @@ func NewCursorConfigManager(logger log.Logger) (*CursorConfigManager, error) {
 	logger.Info().Str("path", filePath).Msg("Cursor MCP config path determined")
 
 	return &CursorConfigManager{
-		logger:   logger,
-		filePath: filePath,
+		logger:       logger,
+		filePath:     filePath,
+		pendingWrite: false,
 	}, nil
 }
 
+// computeConfigHash generates a simple hash of the config to detect changes
+func (m *CursorConfigManager) computeConfigHash(config *MCPServersConfig) string {
+	data, err := json.Marshal(config)
+	if err != nil {
+		// If we can't hash it, return a random value to force write
+		return fmt.Sprintf("error-%d", time.Now().UnixNano())
+	}
+	return fmt.Sprintf("%x", data)
+}
+
 // readConfig reads and parses the mcp.json file.
 // Returns an empty config if the file doesn't exist.
 func (m *CursorConfigManager) readConfig() (*MCPServersConfig, error) {
@@ -93,9 +109,83 @@ func (m *CursorConfigManager) readConfig() (*MCPServersConfig, error) {
 	return config, nil
 }
 
+// scheduleConfigWrite schedules a config write with debouncing
+func (m *CursorConfigManager) scheduleConfigWrite(config *MCPServersConfig, forceWrite bool) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	// Compute hash to check for changes
+	newHash := m.computeConfigHash(config)
+
+	// Skip if content is unchanged and not forcing write
+	if !forceWrite && newHash == m.configHash && m.configHash != "" {
+		m.logger.Debug().Msg("Config unchanged and no force flag set, skipping write")
+		return
+	}
+
+	// Store updated hash
+	m.configHash = newHash
+
+	// If a timer is already running, stop it
+	if m.debounceTimer != nil {
+		m.debounceTimer.Stop()
+	}
+
+	// Store config for later write
+	finalConfig := *config // Make a copy
+
+	// Set pending flag
+	if !m.pendingWrite {
+		m.pendingWrite = true
+		if forceWrite {
+			m.logger.Debug().Dur("delay", debounceDelay).Msg("Scheduling forced config write (debounced)")
+		} else {
+			m.logger.Debug().Dur("delay", debounceDelay).Msg("Scheduling config write (debounced)")
+		}
+	}
+
+	// Create new timer
+	m.debounceTimer = time.AfterFunc(debounceDelay, func() {
+		m.doConfigWrite(&finalConfig)
+	})
+}
+
+// doConfigWrite performs the actual file write operation
+func (m *CursorConfigManager) doConfigWrite(config *MCPServersConfig) {
+	m.mu.Lock()
+	m.pendingWrite = false
+	m.mu.Unlock()
+
+	m.logger.Info().Msg("Writing Cursor mcp.json after debounce delay")
+
+	// Ensure directory exists
+	dir := filepath.Dir(m.filePath)
+	if err := os.MkdirAll(dir, 0750); err != nil {
+		m.logger.Error().Err(err).Str("dir", dir).Msg("Failed to create directory for mcp.json")
+		return
+	}
+
+	// Marshal with indentation for readability
+	data, err := json.MarshalIndent(config, "", "  ")
+	if err != nil {
+		m.logger.Error().Err(err).Msg("Failed to marshal mcp.json data")
+		return
+	}
+
+	// Write file
+	err = os.WriteFile(m.filePath, data, 0640)
+	if err != nil {
+		m.logger.Error().Err(err).Str("path", m.filePath).Msg("Failed to write mcp.json file")
+		return
+	}
+
+	m.logger.Info().Msg("Successfully wrote Cursor mcp.json file")
+}
+
 // writeConfig writes the configuration back to mcp.json.
 // It ensures the directory exists.
 func (m *CursorConfigManager) writeConfig(config *MCPServersConfig) error {
+	// Only used for immediate writes during startup
 	m.mu.Lock()
 	defer m.mu.Unlock()
 
@@ -117,6 +207,9 @@ func (m *CursorConfigManager) writeConfig(config *MCPServersConfig) error {
 		return fmt.Errorf("failed to write %s: %w", m.filePath, err)
 	}
 
+	// Store hash of written config
+	m.configHash = m.computeConfigHash(config)
+
 	return nil
 }
 
@@ -143,43 +236,51 @@ func (m *CursorConfigManager) EnsureAgentEntry() error {
 		needsWrite = true
 	} else {
 		m.logger.Debug().Str("name", agentBrowserEntryName).Msg("Agent Browser entry already exists and is correct.")
-		// We still rewrite the file to potentially trigger Cursor's refresh mechanism
+		// IMPORTANT: Force rewrite on startup even if content is unchanged
+		// This ensures Cursor activates the connection
 		needsWrite = true
 	}
 
 	if needsWrite {
-		m.logger.Info().Msg("Rewriting Cursor mcp.json file...")
+		// For initial setup, we use immediate write to ensure it's ready ASAP
+		m.logger.Info().Msg("Writing Cursor mcp.json file for startup activation...")
 		err = m.writeConfig(config)
 		if err != nil {
 			return fmt.Errorf("failed to write cursor config after ensuring entry: %w", err)
 		}
-		m.logger.Info().Msg("Successfully rewrote Cursor mcp.json file.")
-	} else {
-		m.logger.Info().Msg("No changes needed, but still rewriting Cursor mcp.json file to trigger refresh.")
-		err = m.writeConfig(config)
-		if err != nil {
-			return fmt.Errorf("failed to rewrite cursor config: %w", err)
-		}
-		m.logger.Info().Msg("Successfully rewrote Cursor mcp.json file.")
+		m.logger.Info().Msg("Successfully wrote Cursor mcp.json file.")
 	}
 	return nil
 }
 
 // HandleLocalToolsRefreshed handles the event indicating local tools may have changed.
-// It triggers a rewrite of the mcp.json file.
+// It triggers a debounced rewrite of the mcp.json file.
 func (m *CursorConfigManager) HandleLocalToolsRefreshed(event events.Event) {
 	_, ok := event.(*events.LocalToolsRefreshedEvent)
 	if !ok {
 		m.logger.Error().Str("eventType", string(event.Type())).Msg("Received event of unexpected type in HandleLocalToolsRefreshed")
 		return
 	}
 
-	m.logger.Info().Msg("Local tools refreshed event received, triggering Cursor mcp.json rewrite.")
+	m.logger.Info().Msg("Local tools refreshed event received, scheduling Cursor mcp.json rewrite.")
 
-	// Reuse EnsureAgentEntry which handles read/check/write logic
-	if err := m.EnsureAgentEntry(); err != nil {
-		m.logger.Error().Err(err).Msg("Error rewriting mcp.json on LocalToolsRefreshed event")
+	// Read current config
+	config, err := m.readConfig()
+	if err != nil {
+		m.logger.Error().Err(err).Msg("Failed to read mcp.json during tools refresh")
+		return
+	}
+
+	// Ensure Agent Browser entry is present
+	entry, exists := config.MCPServers[agentBrowserEntryName]
+	if !exists || entry.URL != agentBrowserURL {
+		m.logger.Info().Msg("Ensuring Agent Browser entry during tools refresh")
+		config.MCPServers[agentBrowserEntryName] = ServerEntry{URL: agentBrowserURL}
 	}
+
+	// Schedule debounced write with force flag because tools have changed
+	// This ensures Cursor picks up tool changes even if mcp.json content hasn't changed
+	m.scheduleConfigWrite(config, true)
 }
 
 // RegisterEventHandlers subscribes the manager to relevant events.