Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

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.go
index 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.Narrator
var 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, bod
multiReq.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 = fleetNarrator
multiReq.FindingsProvider = findings
diff --git a/internal/api/report_ai_narration_scope_test.go b/internal/api/report_ai_narration_scope_test.go
new file mode 100644
index 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())
+ }
+ })
+ }
+}