feat: AgentField Desktop (Mac-first) + Windows enablement, bundled CLI, tray, deep links

control-plane/cmd/af-tray/shared.go

@@ -100,6 +100,36 @@ func uiPageURL(page string) string {
 	return fmt.Sprintf("http://localhost:%d/ui/%s", serverPort(), page)
 }
 
+// ---- Desktop app deep links --------------------------------------------------
+//
+// The AgentField desktop app (desktop/ in this repo) registers the
+// agentfield:// URL scheme. When it is installed, the tray opens views there;
+// when it is not, `open agentfield://…` fails fast (no handler registered)
+// and the tray falls back to the web UI in the browser (see openPage in
+// tray_darwin.go).
+
+// deepLinkForPage maps a web-UI page name to the desktop-app view showing the
+// same thing. Unknown/empty pages land on the app's dashboard.
+func deepLinkForPage(page string) string {
+	switch page {
+	case "agents":
+		return "agentfield://agents"
+	case "executions":
+		return "agentfield://activity"
+	default:
+		return "agentfield://dashboard"
+	}
+}
+
+// browserURLForPage is the web-UI fallback for the same page: the server root
+// for the default page, /ui/<page> otherwise.
+func browserURLForPage(page string) string {
+	if page == "" {
+		return dashboardURL()
+	}
+	return uiPageURL(page)
+}
+
 // checkHealth reports whether the given URL answers HTTP 200 within a short
 // timeout. The control plane's /health endpoint returns 200 when healthy and
 // 503 when not, so only a 200 counts as "running".

control-plane/cmd/af-tray/shared_test.go

@@ -54,6 +54,36 @@ func TestURLsUsePort(t *testing.T) {
 	}
 }
 
+// Contract: every page the tray can open has a desktop-app deep link, and
+// unknown/empty pages land on the app's dashboard instead of failing. The
+// scheme must stay "agentfield" — it is what the desktop app registers.
+func TestDeepLinkForPage(t *testing.T) {
+	cases := map[string]string{
+		"":           "agentfield://dashboard",
+		"dashboard":  "agentfield://dashboard",
+		"agents":     "agentfield://agents",
+		"executions": "agentfield://activity",
+		"whatever":   "agentfield://dashboard",
+	}
+	for page, want := range cases {
+		if got := deepLinkForPage(page); got != want {
+			t.Errorf("deepLinkForPage(%q) = %q, want %q", page, got, want)
+		}
+	}
+}
+
+// Contract: the browser fallback opens the server root for the default page
+// and the embedded web UI for named pages, on the resolved port.
+func TestBrowserURLForPage(t *testing.T) {
+	t.Setenv("AGENTFIELD_PORT", "1234")
+	if got, want := browserURLForPage(""), "http://localhost:1234"; got != want {
+		t.Errorf("browserURLForPage(\"\") = %q, want %q", got, want)
+	}
+	if got, want := browserURLForPage("agents"), "http://localhost:1234/ui/agents"; got != want {
+		t.Errorf("browserURLForPage(\"agents\") = %q, want %q", got, want)
+	}
+}
+
 // Contract: a server is "running" only when /health answers HTTP 200; a 503
 // (unhealthy) or an unreachable server both read as not running.
 func TestCheckHealth(t *testing.T) {

control-plane/cmd/af-tray/tray_darwin.go

@@ -249,15 +249,15 @@ func onReady() {
 			case <-mOpen.ClickedCh:
 				openDashboard()
 			case <-mMore.ClickedCh:
-				openURL(uiPageURL("agents"))
+				openPage("agents")
 			case <-mAgentsOpen.ClickedCh:
-				openURL(uiPageURL("agents"))
+				openPage("agents")
 			case <-mSuccess.ClickedCh:
-				openURL(uiPageURL("executions"))
+				openPage("executions")
 			case <-mResponse.ClickedCh:
-				openURL(uiPageURL("executions"))
+				openPage("executions")
 			case <-mMemory.ClickedCh:
-				openURL(uiPageURL("dashboard"))
+				openPage("dashboard")
 			case <-mEnterKey.ClickedCh:
 				handleEnterAPIKey()
 				refresh()
@@ -339,14 +339,18 @@ func notify(title, body string) {
 	_ = exec.Command("osascript", "-e", script).Start()
 }
 
-func openDashboard() {
-	_ = exec.Command("open", dashboardURL()).Start()
-}
+func openDashboard() { openPage("") }
 
-// openURL opens an arbitrary URL in the default browser (used for dashboard
-// deep-links from the metric rows).
-func openURL(u string) {
-	_ = exec.Command("open", u).Start()
+// openPage opens a view, preferring the AgentField desktop app over the
+// browser: `open agentfield://…` succeeds only when something has registered
+// the scheme (the desktop app does on install) and fails fast when nothing
+// has — in which case the same page opens as web UI in the default browser.
+// Run (not Start) on the deep link because the fallback needs its exit code.
+func openPage(page string) {
+	if exec.Command("open", deepLinkForPage(page)).Run() == nil {
+		return
+	}
+	_ = exec.Command("open", browserURLForPage(page)).Start()
 }
 
 func openLogs() {

control-plane/cmd/af/main.go

@@ -338,6 +338,14 @@ func loadConfig(configFile string) (*config.Config, error) {
 	// Set default storage mode to local if not specified
 	if cfg.Storage.Mode == "" {
 		cfg.Storage.Mode = "local"
+	}
+	// Default the local storage paths whenever they are unset — not only when
+	// the mode was defaulted. A config file may set mode: "local" while leaving
+	// the paths empty (the sample config/agentfield.yaml does exactly that,
+	// and it is picked up automatically when af runs next to it), which
+	// previously skipped this block and failed startup with "database path is
+	// empty". Mirrors cmd/agentfield-server.
+	if cfg.Storage.Mode == "local" {
 		// Use the universal path management system
 		if cfg.Storage.Local.DatabasePath == "" {
 			dbPath, err := utils.GetDatabasePath()

control-plane/internal/cli/logs.go

@@ -4,8 +4,10 @@ import (
 	"errors"
 	"fmt"
 	"os"
-	"os/exec" // Added missing import
+	"os/exec"
 	"path/filepath"
+	"runtime"
+	"strings"
 
 	"github.com/Agent-Field/agentfield/control-plane/internal/logger"
 	"github.com/Agent-Field/agentfield/control-plane/internal/packages"
@@ -104,16 +106,48 @@ func (lv *LogViewer) ViewLogs(agentNodeName string) error {
 
 // tailLogs shows the last N lines of the log file
 func (lv *LogViewer) tailLogs(logFile string, lines int) error {
-	cmd := exec.Command("tail", "-n", fmt.Sprintf("%d", lines), logFile)
+	cmd := tailCommand(logFile, lines, false)
 	cmd.Stdout = os.Stdout
 	cmd.Stderr = os.Stderr
 	return cmd.Run()
 }
 
 // followLogs follows the log file in real-time
 func (lv *LogViewer) followLogs(logFile string) error {
-	cmd := exec.Command("tail", "-f", logFile)
+	cmd := tailCommand(logFile, 10, true)
 	cmd.Stdout = os.Stdout
 	cmd.Stderr = os.Stderr
 	return cmd.Run()
 }
+
+// tailCommand builds the platform command that prints the last n lines of a
+// file, optionally following it.
+func tailCommand(logFile string, n int, follow bool) *exec.Cmd {
+	program, args := tailCommandArgs(runtime.GOOS, logFile, n, follow)
+	return exec.Command(program, args...)
+}
+
+// tailCommandArgs returns the program and arguments that tail a log file on
+// the given GOOS. Unix uses tail(1); Windows has no tail, so PowerShell's
+// Get-Content stands in (compile-verified only, not yet tested on a real
+// Windows machine). Pure so both platform branches are unit-testable anywhere.
+func tailCommandArgs(goos, logFile string, n int, follow bool) (string, []string) {
+	if goos == "windows" {
+		script := fmt.Sprintf("Get-Content -LiteralPath %s -Tail %d", psSingleQuote(logFile), n)
+		if follow {
+			script += " -Wait"
+		}
+		return "powershell", []string{"-NoProfile", "-Command", script}
+	}
+	args := []string{"-n", fmt.Sprintf("%d", n)}
+	if follow {
+		args = append(args, "-f")
+	}
+	return "tail", append(args, logFile)
+}
+
+// psSingleQuote quotes s as a PowerShell single-quoted string literal, where
+// the only escape is doubling embedded single quotes.
+func psSingleQuote(s string) string {
+	return "'" + strings.ReplaceAll(s, "'", "''") + "'"
+}