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
Require ai:execute for AI narration of reports by token
rcourtman0ade9410360d
diff --git a/internal/api/metrics_reporting_handlers.go b/internal/api/metrics_reporting_handlers.goindex 50fe43c009..844edae67a 100644--- a/internal/api/metrics_reporting_handlers.go+++ b/internal/api/metrics_reporting_handlers.go@@ -22,6 +22,7 @@ import ("github.com/rcourtman/pulse-go-rewrite/internal/recovery"recoverymanager "github.com/rcourtman/pulse-go-rewrite/internal/recovery/manager""github.com/rcourtman/pulse-go-rewrite/internal/unifiedresources"+ internalauth "github.com/rcourtman/pulse-go-rewrite/pkg/auth""github.com/rcourtman/pulse-go-rewrite/pkg/diskinventory""github.com/rcourtman/pulse-go-rewrite/pkg/reporting""github.com/rs/zerolog/log"@@ -592,6 +593,34 @@ func singleReportRequestFromQuery(q url.Values) singleReportRequestBody {// Assistant settings.const reportGETNarrativeNote = "Tip: This report was requested with GET, which never uses Pulse Assistant. Generate it from Settings, or request it with POST, to include AI narration when Pulse Assistant is configured."+// reportScopeNarrativeNote replaces the "Configure Pulse Assistant" tip on a+// POST report requested with an API token that may not spend AI budget.+const reportScopeNarrativeNote = "Tip: This report was requested with an API token that does not hold the ai:execute scope, so Pulse Assistant was not used. Use a token with ai:execute, or generate the report from Settings, to include AI narration when Pulse Assistant is configured."++// reportCallerMayUseAI reports whether the caller of a report request may+// spend the tenant's AI budget on narration. Narration is a paid provider call+// recorded in the cost ledger, so an API token needs ai:execute for it, as+// every other AI-spending route does; settings:read is not enough. Callers that+// are not tokens (browser sessions, scheduled reports) are unaffected.+func reportCallerMayUseAI(ctx context.Context) bool {+ record, ok := internalauth.GetAPIToken(ctx).(*config.APITokenRecord)+ if !ok || record == nil {+ return true+ }+ return record.HasScope(config.ScopeAIExecute)+}++// scopeLimitedReportNarrator narrates reports requested by a token without+// ai:execute with the deterministic summary and never calls an AI provider.+type scopeLimitedReportNarrator struct{}++func (scopeLimitedReportNarrator) Narrate(ctx context.Context, in reporting.NarrativeInput) (reporting.Narrative, error) {+ out, err := reporting.HeuristicNarrator{}.Narrate(ctx, in)+ out.Source = reporting.NarrativeSourceHeuristic+ out.Disclaimer = reportScopeNarrativeNote+ return out, err+}+// getReportNarrator narrates GET single-resource reports with the// deterministic summary and never calls an AI provider.type getReportNarrator struct{}@@ -714,10 +743,14 @@ func (h *ReportingHandlers) HandleGenerateReport(w http.ResponseWriter, r *http.// from an AI service that is already running.var narrator reporting.Narratorvar findings reporting.FindingsProvider- if r.Method == http.MethodPost {+ switch {+ case r.Method == http.MethodPost && reportCallerMayUseAI(r.Context()):narrator, _, findings = h.resolveNarrator(r.Context())req.Narrator = narrator- } else {+ case r.Method == http.MethodPost:+ findings = h.resolveExistingFindings(r.Context())+ req.Narrator = scopeLimitedReportNarrator{}+ default:findings = h.resolveExistingFindings(r.Context())req.Narrator = getReportNarrator{}}@@ -1192,7 +1225,14 @@ func (h *ReportingHandlers) generateMultiReportFromBody(ctx context.Context, bodmultiReq.Resources = append(multiReq.Resources, req)}- _, fleetNarrator, findings := h.resolveNarrator(ctx)+ var fleetNarrator reporting.FleetNarrator+ var findings reporting.FindingsProvider+ if reportCallerMayUseAI(ctx) {+ _, fleetNarrator, findings = h.resolveNarrator(ctx)+ } else {+ // A nil fleet narrator falls back to the deterministic summary.+ findings = h.resolveExistingFindings(ctx)+ }multiReq.FleetNarrator = fleetNarratormultiReq.FindingsProvider = findingsdiff --git a/internal/api/report_ai_narration_scope_test.go b/internal/api/report_ai_narration_scope_test.gonew file mode 100644index 0000000000..fcaf60a289--- /dev/null+++ b/internal/api/report_ai_narration_scope_test.go@@ -0,0 +1,151 @@+package api++import (+ "context"+ "net/http"+ "net/http/httptest"+ "strings"+ "sync/atomic"+ "testing"++ "github.com/rcourtman/pulse-go-rewrite/internal/config"+ "github.com/rcourtman/pulse-go-rewrite/pkg/metrics"+ "github.com/rcourtman/pulse-go-rewrite/pkg/reporting"+)++// Report narration through Pulse Assistant is a paid provider call recorded in+// the cost ledger. Reports are readable with settings:read, so an API token+// must also hold ai:execute to spend that budget, as on every other AI route.+// Browser sessions keep working as before.+func reportCaller(t *testing.T, scopes []string) *config.APITokenRecord {+ t.Helper()+ if scopes == nil {+ return nil+ }+ record, err := config.NewAPITokenRecord("report-narration-token.12345678", "report-caller", scopes)+ if err != nil {+ t.Fatalf("new token record: %v", err)+ }+ return record+}++var reportNarrationCallers = []struct {+ name string+ scopes []string+ wantAI bool+}{+ {"browser session (no token)", nil, true},+ {"settings:read token", []string{config.ScopeSettingsRead}, false},+ {"settings:read plus monitoring:read token", []string{config.ScopeSettingsRead, config.ScopeMonitoringRead}, false},+ {"settings:read plus ai:execute token", []string{config.ScopeSettingsRead, config.ScopeAIExecute}, true},+ {"full-access token", []string{config.ScopeWildcard}, true},+}++func TestSingleReportAINarrationNeedsAIExecuteForTokens(t *testing.T) {+ for _, tc := range reportNarrationCallers {+ t.Run(tc.name, func(t *testing.T) {+ store, err := metrics.NewStore(metrics.DefaultConfig(t.TempDir()))+ if err != nil {+ t.Fatal(err)+ }+ t.Cleanup(func() { _ = store.Close() })+ engine := &recordingReportEngine{ReportEngine: reporting.NewReportEngine(reporting.EngineConfig{MetricsStore: store})}+ original := reporting.GetEngine()+ reporting.SetEngine(engine)+ t.Cleanup(func() { reporting.SetEngine(original) })++ narrator := &countingReportNarrator{}+ var narratorResolves, findingsResolves atomic.Int32+ handler := NewReportingHandlers(nil, nil)+ handler.SetNarratorResolver(func(context.Context) (reporting.Narrator, reporting.FleetNarrator, reporting.FindingsProvider) {+ narratorResolves.Add(1)+ return narrator, nil, nil+ })+ handler.SetExistingFindingsResolver(func(context.Context) reporting.FindingsProvider {+ findingsResolves.Add(1)+ return nil+ })++ req := httptest.NewRequest(http.MethodPost, "/api/admin/reports/generate",+ strings.NewReader(`{"format":"pdf","resourceType":"node","resourceId":"node-1"}`))+ if caller := reportCaller(t, tc.scopes); caller != nil {+ attachAPITokenRecord(req, caller)+ }+ rec := httptest.NewRecorder()+ handler.HandleGenerateReport(rec, req)+ if rec.Code != http.StatusOK || rec.Header().Get("Content-Type") != "application/pdf" {+ t.Fatalf("status %d, content type %q, body=%s", rec.Code, rec.Header().Get("Content-Type"), rec.Body.String())+ }++ if tc.wantAI {+ if narrator.calls.Load() != 1 || narratorResolves.Load() != 1 {+ t.Fatalf("AI narration calls=%d resolves=%d, want 1 and 1", narrator.calls.Load(), narratorResolves.Load())+ }+ return+ }+ if narrator.calls.Load() != 0 || narratorResolves.Load() != 0 {+ t.Fatalf("a caller without ai:execute spent AI budget: calls=%d resolves=%d", narrator.calls.Load(), narratorResolves.Load())+ }+ if findingsResolves.Load() != 1 {+ t.Fatalf("existing Patrol findings lookups = %d, want 1", findingsResolves.Load())+ }+ narrative, err := engine.NarrativeFor(engine.requests[len(engine.requests)-1])+ if err != nil {+ t.Fatalf("narrative: %v", err)+ }+ if narrative.Source != reporting.NarrativeSourceHeuristic || narrative.Disclaimer != reportScopeNarrativeNote {+ t.Fatalf("narrative = source %q disclaimer %q, want the deterministic summary with the scope note", narrative.Source, narrative.Disclaimer)+ }+ })+ }+}++type stubFleetNarrator struct{}++func (stubFleetNarrator) NarrateFleet(context.Context, reporting.FleetNarrativeInput) (reporting.FleetNarrative, error) {+ return reporting.FleetNarrative{}, nil+}++func TestFleetReportAINarrationNeedsAIExecuteForTokens(t *testing.T) {+ for _, tc := range reportNarrationCallers {+ t.Run(tc.name, func(t *testing.T) {+ engine := &stubReportingEngine{data: []byte("report"), contentType: "application/pdf"}+ original := reporting.GetEngine()+ reporting.SetEngine(engine)+ t.Cleanup(func() { reporting.SetEngine(original) })++ var narratorResolves, findingsResolves atomic.Int32+ handler := NewReportingHandlers(nil, nil)+ handler.SetNarratorResolver(func(context.Context) (reporting.Narrator, reporting.FleetNarrator, reporting.FindingsProvider) {+ narratorResolves.Add(1)+ return nil, stubFleetNarrator{}, nil+ })+ handler.SetExistingFindingsResolver(func(context.Context) reporting.FindingsProvider {+ findingsResolves.Add(1)+ return nil+ })++ req := httptest.NewRequest(http.MethodPost, "/api/admin/reports/generate-multi",+ strings.NewReader(`{"resources":[{"resourceType":"vm","resourceId":"vm-1"}],"format":"pdf"}`))+ if caller := reportCaller(t, tc.scopes); caller != nil {+ attachAPITokenRecord(req, caller)+ }+ rec := httptest.NewRecorder()+ handler.HandleGenerateMultiReport(rec, req)+ if rec.Code != http.StatusOK {+ t.Fatalf("status %d, body=%s", rec.Code, rec.Body.String())+ }++ gotAI := engine.lastMulti.FleetNarrator != nil+ if gotAI != tc.wantAI {+ t.Fatalf("fleet narrator passed to the engine = %v, want %v", gotAI, tc.wantAI)+ }+ if tc.wantAI && narratorResolves.Load() != 1 {+ t.Fatalf("AI service resolves = %d, want 1", narratorResolves.Load())+ }+ if !tc.wantAI && (narratorResolves.Load() != 0 || findingsResolves.Load() != 1) {+ t.Fatalf("a caller without ai:execute resolved the AI service %d times and looked up existing findings %d times, want 0 and 1", narratorResolves.Load(), findingsResolves.Load())+ }+ })+ }+}