Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
package api
import (
"encoding/json"
"io"
"net/http"
"strings"
"sync"
"time"
"github.com/rcourtman/pulse-go-rewrite/internal/agentcapabilities"
"github.com/rcourtman/pulse-go-rewrite/internal/config"
"github.com/rcourtman/pulse-go-rewrite/internal/mock"
"github.com/rs/zerolog/log"
)
func (r *Router) withExternalAgentCapabilityActivity(capabilityName string, handler http.HandlerFunc) http.HandlerFunc {
return func(w http.ResponseWriter, req *http.Request) {
r.recordExternalAgentCapabilityActivity(req, capabilityName)
if !externalAgentHistoryReadCapability(capabilityName) {
handler(w, req)
return
}
rw := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK}
handler(rw, req)
if rw.StatusCode() < http.StatusBadRequest {
r.recordExternalAgentHistoryReadDay(req, capabilityName)
}
}
}
// externalAgentHistoryReadCapability reports the requested history reads the
// event-record review counts: what changed, and how a resource's metrics moved.
func externalAgentHistoryReadCapability(capabilityName string) bool {
switch strings.TrimSpace(capabilityName) {
case agentcapabilities.ListRecentChangesCapabilityName, agentcapabilities.GetMetricHistoryCapabilityName:
return true
default:
return false
}
}
// externalAgentHistoryReadDays remembers the last UTC day each persistence
// recorded a history-read marker, so a busy agent costs one write per day
// rather than one per request. The persistence also dedupes, which covers
// restarts.
var externalAgentHistoryReadDays sync.Map
// recordExternalAgentHistoryReadDay writes the install-level history-read
// marker. It goes to the root persistence, which install telemetry reads,
// whichever organization the request served: the marker is a content-free
// day, not tenant data. Mock-mode reads are demo data, not adoption, and
// would otherwise outlive the switch back to live monitoring.
func (r *Router) recordExternalAgentHistoryReadDay(req *http.Request, capabilityName string) {
if r == nil || req == nil || isFirstPartyBrowserRequest(req) || mock.IsMockEnabled() {
return
}
_, requiredScope, ok := externalAgentCapabilityActivity(capabilityName)
if !ok {
return
}
now := time.Now().UTC()
if !apiTokenCoversExternalAgentSurface(getAPITokenRecordFromRequest(req), now, requiredScope) {
return
}
persistence := r.persistence
if persistence == nil {
return
}
day := now.Format(time.DateOnly)
if last, seen := externalAgentHistoryReadDays.Load(persistence); seen && last == day {
return
}
if err := persistence.RecordExternalAgentActivity(config.ExternalAgentActivityRecord{
Timestamp: now,
Surface: externalAgentActivitySurface(req),
Activity: config.ExternalAgentActivityHistoryRead,
}); err != nil {
log.Debug().Err(err).Msg("Failed to record external agent history read")
return
}
externalAgentHistoryReadDays.Store(persistence, day)
}
func (r *Router) recordExternalAgentCapabilityActivity(req *http.Request, capabilityName string) {
activity, requiredScope, ok := externalAgentCapabilityActivity(capabilityName)
if !ok {
return
}
r.recordExternalAgentActivity(req, activity, requiredScope)
}
func externalAgentActivityForCapability(capabilityName string) (string, bool) {
activity, _, ok := externalAgentCapabilityActivity(capabilityName)
return activity, ok
}
func externalAgentCapabilityActivity(capabilityName string) (string, string, bool) {
capabilityName = strings.TrimSpace(capabilityName)
if capabilityName == "" {
return "", "", false
}
capability, ok := agentcapabilities.FindCapability(agentcapabilities.CanonicalManifest().Capabilities, capabilityName)
if !ok {
return "", "", false
}
var activity string
switch strings.TrimSpace(capabilityName) {
case agentcapabilities.ResourceContextCapabilityName,
agentcapabilities.ListResourceCapabilitiesCapabilityName,
agentcapabilities.GetMetricHistoryCapabilityName:
activity = config.ExternalAgentActivityResourceContext
case agentcapabilities.FleetContextCapabilityName,
agentcapabilities.ListRecentChangesCapabilityName:
activity = config.ExternalAgentActivityFleetContext
case agentcapabilities.OperationsLoopStatusCapabilityName:
activity = config.ExternalAgentActivityFleetContext
case agentcapabilities.EventSubscriptionCapabilityName:
activity = config.ExternalAgentActivityEventStream
case agentcapabilities.ListNodesCapabilityName,
agentcapabilities.AddNodeCapabilityName,
agentcapabilities.UpdateNodeCapabilityName,
agentcapabilities.RemoveNodeCapabilityName,
agentcapabilities.TestNodeCredentialsCapabilityName,
agentcapabilities.TestNodeConnectionCapabilityName,
agentcapabilities.RefreshNodeClusterMembershipCapabilityName,
agentcapabilities.DiscoverLANCapabilityName:
activity = config.ExternalAgentActivityProvisioning
case agentcapabilities.GetOperatorStateCapabilityName,
agentcapabilities.SetOperatorStateCapabilityName,
agentcapabilities.ClearOperatorStateCapabilityName:
activity = config.ExternalAgentActivityOperatorState
case agentcapabilities.ListFindingsCapabilityName:
activity = config.ExternalAgentActivityFindingList
case agentcapabilities.AcknowledgeFindingCapabilityName,
agentcapabilities.SnoozeFindingCapabilityName,
agentcapabilities.DismissFindingCapabilityName,
agentcapabilities.ResolveFindingCapabilityName:
activity = config.ExternalAgentActivityFindingDecision
case agentcapabilities.PlanActionCapabilityName:
activity = config.ExternalAgentActivityActionPlan
case agentcapabilities.DecideActionCapabilityName:
activity = config.ExternalAgentActivityActionDecision
case agentcapabilities.ExecuteActionCapabilityName:
activity = config.ExternalAgentActivityActionExecute
default:
return "", "", false
}
requiredScope := strings.TrimSpace(capability.Scope)
if requiredScope == "" {
return "", "", false
}
return activity, requiredScope, true
}
func (r *Router) recordExternalAgentActivity(req *http.Request, activity string, requiredScopes ...string) {
if r == nil || req == nil || strings.TrimSpace(activity) == "" {
return
}
if isFirstPartyBrowserRequest(req) {
return
}
token := getAPITokenRecordFromRequest(req)
if !apiTokenCoversExternalAgentSurface(token, time.Now().UTC(), requiredScopes...) {
return
}
persistence := r.persistenceForOrg(req.Context())
if persistence == nil {
return
}
if err := persistence.RecordExternalAgentActivity(config.ExternalAgentActivityRecord{
Timestamp: time.Now().UTC(),
Surface: externalAgentActivitySurface(req),
Activity: activity,
}); err != nil {
log.Debug().Err(err).Str("activity", activity).Msg("Failed to record external agent activity")
}
}
type agentWorkflowPromptActivityRequest struct {
Name string `json:"name"`
}
// HandleAgentWorkflowPromptActivity records content-free workflow starter
// usage from agent adapters that render prompts locally, such as pulse-mcp.
func (r *Router) HandleAgentWorkflowPromptActivity(w http.ResponseWriter, req *http.Request) {
if req.Method != http.MethodPost {
http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
return
}
var payload agentWorkflowPromptActivityRequest
dec := json.NewDecoder(http.MaxBytesReader(w, req.Body, 4096))
if err := dec.Decode(&payload); err != nil {
http.Error(w, "Invalid request", http.StatusBadRequest)
return
}
var discard json.RawMessage
if err := dec.Decode(&discard); err != io.EOF {
http.Error(w, "Invalid request", http.StatusBadRequest)
return
}
promptName := strings.TrimSpace(payload.Name)
if !canonicalWorkflowPromptDeclared(promptName) {
http.Error(w, "Unknown workflow prompt", http.StatusBadRequest)
return
}
r.recordWorkflowPromptActivity(req, workflowPromptActivitySurface(req), promptName)
w.WriteHeader(http.StatusNoContent)
}
func canonicalWorkflowPromptDeclared(promptName string) bool {
promptName = strings.TrimSpace(promptName)
if promptName == "" {
return false
}
for _, prompt := range agentcapabilities.ManifestPulseWorkflowPrompts(agentcapabilities.CanonicalManifest()) {
if strings.TrimSpace(prompt.Name) == promptName {
return true
}
}
return false
}
func (r *Router) recordWorkflowPromptActivity(req *http.Request, surface, promptName string) {
if r == nil || req == nil || strings.TrimSpace(promptName) == "" {
return
}
token := getAPITokenRecordFromRequest(req)
if !apiTokenCoversExternalAgentSurface(token, time.Now().UTC(), config.ScopeMonitoringRead) {
return
}
persistence := r.persistenceForOrg(req.Context())
if persistence == nil {
return
}
if err := persistence.RecordWorkflowPromptActivity(config.WorkflowPromptActivityRecord{
Timestamp: time.Now().UTC(),
Surface: surface,
PromptName: promptName,
}); err != nil {
log.Debug().Err(err).Str("prompt_name", promptName).Msg("Failed to record workflow prompt activity")
}
}
func workflowPromptActivitySurface(req *http.Request) string {
if req == nil {
return config.WorkflowPromptActivitySurfaceAgentAPI
}
switch strings.TrimSpace(req.Header.Get(agentcapabilities.AgentSurfaceHeader)) {
case agentcapabilities.AgentSurfacePulseMCP:
return config.WorkflowPromptActivitySurfacePulseMCP
default:
return config.WorkflowPromptActivitySurfaceAgentAPI
}
}
func externalAgentActivitySurface(req *http.Request) string {
if req == nil {
return config.ExternalAgentActivitySurfaceAgentAPI
}
switch strings.TrimSpace(req.Header.Get(agentcapabilities.AgentSurfaceHeader)) {
case agentcapabilities.AgentSurfacePulseMCP:
return config.ExternalAgentActivitySurfacePulseMCP
default:
return config.ExternalAgentActivitySurfaceAgentAPI
}
}
// isFirstPartyBrowserRequest reports whether the request came from a page
// Pulse itself served. The setup wizard leaves the browser authenticated with
// the wildcard admin token, and kiosk links authenticate with ?token=, so the
// Pulse UI's own node and finding fetches would otherwise count as external
// agent use. Browsers set Sec-Fetch-Site and page scripts cannot override it;
// scripts, MCP adapters and dashboards on another origin never send
// same-origin.
func isFirstPartyBrowserRequest(req *http.Request) bool {
return strings.EqualFold(strings.TrimSpace(req.Header.Get("Sec-Fetch-Site")), "same-origin")
}
func apiTokenCoversExternalAgentSurface(token *config.APITokenRecord, now time.Time, requiredScopes ...string) bool {
if token == nil {
return false
}
if token.ExpiresAt != nil && now.After(token.ExpiresAt.UTC()) {
return false
}
if len(requiredScopes) == 0 {
requiredScopes = agentcapabilities.CanonicalManifest().RequiredScopes
}
if len(requiredScopes) == 0 {
return false
}
token = cloneAPITokenRecord(token)
for _, scope := range requiredScopes {
scope = strings.TrimSpace(scope)
if scope == "" {
return false
}
if !token.HasScope(scope) {
return false
}
}
return true
}
func cloneAPITokenRecord(token *config.APITokenRecord) *config.APITokenRecord {
if token == nil {
return nil
}
clone := token.Clone()
return &clone
}