feat: Support praxis mode in agentop and the installer

cmd/agentop/cmd_config_migrate.go

@@ -85,13 +85,9 @@ func migrateConfig(path string, stdout io.Writer) (changed bool, err error) {
 		return false, err
 	}
 
-	// Keep the previous file once, under a distinct name so it cannot be confused
-	// with the config itself.
-	bak := path + ".before-agentop-migrate"
-	if _, serr := os.Stat(bak); os.IsNotExist(serr) {
-		if werr := os.WriteFile(bak, raw, 0o600); werr != nil {
-			return false, fmt.Errorf("writing %s: %w", bak, werr)
-		}
+	bak, err := keepPreviousConfig(path, raw)
+	if err != nil {
+		return false, err
 	}
 	if err := replaceConfig(path, updated, nil); err != nil {
 		return false, err
@@ -220,6 +216,18 @@ func loadCandidate(updated string) (cfg *config.Config, loaded bool, err error)
 	return cfg, true, nil
 }
 
+// keepPreviousConfig writes raw to path's .before-agentop-migrate file, unless that
+// file exists. The distinct name keeps it apart from the config itself.
+func keepPreviousConfig(path string, raw []byte) (bak string, err error) {
+	bak = path + ".before-agentop-migrate"
+	if _, serr := os.Stat(bak); os.IsNotExist(serr) {
+		if werr := os.WriteFile(bak, raw, 0o600); werr != nil {
+			return "", fmt.Errorf("writing %s: %w", bak, werr)
+		}
+	}
+	return bak, nil
+}
+
 // replaceConfig swaps updated in for the file at path, through a temp file that
 // must load first — and, when verify is set, pass it. A migration that produces an
 // unparseable config would take the proxy down on next start, so the original
@@ -263,22 +271,50 @@ func replaceConfig(path, updated string, verify func(*config.Config) error) erro
 
 // insertListenerKeys adds keys to the listener block, matching whatever
 // indentation the file already uses.
+func insertListenerKeys(src string, pins []pinnedListener) (string, error) {
+	return insertBlockKeys(src, "listener", pins)
+}
+
+// topLevelKey returns the index of the first top-level line that starts with head,
+// or -1, and the indentation of the document (-1 when it has no key line). Only a
+// top-level key counts: the same name nested in a plugin's config is another block.
+func topLevelKey(lines []string, head string) (at, docIndent int) {
+	docIndent = -1
+	for i, l := range lines {
+		trimmed := strings.TrimSpace(l)
+		if trimmed == "" || strings.HasPrefix(trimmed, "#") || isDocumentMarker(trimmed) {
+			continue
+		}
+		indent := len(l) - len(strings.TrimLeft(l, " "))
+		if docIndent < 0 {
+			docIndent = indent
+		}
+		if indent == docIndent && strings.HasPrefix(trimmed, head) {
+			return i, docIndent
+		}
+	}
+	return -1, docIndent
+}
+
+// isDocumentMarker reports whether trimmed is a "---" document start, a "..."
+// document end or a "%" directive. None of them is a key line.
+func isDocumentMarker(trimmed string) bool {
+	return trimmed == "---" || trimmed == "..." || strings.HasPrefix(trimmed, "--- ") || strings.HasPrefix(trimmed, "%")
+}
+
+// insertBlockKeys adds keys to the block named block, matching whatever
+// indentation the file already uses. A pin with no comment gets no comment line.
 //
 // Indentation is read from the file rather than assumed: a real config turned up
 // with the whole document indented two spaces, which is valid YAML and would have
 // produced a broken file from any hardcoded guess.
-func insertListenerKeys(src string, pins []pinnedListener) (string, error) {
+func insertBlockKeys(src, block string, pins []pinnedListener) (string, error) {
 	lines := strings.Split(src, "\n")
+	head := block + ":"
 
-	listenerAt := -1
-	for i, l := range lines {
-		if strings.HasPrefix(strings.TrimSpace(l), "listener:") && !strings.HasPrefix(strings.TrimSpace(l), "#") {
-			listenerAt = i
-			break
-		}
-	}
+	listenerAt, _ := topLevelKey(lines, head)
 	if listenerAt < 0 {
-		return "", fmt.Errorf("no listener: block found")
+		return "", fmt.Errorf("no %s block found", head)
 	}
 	parentIndent := len(lines[listenerAt]) - len(strings.TrimLeft(lines[listenerAt], " "))
 
@@ -306,9 +342,9 @@ func insertListenerKeys(src string, pins []pinnedListener) (string, error) {
 		// is invalid YAML. That fails closed — the validation before the rename catches
 		// it and the original survives — but the user would see a bare parse error
 		// instead of being told the shape is unsupported.
-		if rest := strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(lines[listenerAt]), "listener:")); rest != "" {
-			return "", fmt.Errorf("listener: is written in flow style (%s); "+
-				"rewrite it as an indented block, or add the keys by hand", rest)
+		if rest := strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(lines[listenerAt]), head)); rest != "" && !strings.HasPrefix(rest, "#") {
+			return "", fmt.Errorf("%s is written in flow style (%s); "+
+				"rewrite it as an indented block, or add the keys by hand", head, rest)
 		}
 		// A genuinely empty block: indent one level in from the parent.
 		childIndent = parentIndent + 2
@@ -323,8 +359,10 @@ func insertListenerKeys(src string, pins []pinnedListener) (string, error) {
 	pad := strings.Repeat(" ", childIndent)
 	add := make([]string, 0, len(pins)*3)
 	for _, pin := range pins {
-		for _, cl := range strings.Split(pin.comment, "\n") {
-			add = append(add, pad+"# "+strings.TrimSpace(cl))
+		if pin.comment != "" {
+			for _, cl := range strings.Split(pin.comment, "\n") {
+				add = append(add, pad+"# "+strings.TrimSpace(cl))
+			}
 		}
 		add = append(add, pad+pin.key+": "+pin.value)
 	}

cmd/agentop/cmd_script.go

@@ -582,6 +582,9 @@ func scriptInstall(args []string, stdout, stderr io.Writer) int {
 		return 2
 	}
 	t, err := loadScriptTarget(cfgPath)
+	if err == nil {
+		err = praxisRefusal(t.cfg, t.path, t.statsURL)
+	}
 	if err != nil {
 		return fail("%v", err)
 	}
@@ -723,6 +726,9 @@ func scriptRemove(args []string, stdout, stderr io.Writer) int {
 		return 2
 	}
 	t, err := loadScriptTarget(cfgPath)
+	if err == nil {
+		err = praxisRefusal(t.cfg, t.path, t.statsURL)
+	}
 	if err != nil {
 		return fail("%v", err)
 	}

cmd/agentop/cmd_server.go

@@ -154,6 +154,19 @@ func serverTarget(configPath string) (cfg *config.Config, path, statsURL string,
 	return cfg, path, statsURL, nil
 }
 
+// serverWriteTarget is serverTarget for an action that changes the router. It
+// refuses in praxis mode, where the change has no effect. A list does not refuse:
+// it shows the file.
+func serverWriteTarget(configPath string) (cfg *config.Config, path, statsURL string, err error) {
+	if cfg, path, statsURL, err = serverTarget(configPath); err == nil {
+		err = praxisRefusal(cfg, path, statsURL)
+	}
+	if err != nil {
+		return nil, "", "", err
+	}
+	return cfg, path, statsURL, nil
+}
+
 // readRouter is the router entry's config, decoded without the plugin's validation
 // so a listing still works on a config the proxy would refuse. present is false
 // when the outbound chain has no router entry.
@@ -212,7 +225,7 @@ func serverList(args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintf(stderr, "agentop server: unexpected argument %q; the action comes first: agentop server <action> [flags]\n", pos[0])
 		return 2
 	}
-	cfg, path, _, err := serverTarget(*cfgPath)
+	cfg, path, statsURL, err := serverTarget(*cfgPath)
 	if err != nil {
 		fmt.Fprintf(stderr, "agentop server: %v\n", err)
 		return 1
@@ -223,6 +236,10 @@ func serverList(args []string, stdout, stderr io.Writer) int {
 		return 1
 	}
 	if len(c.Servers) == 0 {
+		if praxisRefusal(cfg, path, statsURL) != nil {
+			fmt.Fprintln(stdout, "No inference servers yet. Praxis mode is on, so `agentop server add` has no effect.")
+			return 0
+		}
 		fmt.Fprintln(stdout, "No inference servers yet. Add one:")
 		fmt.Fprintln(stdout, "  agentop server add <name> <url>")
 		return 0

cmd/agentop/cmd_server_write.go

@@ -121,7 +121,7 @@ func serverAdd(args []string, stdin io.Reader, stdout, stderr io.Writer) int {
 		return 1
 	}
 
-	cfg, path, statsURL, err := serverTarget(*cfgPath)
+	cfg, path, statsURL, err := serverWriteTarget(*cfgPath)
 	if err != nil {
 		fmt.Fprintf(stderr, "agentop server add: %v\n", err)
 		return 1
@@ -235,7 +235,7 @@ func serverRemove(args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintf(stderr, "agentop server remove: %v\n", err)
 		return 2
 	}
-	cfg, path, statsURL, err := serverTarget(*cfgPath)
+	cfg, path, statsURL, err := serverWriteTarget(*cfgPath)
 	if err != nil {
 		fmt.Fprintf(stderr, "agentop server remove: %v\n", err)
 		return 1
@@ -400,7 +400,7 @@ func serverUse(args []string, stdout, stderr io.Writer) int {
 	// The canonical spelling, so the key this command writes and the messages it
 	// prints name the agent today's requests report, however the user spelled it.
 	*agent = pipeline.CanonicalAgent(*agent)
-	cfg, path, statsURL, err := serverTarget(*cfgPath)
+	cfg, path, statsURL, err := serverWriteTarget(*cfgPath)
 	if err != nil {
 		fmt.Fprintf(stderr, "agentop server use: %v\n", err)
 		return 1
@@ -442,7 +442,7 @@ func serverReset(args []string, stdout, stderr io.Writer) int {
 	// The canonical spelling, for the same reason as use: the check below and the
 	// key the reset removes must name the agent the router routes.
 	*agent = pipeline.CanonicalAgent(*agent)
-	cfg, path, statsURL, err := serverTarget(*cfgPath)
+	cfg, path, statsURL, err := serverWriteTarget(*cfgPath)
 	if err != nil {
 		fmt.Fprintf(stderr, "agentop server reset: %v\n", err)
 		return 1
@@ -569,7 +569,7 @@ func serverMove(args []string, stdout, stderr io.Writer) int {
 		fmt.Fprintf(stderr, "agentop server move: %v\n", err)
 		return 2
 	}
-	cfg, path, statsURL, err := serverTarget(*cfgPath)
+	cfg, path, statsURL, err := serverWriteTarget(*cfgPath)
 	if err != nil {
 		fmt.Fprintf(stderr, "agentop server move: %v\n", err)
 		return 1

cmd/agentop/cmd_service.go

@@ -1207,6 +1207,11 @@ func serviceIsCurrent(goos string, p servicePaths) bool {
 	if goos == "darwin" && !strings.Contains(body, "--supervise") {
 		return false
 	}
+	// On Linux the unit supervises only in praxis mode. A unit that does not agree
+	// with the config file must be written again.
+	if goos == "linux" && strings.Contains(body, "--supervise") != configPraxisEnabled(p.configFile) {
+		return false
+	}
 	if running, _ := supervisorRunning(goos, p); !running {
 		return false
 	}
@@ -1216,6 +1221,13 @@ func serviceIsCurrent(goos string, p servicePaths) bool {
 	return waitHealthy(p.healthURL, 2*time.Second)
 }
 
+// configPraxisEnabled reports whether the config file at path sets praxis.enabled.
+// It is false when the file does not load.
+func configPraxisEnabled(path string) bool {
+	cfg, err := config.Load(path)
+	return err == nil && cfg.PraxisEnabled()
+}
+
 // proxyBinaryUnchanged reports whether the binary on disk is still the one the unit
 // was written for.
 //

cmd/agentop/cmd_service_goos_test.go

@@ -114,6 +114,35 @@ func TestServiceIsCurrent_BothPlatforms(t *testing.T) {
 		}
 	})
 
+	// In praxis mode the systemd unit must supervise. This clause alone makes install
+	// and setup write the unit again after praxis.enabled changes.
+	t.Run("linux: praxis on and a unit without --supervise is not current", func(t *testing.T) {
+		p := currentServiceFixture(t, "linux")
+		if err := os.WriteFile(p.configFile, []byte("praxis:\n  enabled: true\n"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if serviceIsCurrent("linux", p) {
+			t.Error("claimed current for a direct-mode unit under a praxis config")
+		}
+	})
+
+	t.Run("linux: praxis on and a supervising unit is current", func(t *testing.T) {
+		p := currentServiceFixture(t, "linux")
+		if err := os.WriteFile(p.configFile, []byte("praxis:\n  enabled: true\n"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		unit := renderUnitFor("linux", p)
+		if !strings.Contains(unit, "--supervise") {
+			t.Fatal("a supervising systemd unit has no --supervise; this case says nothing")
+		}
+		if err := os.WriteFile(p.unitFile, []byte(unit), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if !serviceIsCurrent("linux", p) {
+			t.Error("not current; every Linux praxis install would reinstall at each run")
+		}
+	})
+
 	// The supervisor clause, driven through each platform's own stub. "Installed but
 	// not running" is the state a bad config leaves, and reporting it as current means
 	// an install that skips the repair.

cmd/agentop/cmd_service_platform.go

@@ -90,8 +90,11 @@ func shQuote(v string) string {
 // KeepAlive stays in the plist for the cases launchd does honour, such as a
 // login-time load; it is no longer what crash recovery depends on.
 //
-// The systemd unit deliberately does NOT use --supervise: Restart=on-failure works
+// In direct mode the systemd unit does NOT use --supervise: Restart=on-failure works
 // there and counts restarts against StartLimit, which a nested supervisor would hide.
+// In praxis mode (praxis.enabled in p.configFile) it uses --supervise, because only
+// the supervisor starts cortex-gateway and writes gateway.token. The unit reads the
+// file itself, so no caller can write a unit that does not agree with it.
 func renderUnitFor(goos string, p servicePaths) string {
 	if goos == "darwin" {
 		// HOME is set explicitly: the config interpolates ${HOME} at load, and an
@@ -148,7 +151,11 @@ func renderUnitFor(goos string, p servicePaths) string {
 	// proxy closes its listeners on SIGTERM rather than draining them (cmd/cortex/main.go)
 	// and is gone in well under a second, so this only ever ends one that hangs — which
 	// systemd's own default would let hold a restart for 90s. There is no supervisor in
-	// between here: KillMode=control-group signals the proxy directly.
+	// between here in direct mode: KillMode=control-group signals the proxy directly.
+	supervise := ""
+	if configPraxisEnabled(p.configFile) {
+		supervise = " --supervise"
+	}
 	return `[Unit]
 Description=Cortex local proxy (cortex)
 Documentation=https://github.com/rossoctl/cortex
@@ -158,7 +165,7 @@ StartLimitBurst=5
 
 [Service]
 Type=simple
-ExecStart=` + shQuote(p.binary) + ` --config ` + shQuote(p.configFile) + `
+ExecStart=` + shQuote(p.binary) + supervise + ` --config ` + shQuote(p.configFile) + `
 Restart=on-failure
 RestartSec=10
 TimeoutStopSec=5

cmd/agentop/cmd_service_test.go

@@ -802,3 +802,69 @@ func TestReportNotAnswering_LeadsWithTheHolder(t *testing.T) {
 		t.Errorf("the holder line is not between those two:\n%s", s)
 	}
 }
+
+// TestRenderUnit_LinuxPraxisSupervises: in praxis mode the supervisor must start the
+// gateway and write gateway.token, so the systemd unit runs cortex --supervise. The
+// unit reads praxis.enabled from the config file: no caller sets it.
+func TestRenderUnit_LinuxPraxisSupervises(t *testing.T) {
+	p := servicePathsFixture(t)
+	if err := os.WriteFile(p.configFile, []byte("praxis:\n  enabled: true\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	u := renderUnitFor("linux", p)
+	want := "ExecStart=" + shQuote(p.binary) + " --supervise --config " + shQuote(p.configFile) + "\n"
+	if !strings.Contains(u, want) {
+		t.Errorf("ExecStart is not %q:\n%s", want, u)
+	}
+}
+
+// TestRenderUnit_LinuxDirectUnchanged: direct mode keeps the unit it had before
+// praxis mode, byte for byte.
+func TestRenderUnit_LinuxDirectUnchanged(t *testing.T) {
+	p := servicePathsFixture(t)
+	want := `[Unit]
+Description=Cortex local proxy (cortex)
+Documentation=https://github.com/rossoctl/cortex
+X-AgentopVersion=` + version + `
+StartLimitIntervalSec=300
+StartLimitBurst=5
+
+[Service]
+Type=simple
+ExecStart=` + shQuote(p.binary) + ` --config ` + shQuote(p.configFile) + `
+Restart=on-failure
+RestartSec=10
+TimeoutStopSec=5
+StandardOutput=append:` + p.logFile + `
+StandardError=append:` + p.logFile + `
+
+[Install]
+WantedBy=default.target
+`
+	if got := renderUnitFor("linux", p); got != want {
+		t.Errorf("direct-mode unit changed:\ngot:\n%s\nwant:\n%s", got, want)
+	}
+}
+
+func TestConfigPraxisEnabled(t *testing.T) {
+	dir := t.TempDir()
+	for _, tc := range []struct {
+		name, body string
+		want       bool
+	}{
+		{"on", "praxis:\n  enabled: true\n", true},
+		{"off", "praxis:\n  enabled: false\n", false},
+		{"broken", "praxis: [\n", false},
+	} {
+		path := filepath.Join(dir, tc.name+".yaml")
+		if err := os.WriteFile(path, []byte(tc.body), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		if got := configPraxisEnabled(path); got != tc.want {
+			t.Errorf("%s: configPraxisEnabled = %v, want %v", tc.name, got, tc.want)
+		}
+	}
+	if configPraxisEnabled(filepath.Join(dir, "missing.yaml")) {
+		t.Error("missing file: configPraxisEnabled = true, want false")
+	}
+}