feat: reload development agents from config changes

Author: piotrlaczkowski

cmd/golanggraph/cli_test.go

@@ -791,14 +791,65 @@ func TestDev_ValidatesAndAppliesTheLogLevel(t *testing.T) {
 	assert.Contains(t, err.Error(), "invalid log level")
 }
 
-func TestDev_SaysHotReloadIsNotImplemented(t *testing.T) {
-	// Point at an occupied port so the run stops right after the notice.
-	var out bytes.Buffer
-	_ = runServer(context.Background(), &out, serverOptions{
-		Host: "127.0.0.1", Port: occupiedPort(t), Dev: true, HotReload: true,
+func TestDev_HotReloadRequiresAgentConfig(t *testing.T) {
+	err := runServer(context.Background(), &bytes.Buffer{}, serverOptions{
+		Host: "127.0.0.1", Port: freePort(t), Dev: true, HotReload: true,
 	})
 
-	assert.Contains(t, out.String(), "hot-reload is not implemented")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "requires --agent-config")
+}
+
+func TestDev_HotReloadReplacesConfiguredAgents(t *testing.T) {
+	path := writeTestFile(t, t.TempDir(), "agent.yaml", "id: initial\n"+validAgentYAML)
+	port := freePort(t)
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	var out bytes.Buffer
+	errCh := make(chan error, 1)
+	go func() {
+		errCh <- runServer(ctx, &out, serverOptions{
+			Host: "127.0.0.1", Port: port, Dev: true, HotReload: true, AgentConfig: path,
+		})
+	}()
+
+	endpoint := fmt.Sprintf("http://127.0.0.1:%d/api/v1/agents", port)
+	waitForAgentIDs(t, endpoint, "initial")
+
+	replacement := "id: replacement\n" + validAgentYAML
+	require.NoError(t, os.WriteFile(path, []byte(replacement), 0o600))
+	waitForAgentIDs(t, endpoint, "replacement")
+
+	cancel()
+	require.NoError(t, <-errCh)
+	assert.Contains(t, out.String(), "Reloaded agent configuration")
+}
+
+func waitForAgentIDs(t *testing.T, endpoint string, wanted string) {
+	t.Helper()
+	deadline := time.Now().Add(5 * time.Second)
+	for time.Now().Before(deadline) {
+		response, err := http.Get(endpoint) // #nosec G107 -- local server started by this test.
+		if err == nil {
+			var payload struct {
+				Agents []struct {
+					ID string `json:"id"`
+				} `json:"agents"`
+			}
+			decodeErr := json.NewDecoder(response.Body).Decode(&payload)
+			_ = response.Body.Close()
+			if decodeErr == nil {
+				for _, configured := range payload.Agents {
+					if configured.ID == wanted {
+						return
+					}
+				}
+			}
+		}
+		time.Sleep(25 * time.Millisecond)
+	}
+	t.Fatalf("agent %q did not appear at %s before timeout", wanted, endpoint)
 }
 
 // ---------------------------------------------------------------------------

cmd/golanggraph/main.go

@@ -22,6 +22,7 @@ import (
 	"syscall"
 	"time"
 
+	"github.com/fsnotify/fsnotify"
 	"github.com/sirupsen/logrus"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
@@ -282,9 +283,9 @@ var devCmd = &cobra.Command{
 	Short: "Start a development server",
 	Long: `Start a development server for testing and debugging agents.
 
-Includes an interactive debugging interface and an agent playground. Hot-reload
-is not implemented: --hot-reload only reports that, so restart the server to
-pick up changes.`,
+Includes an interactive debugging interface and an agent playground. With
+--hot-reload and --agent-config, the server atomically replaces configured
+agents whenever that configuration file changes.`,
 	RunE: func(cmd *cobra.Command, args []string) error {
 		ctx, stop := signal.NotifyContext(cmd.Context(), syscall.SIGINT, syscall.SIGTERM)
 		defer stop()
@@ -427,7 +428,7 @@ func init() {
 	devCmd.Flags().StringP("host", "H", "localhost", "Host to bind to")
 	devCmd.Flags().IntP("port", "p", 8080, "Port to bind to")
 	devCmd.Flags().String("agent-config", "", "Agent configuration file")
-	devCmd.Flags().Bool("hot-reload", true, "Enable hot-reload (not implemented)")
+	devCmd.Flags().Bool("hot-reload", false, "Reload --agent-config when its file changes")
 	devCmd.Flags().Bool("debug", true, "Enable the server's development mode (debug interface and playground)")
 	devCmd.Flags().String("log-level", "info", "Log level (debug, info, warn, error)")
 
@@ -530,8 +531,8 @@ type serverOptions struct {
 	// AgentConfig is an optional agent configuration file whose agents are
 	// created on the server before it starts serving.
 	AgentConfig string
-	// HotReload is the dev command's --hot-reload flag. File watching is not
-	// implemented; the flag is reported honestly rather than acted on.
+	// HotReload watches --agent-config and atomically replaces its agents when
+	// its file changes.
 	HotReload bool
 	// LogLevel is applied to the server's logger.
 	LogLevel string
@@ -588,29 +589,35 @@ func runServer(ctx context.Context, out io.Writer, opts serverOptions) error {
 
 	// --agent-config used to be declared and never read. Load it for real.
 	if opts.AgentConfig != "" {
-		configs, err := loadAgentConfigs(opts.AgentConfig)
-		if err != nil {
-			return fmt.Errorf("agent config %s: %w", opts.AgentConfig, err)
-		}
-		for _, cfg := range configs {
-			if _, err := agentManager.CreateAgent(cfg.toAgentConfig()); err != nil {
-				return fmt.Errorf("failed to create agent %s: %w", cfg.Name, err)
-			}
-			_, _ = fmt.Fprintf(out, "Loaded agent %s (%s)\n", cfg.Name, cfg.Type)
+		if err := replaceAgentsFromConfig(out, agentManager, opts.AgentConfig); err != nil {
+			return err
 		}
 	}
 
-	if opts.HotReload {
-		// The previous implementation printed "Hot-reload enabled - watching
-		// for changes..." next to a comment saying the watcher "would go here".
-		_, _ = fmt.Fprintln(out, "Note: hot-reload is not implemented; restart the server to pick up changes")
-	}
-
 	// Fail before announcing success if the address cannot be bound.
 	if err := checkAddressAvailable(opts.Host, opts.Port); err != nil {
 		return err
 	}
 
+	watchCtx, stopWatching := context.WithCancel(ctx)
+	var waitForWatcher func()
+	defer func() {
+		stopWatching()
+		if waitForWatcher != nil {
+			waitForWatcher()
+		}
+	}()
+	if opts.HotReload {
+		if opts.AgentConfig == "" {
+			return fmt.Errorf("--hot-reload requires --agent-config")
+		}
+		wait, err := watchAgentConfig(watchCtx, out, agentManager, opts.AgentConfig)
+		if err != nil {
+			return err
+		}
+		waitForWatcher = wait
+	}
+
 	errCh := make(chan error, 1)
 	go func() { errCh <- srv.Start() }()
 
@@ -643,6 +650,99 @@ func runServer(ctx context.Context, out io.Writer, opts serverOptions) error {
 	return nil
 }
 
+// replaceAgentsFromConfig parses a complete replacement set before atomically
+// swapping it into the manager. It is shared by the initial load and reload
+// path so both reject the same malformed configuration.
+func replaceAgentsFromConfig(out io.Writer, manager *server.AgentManager, configPath string) error {
+	configs, err := loadAgentConfigs(configPath)
+	if err != nil {
+		return fmt.Errorf("agent config %s: %w", configPath, err)
+	}
+
+	agentConfigs := make([]*agent.AgentConfig, 0, len(configs))
+	for _, cfg := range configs {
+		agentConfigs = append(agentConfigs, cfg.toAgentConfig())
+	}
+	if err := manager.ReplaceAgents(agentConfigs); err != nil {
+		return fmt.Errorf("agent config %s: %w", configPath, err)
+	}
+	for _, cfg := range configs {
+		_, _ = fmt.Fprintf(out, "Loaded agent %s (%s)\n", cfg.Name, cfg.Type)
+	}
+	return nil
+}
+
+// watchAgentConfig watches both the configuration file's directory and its
+// filename. Watching the directory is important because editors commonly save
+// by replacing a temporary file, which invalidates a file-only watch.
+func watchAgentConfig(ctx context.Context, out io.Writer, manager *server.AgentManager, configPath string) (func(), error) {
+	absPath, err := filepath.Abs(configPath)
+	if err != nil {
+		return nil, fmt.Errorf("resolve agent config for hot-reload: %w", err)
+	}
+	absPath = filepath.Clean(absPath)
+
+	watcher, err := fsnotify.NewWatcher()
+	if err != nil {
+		return nil, fmt.Errorf("create hot-reload watcher: %w", err)
+	}
+	if err := watcher.Add(filepath.Dir(absPath)); err != nil {
+		_ = watcher.Close()
+		return nil, fmt.Errorf("watch agent config directory: %w", err)
+	}
+
+	_, _ = fmt.Fprintf(out, "Watching agent config for changes: %s\n", absPath)
+	done := make(chan struct{})
+	go func() {
+		defer close(done)
+		defer func() { _ = watcher.Close() }()
+		var debounce <-chan time.Time
+		var timer *time.Timer
+		for {
+			select {
+			case <-ctx.Done():
+				if timer != nil {
+					timer.Stop()
+				}
+				return
+			case event, ok := <-watcher.Events:
+				if !ok {
+					return
+				}
+				if filepath.Clean(event.Name) != absPath || event.Op&(fsnotify.Write|fsnotify.Create|fsnotify.Rename) == 0 {
+					continue
+				}
+				if timer == nil {
+					timer = time.NewTimer(150 * time.Millisecond)
+					debounce = timer.C
+					continue
+				}
+				if !timer.Stop() {
+					select {
+					case <-timer.C:
+					default:
+					}
+				}
+				timer.Reset(150 * time.Millisecond)
+			case <-debounce:
+				timer = nil
+				debounce = nil
+				if err := replaceAgentsFromConfig(out, manager, absPath); err != nil {
+					_, _ = fmt.Fprintf(out, "Hot-reload failed; keeping existing agents: %v\n", err)
+					continue
+				}
+				_, _ = fmt.Fprintln(out, "Reloaded agent configuration")
+			case err, ok := <-watcher.Errors:
+				if !ok {
+					return
+				}
+				_, _ = fmt.Fprintf(out, "Hot-reload watcher error: %v\n", err)
+			}
+		}
+	}()
+	return func() { <-done }, nil
+}
+
 // checkAddressAvailable reports whether the server can bind host:port. Without
 // this the CLI announced a listening server whose bind had already failed.
 func checkAddressAvailable(host string, port int) error {

go.mod

@@ -3,6 +3,7 @@ module github.com/UnicoLab/GoLangGraph
 go 1.23.0
 
 require (
+	github.com/fsnotify/fsnotify v1.8.0
 	github.com/go-redis/redis/v8 v8.11.5
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/mux v1.8.1
@@ -24,7 +25,6 @@ require (
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
 	github.com/dlclark/regexp2 v1.10.0 // indirect
-	github.com/fsnotify/fsnotify v1.8.0 // indirect
 	github.com/go-viper/mapstructure/v2 v2.3.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/pelletier/go-toml/v2 v2.2.3 // indirect

pkg/server/server.go

@@ -1693,6 +1693,33 @@ func (am *AgentManager) CreateAgent(config *agent.AgentConfig) (agent.Agent, err
 	return agentInstance, nil
 }
 
+// ReplaceAgents atomically replaces the agents managed by am. The replacement
+// is built and validated before the live map is swapped, so a malformed reload
+// leaves the currently serving agents available.
+func (am *AgentManager) ReplaceAgents(configs []*agent.AgentConfig) error {
+	replacement := make(map[string]agent.Agent, len(configs))
+	for _, config := range configs {
+		if config == nil {
+			return fmt.Errorf("agent configuration is nil")
+		}
+		if err := config.Validate(); err != nil {
+			return fmt.Errorf("invalid agent %q: %w", config.ID, err)
+		}
+		if config.ID == "" {
+			return fmt.Errorf("agent %q has an empty id", config.Name)
+		}
+		if _, exists := replacement[config.ID]; exists {
+			return fmt.Errorf("duplicate agent id %q", config.ID)
+		}
+		replacement[config.ID] = agent.NewAgent(config, am.llmManager, am.toolRegistry)
+	}
+
+	am.mu.Lock()
+	am.agents = replacement
+	am.mu.Unlock()
+	return nil
+}
+
 // GetAgent retrieves an agent by ID
 func (am *AgentManager) GetAgent(id string) (agent.Agent, bool) {
 	am.mu.RLock()