feat(observ): Add observability engine, plugin tool bridge, notifications

cmd/agent/main.go

@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"github.com/flatrun/agent/internal/api"
+	"github.com/flatrun/agent/internal/observ"
 	"github.com/flatrun/agent/internal/watcher"
 	"github.com/flatrun/agent/pkg/config"
 	"github.com/flatrun/agent/pkg/updater"
@@ -106,7 +107,17 @@ func newRootCmd() *cobra.Command {
 		},
 	}
 
-	root.AddCommand(serve, setup, update, versionCmd)
+	observPlugin := &cobra.Command{
+		Use:          "observ-plugin",
+		Short:        "Run the built-in observability plugin (launched by the agent)",
+		Hidden:       true,
+		SilenceUsage: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return observ.RunPlugin()
+		},
+	}
+
+	root.AddCommand(serve, setup, update, versionCmd, observPlugin)
 	return root
 }
 

cmd/observ-plugin/main.go

@@ -0,0 +1,12 @@
+// Command observ-plugin is the FlatRun observability app as a standalone binary. The agent
+// normally runs this logic by re-execing itself; this command allows building the plugin on
+// its own for development or as an external plugin.
+//
+// Build: go build -o plugin ./cmd/observ-plugin
+package main
+
+import "github.com/flatrun/agent/internal/observ"
+
+func main() {
+	_ = observ.RunPlugin()
+}

examples/plugins/hello/main.go

@@ -20,10 +20,25 @@ func main() {
 		_, _ = w.Write([]byte(`{"message":"hello from the flatrun plugin"}`))
 	})
 
+	echo := pluginsdk.Tool{
+		Spec: pluginapi.ToolSpec{
+			Name:        "echo",
+			Description: "Echo back the given text.",
+			Parameters: map[string]any{
+				"type":       "object",
+				"properties": map[string]any{"text": map[string]any{"type": "string"}},
+			},
+		},
+		Run: func(args map[string]any) (string, error) {
+			text, _ := args["text"].(string)
+			return "echo: " + text, nil
+		},
+	}
+
 	_ = pluginsdk.Serve(pluginapi.Info{
 		Name:        "hello",
 		Version:     "0.1.0",
 		DisplayName: "Hello Plugin",
 		Description: "A sample out-of-process plugin.",
-	}, mux)
+	}, mux, echo)
 }

go.mod

@@ -12,7 +12,7 @@ require (
 	github.com/digitalocean/godo v1.171.0
 	github.com/distribution/reference v0.6.0
 	github.com/docker/docker v28.5.2+incompatible
-	github.com/fsnotify/fsnotify v1.9.0
+	github.com/fsnotify/fsnotify v1.10.1
 	github.com/gin-contrib/cors v1.7.6
 	github.com/gin-gonic/gin v1.10.1
 	github.com/go-sql-driver/mysql v1.9.3
@@ -21,12 +21,13 @@ require (
 	github.com/gorilla/websocket v1.5.4-0.20250319132907-e064f32e3674
 	github.com/lib/pq v1.10.9
 	github.com/moby/moby/client v0.2.2
+	github.com/nicholas-fedor/shoutrrr v0.16.1
 	github.com/robfig/cron/v3 v3.0.1
 	github.com/spf13/cobra v1.10.2
 	github.com/testcontainers/testcontainers-go v0.41.0
 	github.com/testcontainers/testcontainers-go/modules/compose v0.41.0
-	golang.org/x/crypto v0.48.0
-	golang.org/x/oauth2 v0.35.0
+	golang.org/x/crypto v0.51.0
+	golang.org/x/oauth2 v0.36.0
 	gopkg.in/yaml.v3 v3.0.1
 	modernc.org/sqlite v1.47.0
 )
@@ -77,6 +78,7 @@ require (
 	github.com/docker/go-units v0.5.0 // indirect
 	github.com/dustin/go-humanize v1.0.1 // indirect
 	github.com/ebitengine/purego v0.10.0 // indirect
+	github.com/eclipse/paho.golang v0.23.0 // indirect
 	github.com/eiannone/keyboard v0.0.0-20220611211555-0d226195f203 // indirect
 	github.com/felixge/httpsnoop v1.0.4 // indirect
 	github.com/fsnotify/fsevents v0.2.0 // indirect
@@ -113,7 +115,8 @@ require (
 	github.com/leodido/go-urn v1.4.0 // indirect
 	github.com/lufia/plan9stats v0.0.0-20211012122336-39d0f177ccd0 // indirect
 	github.com/magiconair/properties v1.8.10 // indirect
-	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mattn/go-colorable v0.1.15 // indirect
+	github.com/mattn/go-isatty v0.0.22 // indirect
 	github.com/mattn/go-runewidth v0.0.16 // indirect
 	github.com/mattn/go-shellwords v1.0.12 // indirect
 	github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect
@@ -138,7 +141,7 @@ require (
 	github.com/opencontainers/go-digest v1.0.0 // indirect
 	github.com/opencontainers/image-spec v1.1.1 // indirect
 	github.com/pelletier/go-toml v1.9.5 // indirect
-	github.com/pelletier/go-toml/v2 v2.2.4 // indirect
+	github.com/pelletier/go-toml/v2 v2.3.1 // indirect
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/planetscale/vtprotobuf v0.6.1-0.20240319094008-0393e58bdf10 // indirect
 	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
@@ -185,11 +188,11 @@ require (
 	go.yaml.in/yaml/v3 v3.0.4 // indirect
 	go.yaml.in/yaml/v4 v4.0.0-rc.4 // indirect
 	golang.org/x/arch v0.18.0 // indirect
-	golang.org/x/net v0.50.0 // indirect
-	golang.org/x/sync v0.19.0 // indirect
-	golang.org/x/sys v0.42.0 // indirect
-	golang.org/x/term v0.40.0 // indirect
-	golang.org/x/text v0.34.0 // indirect
+	golang.org/x/net v0.55.0 // indirect
+	golang.org/x/sync v0.21.0 // indirect
+	golang.org/x/sys v0.46.0 // indirect
+	golang.org/x/term v0.44.0 // indirect
+	golang.org/x/text v0.38.0 // indirect
 	golang.org/x/time v0.14.0 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20260209200024-4cfbd4190f57 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260209200024-4cfbd4190f57 // indirect