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
Count the days external agents read Pulse history
rcourtmanb94d8473ce5a
diff --git a/docs/PRIVACY.md b/docs/PRIVACY.mdindex 800b9ed511..d02191fcf9 100644--- a/docs/PRIVACY.md+++ b/docs/PRIVACY.md@@ -40,7 +40,7 @@ Every field is listed below with the reason it exists. Nothing else is included| Field | Example | Purpose ||-------|---------|---------|-| Schema version | `20` | Identify the exact payload contract so old and new signals are not mixed silently |+| Schema version | `21` | Identify the exact payload contract so old and new signals are not mixed silently || Sent at | `2026-07-23T08:30:00Z` | Date the individual heartbeat without sending a history of client activity || Install ID | `a1b2c3d4-...` | Distinguish active installations within one rotation window without tying telemetry to an account or person || Version | `6.0.0-rc.1` | Track the canonical release identity currently deployed |@@ -252,6 +252,7 @@ Every field is listed below with the reason it exists. Nothing else is included| Pulse Intelligence MCP adapter used 30d | `true`/`false` | See whether the `pulse-mcp` adapter reached a Pulse Intelligence agent/MCP route in the current 30-day telemetry window without sending token identity, route parameters, resource IDs, prompts, or request details || Pulse Intelligence external agent context requests 30d | `8` | Count external-agent/MCP resource-context and fleet-context requests in the current 30-day telemetry window without sending resource IDs, route parameters, or request details || Pulse Intelligence external agent event stream requests 30d | `3` | Count external-agent/MCP event-stream requests in the current 30-day telemetry window without sending event content, route parameters, or request details |+| Pulse Intelligence external agent history read days 30d | `4` | Count the distinct days, 0 to 30, in the current 30-day telemetry window on which an external agent or MCP client successfully read change or metric history, so adoption of those reads can be judged without sending queries, resource IDs, time windows, results, or request counts || Pulse Intelligence external agent provisioning requests 30d | `2` | Count external-agent/MCP provisioning requests in the current 30-day telemetry window without sending discovered resources, credentials, route parameters, or request details || Pulse Intelligence external agent operator state requests 30d | `5` | Count external-agent/MCP operator-state requests in the current 30-day telemetry window without sending state payloads, route parameters, or request details || Pulse Intelligence external agent finding requests 30d | `4` | Count external-agent/MCP finding-list and finding-decision requests in the current 30-day telemetry window without sending finding IDs, finding text, route parameters, or request details |@@ -456,6 +457,7 @@ Every change to the payload bumps the schema version, is listed here with its da| Schema | Date | Change ||--------|------|--------|+| 21 | 2026-10-29 | Content-free count of distinct days on which an external agent or MCP client successfully read change or metric history || 20 | 2026-10-17 | Content-free aggregate report generation, delivery outcomes, source-data states and distinct-period repeat use, with measurement availability and elapsed observation days || 19 | 2026-10-16 | Content-free rolling count of successful metric-history responses that return data older than seven days || 18 | 2026-09-27 | Effective update channel, closed outcome of the last update check on that channel, and whether it offered a newer release |diff --git a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md b/docs/release-control/v6/internal/subsystems/agent-lifecycle.mdindex 73b61b7355..b0c8d1a2a2 100644--- a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md+++ b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md@@ -2752,6 +2752,10 @@ disclosure, install-token scope, or execution authority.Metric history at `/api/agent/metric-history` (`get_metric_history`) is thesame read-only boundary: a resource's recorded metric series for a window,never install, enrollment or command authority.+The schema-v21 history-read usage marker that successful `list_recent_changes`+and `get_metric_history` responses leave is telemetry about agent reads only:+one content-free `history_read` record per UTC day, never evidence of agent+enrollment, a connected host or command use.The `alert.fired`, `alert.resolved` and `resource.status_changed` events on`/api/agent/events` are the push form of the same records and the samediff --git a/docs/release-control/v6/internal/subsystems/api-contracts.md b/docs/release-control/v6/internal/subsystems/api-contracts.mdindex b0a20afa45..a549766f73 100644--- a/docs/release-control/v6/internal/subsystems/api-contracts.md+++ b/docs/release-control/v6/internal/subsystems/api-contracts.md@@ -6830,6 +6830,17 @@ The `cmd/pulse-mcp/README.md` introduction names these monitoring-read agentreads as the place a new MCP user starts; its named tools are pinned to themanifest's MCP surface and scope by`TestContract_PulseMCPReadmeIntroNamesPublishedReadTools`.+After a response below 400 from `list_recent_changes` or `get_metric_history`,+`withExternalAgentCapabilityActivity` also records one content-free+`history_read` day marker (`recordExternalAgentHistoryReadDay`), under the same+token-scope and first-party exclusions as other external-agent activity, never+in mock mode, and at most once per UTC day. It is written to the root+persistence whichever organization the request served, because install+telemetry reads only that history. The per-request activity those routes+already record is unchanged, so existing context counters keep their meaning.+The marker feeds schema-v21 telemetry+`pulse_intelligence_external_agent_history_read_days_30d`, which the+`TelemetryPingPreview` type in `frontend-modern/src/api/settings.ts` declares.`/api/agent/resource-capabilities/{id}` is the agent-consumablestructured capability surface for a single resource: the governeddiff --git a/docs/release-control/v6/internal/subsystems/security-privacy.md b/docs/release-control/v6/internal/subsystems/security-privacy.mdindex 4379701ca2..36fd491625 100644--- a/docs/release-control/v6/internal/subsystems/security-privacy.md+++ b/docs/release-control/v6/internal/subsystems/security-privacy.md@@ -3202,7 +3202,7 @@ carry the schema notice for the first release that includes this field.### Telemetry ingestion matches the released sender while storage stays compatible-The active outbound contract is schema v19. Schema v8 added content-free+The active outbound contract is schema v21. Schema v8 added content-freeapproved-action refusal counters for target change, prerequisite failure, andinvalid typed contract so agent-side pre-mutation failures no longer collapseinto `other`. Schema v9 completes that split with a content-free `uncoded`@@ -3250,6 +3250,21 @@ it. The sender and receiver both force `update_available` false unless theoutcome is `available`. No version, release tag, URL, response, or error textleaves the install, and the receiver canonicalizes both strings to the releasedvocabulary or `unknown`.+Schema v19 adds the rolling count of served metric history responses with data+older than seven days, and schema v20 adds aggregate reporting outcomes and+distinct-period reuse. Schema v21 adds only+`pulse_intelligence_external_agent_history_read_days_30d`: the number of+distinct UTC days, 0 to 30, on which an external agent or MCP client got a+successful response from `list_recent_changes` or `get_metric_history`. It+backs the agent event-record review. Locally it is one content-free+`history_read` marker per UTC day in the external-agent activity history,+written to the root persistence after a 2xx response, never for a request+Pulse's own pages made (`Sec-Fetch-Site: same-origin`) or in mock mode, and kept+outside the 500-record cap so busy agents cannot erase earlier days. Days are+whole UTC dates inside the window, so the partial start date is left out and+the count never exceeds 30. No query, resource ID, time window, result+or request count leaves the install, and the receiver clamps the value to+0 to 30.Patrol run and new-finding volumes use bounded local UTC-day tallies in`internal/config/persistence.go`, preserving aggregate activity after theoperator-facing run history is trimmed. Finding volume has its own persistencediff --git a/docs/release-control/v6/internal/subsystems/storage-recovery.md b/docs/release-control/v6/internal/subsystems/storage-recovery.mdindex d9de2d2914..06e5d9a0bb 100644--- a/docs/release-control/v6/internal/subsystems/storage-recovery.md+++ b/docs/release-control/v6/internal/subsystems/storage-recovery.md@@ -4736,6 +4736,12 @@ persistence either. It resolves a resource's existing `MetricsTarget` and readsthrough the same history path the charts use (the metrics store, then thein-memory and live fallbacks), so its recovery posture is the metrics store's.+The history-read usage marker adds no new store. It is a content-free+`history_read` record in the existing external-agent activity history, at most+one per UTC day, kept outside that history's 500-record cap and bounded by its+90-day retention. Losing the file loses only past markers; telemetry then+reports fewer history-read days until agents read again.+The live `alert.fired`, `alert.resolved` and `resource.status_changed` agentevents add no persistence. They are published in memory after the monitoradapter has recorded the matching `resource_changes` row, and per-resourcediff --git a/frontend-modern/browser-verification/da2e7dd841aaeb9b.json b/frontend-modern/browser-verification/da2e7dd841aaeb9b.jsonnew file mode 100644index 0000000000..05e45f3484--- /dev/null+++ b/frontend-modern/browser-verification/da2e7dd841aaeb9b.json@@ -0,0 +1,38 @@+{+ "version": 1,+ "base_sha": "75e00474f145f107e54026689f977dabc1da70d5",+ "verified_at": "2026-10-29T11:16:07Z",+ "result": "passed",+ "changed_paths": [+ "frontend-modern/src/api/settings.ts"+ ],+ "content_sha256": {+ "frontend-modern/src/api/settings.ts": "a79ea06499e0326e2039b9d97021b7ccee8f23ff80a0fb2fad29706f5a9392b1"+ },+ "routes": [+ "/settings/system-general"+ ],+ "viewports": [+ {+ "width": 1280,+ "height": 800+ },+ {+ "width": 390,+ "height": 844+ }+ ],+ "states": [+ "Signed in to a private mock Pulse built from this tree (schema 21) with outbound telemetry disabled",+ "Telemetry preview before opening: Preview payload button and disabled-telemetry notice",+ "Preview open after one successful list_recent_changes call by a monitoring:read API token and one rejected call (400): payload shows schema_version 21 and pulse_intelligence_external_agent_history_read_days_30d 1",+ "1280x800: preview code block readable, no page-level horizontal overflow",+ "390x844: preview renders under the mobile settings header, page does not overflow horizontally, long payload lines scroll inside the code block"+ ],+ "interactions": [+ "Signed in with the stack's test credentials",+ "Opened Settings > General and scrolled to Usage data and privacy",+ "Clicked Preview payload at 1280x800 and at 390x844 and read the rendered payload",+ "Clicked Copy JSON and saw the 'Telemetry payload copied to clipboard' confirmation"+ ]+}diff --git a/frontend-modern/public/docs/PRIVACY.md b/frontend-modern/public/docs/PRIVACY.mdindex 800b9ed511..d02191fcf9 100644--- a/frontend-modern/public/docs/PRIVACY.md+++ b/frontend-modern/public/docs/PRIVACY.md@@ -40,7 +40,7 @@ Every field is listed below with the reason it exists. Nothing else is included| Field | Example | Purpose ||-------|---------|---------|-| Schema version | `20` | Identify the exact payload contract so old and new signals are not mixed silently |+| Schema version | `21` | Identify the exact payload contract so old and new signals are not mixed silently || Sent at | `2026-07-23T08:30:00Z` | Date the individual heartbeat without sending a history of client activity || Install ID | `a1b2c3d4-...` | Distinguish active installations within one rotation window without tying telemetry to an account or person || Version | `6.0.0-rc.1` | Track the canonical release identity currently deployed |@@ -252,6 +252,7 @@ Every field is listed below with the reason it exists. Nothing else is included| Pulse Intelligence MCP adapter used 30d | `true`/`false` | See whether the `pulse-mcp` adapter reached a Pulse Intelligence agent/MCP route in the current 30-day telemetry window without sending token identity, route parameters, resource IDs, prompts, or request details || Pulse Intelligence external agent context requests 30d | `8` | Count external-agent/MCP resource-context and fleet-context requests in the current 30-day telemetry window without sending resource IDs, route parameters, or request details || Pulse Intelligence external agent event stream requests 30d | `3` | Count external-agent/MCP event-stream requests in the current 30-day telemetry window without sending event content, route parameters, or request details |+| Pulse Intelligence external agent history read days 30d | `4` | Count the distinct days, 0 to 30, in the current 30-day telemetry window on which an external agent or MCP client successfully read change or metric history, so adoption of those reads can be judged without sending queries, resource IDs, time windows, results, or request counts || Pulse Intelligence external agent provisioning requests 30d | `2` | Count external-agent/MCP provisioning requests in the current 30-day telemetry window without sending discovered resources, credentials, route parameters, or request details || Pulse Intelligence external agent operator state requests 30d | `5` | Count external-agent/MCP operator-state requests in the current 30-day telemetry window without sending state payloads, route parameters, or request details || Pulse Intelligence external agent finding requests 30d | `4` | Count external-agent/MCP finding-list and finding-decision requests in the current 30-day telemetry window without sending finding IDs, finding text, route parameters, or request details |@@ -456,6 +457,7 @@ Every change to the payload bumps the schema version, is listed here with its da| Schema | Date | Change ||--------|------|--------|+| 21 | 2026-10-29 | Content-free count of distinct days on which an external agent or MCP client successfully read change or metric history || 20 | 2026-10-17 | Content-free aggregate report generation, delivery outcomes, source-data states and distinct-period repeat use, with measurement availability and elapsed observation days || 19 | 2026-10-16 | Content-free rolling count of successful metric-history responses that return data older than seven days || 18 | 2026-09-27 | Effective update channel, closed outcome of the last update check on that channel, and whether it offered a newer release |diff --git a/frontend-modern/src/api/__tests__/settings.test.ts b/frontend-modern/src/api/__tests__/settings.test.tsindex 4ff3b3a77a..27e6836463 100644--- a/frontend-modern/src/api/__tests__/settings.test.ts+++ b/frontend-modern/src/api/__tests__/settings.test.ts@@ -197,6 +197,7 @@ const mockTelemetryPreviewPayload = {pulse_intelligence_mcp_adapter_used_30d: false,pulse_intelligence_external_agent_context_requests_30d: 0,pulse_intelligence_external_agent_event_stream_requests_30d: 0,+ pulse_intelligence_external_agent_history_read_days_30d: 0,pulse_intelligence_external_agent_provisioning_requests_30d: 0,pulse_intelligence_external_agent_operator_state_requests_30d: 0,pulse_intelligence_external_agent_finding_requests_30d: 0,diff --git a/frontend-modern/src/api/settings.ts b/frontend-modern/src/api/settings.tsindex 200401a414..1ea88c9da7 100644--- a/frontend-modern/src/api/settings.ts+++ b/frontend-modern/src/api/settings.ts@@ -199,6 +199,7 @@ export interface TelemetryPingPreview {pulse_intelligence_mcp_adapter_used_30d: boolean;pulse_intelligence_external_agent_context_requests_30d: number;pulse_intelligence_external_agent_event_stream_requests_30d: number;+ pulse_intelligence_external_agent_history_read_days_30d: number;pulse_intelligence_external_agent_provisioning_requests_30d: number;pulse_intelligence_external_agent_operator_state_requests_30d: number;pulse_intelligence_external_agent_finding_requests_30d: number;diff --git a/frontend-modern/src/components/Settings/__tests__/useSystemSettingsState.test.ts b/frontend-modern/src/components/Settings/__tests__/useSystemSettingsState.test.tsindex 731cc2a1bf..f10a3f91ac 100644--- a/frontend-modern/src/components/Settings/__tests__/useSystemSettingsState.test.ts+++ b/frontend-modern/src/components/Settings/__tests__/useSystemSettingsState.test.ts@@ -203,6 +203,7 @@ const buildTelemetryPreviewPayload = (pulse_intelligence_mcp_adapter_used_30d: false,pulse_intelligence_external_agent_context_requests_30d: 0,pulse_intelligence_external_agent_event_stream_requests_30d: 0,+ pulse_intelligence_external_agent_history_read_days_30d: 0,pulse_intelligence_external_agent_provisioning_requests_30d: 0,pulse_intelligence_external_agent_operator_state_requests_30d: 0,pulse_intelligence_external_agent_finding_requests_30d: 0,diff --git a/internal/api/agent_activity_telemetry.go b/internal/api/agent_activity_telemetry.goindex 4ba0c52713..bae109740d 100644--- a/internal/api/agent_activity_telemetry.go+++ b/internal/api/agent_activity_telemetry.go@@ -5,18 +5,81 @@ import ("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)- handler(w, req)+ 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) {diff --git a/internal/api/agent_activity_telemetry_test.go b/internal/api/agent_activity_telemetry_test.goindex e4a83422da..1f2f612e20 100644--- a/internal/api/agent_activity_telemetry_test.go+++ b/internal/api/agent_activity_telemetry_test.go@@ -1,6 +1,7 @@package apiimport (+ "context""net/http""net/http/httptest""strings"@@ -216,3 +217,82 @@ func TestRecordExternalAgentCapabilityActivityUsesCapabilityClass(t *testing.T)t.Fatalf("operator-state capability activity = %q, want %q", history.Events[0].Activity, config.ExternalAgentActivityOperatorState)}}++// The event-record review counts days on which an agent successfully read+// history, so the marker is written only after a 2xx response, at most once a+// day, never for Pulse's own pages, and never for other capabilities.+func TestHistoryReadDayRecordedOnlyAfterSuccessfulRead(t *testing.T) {+ historyReads := func(t *testing.T, persistence *config.ConfigPersistence) int {+ t.Helper()+ history, err := persistence.LoadExternalAgentActivityHistory()+ if err != nil {+ t.Fatalf("LoadExternalAgentActivityHistory: %v", err)+ }+ count := 0+ for _, event := range history.Events {+ if event.Activity == config.ExternalAgentActivityHistoryRead {+ count+++ }+ }+ return count+ }+ call := func(router *Router, capability string, status int, firstParty bool) {+ handler := router.withExternalAgentCapabilityActivity(capability, func(w http.ResponseWriter, _ *http.Request) {+ w.WriteHeader(status)+ })+ req := httptest.NewRequest(http.MethodGet, "/api/agent/changes", nil)+ attachAPITokenRecord(req, &config.APITokenRecord{Scopes: []string{config.ScopeMonitoringRead}})+ if firstParty {+ req.Header.Set("Sec-Fetch-Site", "same-origin")+ }+ handler(httptest.NewRecorder(), req)+ }++ persistence := config.NewConfigPersistence(t.TempDir())+ router := &Router{persistence: persistence}+ call(router, agentcapabilities.ListRecentChangesCapabilityName, http.StatusBadRequest, false)+ call(router, agentcapabilities.GetMetricHistoryCapabilityName, http.StatusNotFound, false)+ if got := historyReads(t, persistence); got != 0 {+ t.Fatalf("failed reads recorded %d history-read markers", got)+ }+ call(router, agentcapabilities.FleetContextCapabilityName, http.StatusOK, false)+ if got := historyReads(t, persistence); got != 0 {+ t.Fatalf("fleet context recorded %d history-read markers", got)+ }+ call(router, agentcapabilities.ListRecentChangesCapabilityName, http.StatusOK, false)+ call(router, agentcapabilities.GetMetricHistoryCapabilityName, http.StatusOK, false)+ if got := historyReads(t, persistence); got != 1 {+ t.Fatalf("two successful reads on one day recorded %d markers; want 1", got)+ }++ uiPersistence := config.NewConfigPersistence(t.TempDir())+ call(&Router{persistence: uiPersistence}, agentcapabilities.ListRecentChangesCapabilityName, http.StatusOK, true)+ if got := historyReads(t, uiPersistence); got != 0 {+ t.Fatalf("Pulse's own page recorded %d history-read markers", got)+ }+}++// Install telemetry reads only the root persistence, so a history read served+// for another organization must still leave its day marker there.+func TestHistoryReadDayFromAnotherOrganizationReachesInstallTelemetry(t *testing.T) {+ root := config.NewConfigPersistence(t.TempDir())+ router := &Router{persistence: root, multiTenant: config.NewMultiTenantPersistence(t.TempDir())}+ handler := router.withExternalAgentCapabilityActivity(agentcapabilities.ListRecentChangesCapabilityName, func(w http.ResponseWriter, _ *http.Request) {+ w.WriteHeader(http.StatusOK)+ })+ req := httptest.NewRequest(http.MethodGet, "/api/agent/changes", nil)+ req = req.WithContext(context.WithValue(req.Context(), OrgIDContextKey, "acme"))+ attachAPITokenRecord(req, &config.APITokenRecord{Scopes: []string{config.ScopeMonitoringRead}})+ handler(httptest.NewRecorder(), req)++ history, err := root.LoadExternalAgentActivityHistory()+ if err != nil {+ t.Fatalf("LoadExternalAgentActivityHistory: %v", err)+ }+ for _, event := range history.Events {+ if event.Activity == config.ExternalAgentActivityHistoryRead {+ return+ }+ }+ t.Fatalf("history read for organization acme left no marker in root persistence: %+v", history.Events)+}diff --git a/internal/config/ai_usage_persistence_test.go b/internal/config/ai_usage_persistence_test.goindex 6c15a5c155..7b765337b6 100644--- a/internal/config/ai_usage_persistence_test.go+++ b/internal/config/ai_usage_persistence_test.go@@ -175,3 +175,40 @@ func TestRecordWorkflowPromptActivityPrunesAndNormalizes(t *testing.T) {t.Fatalf("recorded event mismatch: %+v", loaded.Events[0])}}++// History-read day markers are one per UTC day and sit outside the record+// cap, so a busy agent's per-request records cannot erase the days it read+// history on.+func TestExternalAgentHistoryReadMarkersAreDailyAndSurviveTheCap(t *testing.T) {+ cp := NewConfigPersistence(t.TempDir())+ // Midday, so the same-day pair below cannot straddle midnight.+ now := time.Now().UTC().Truncate(24 * time.Hour).Add(12 * time.Hour)+ marker := func(at time.Time) ExternalAgentActivityRecord {+ return ExternalAgentActivityRecord{Timestamp: at, Surface: ExternalAgentActivitySurfaceAgentAPI, Activity: ExternalAgentActivityHistoryRead}+ }+ for _, at := range []time.Time{now.Add(-48 * time.Hour), now.Add(-24 * time.Hour), now, now.Add(time.Second)} {+ if err := cp.RecordExternalAgentActivity(marker(at)); err != nil {+ t.Fatalf("RecordExternalAgentActivity: %v", err)+ }+ }+ for i := 0; i < maxExternalAgentActivityHistoryRecords+50; i++ {+ if err := cp.RecordExternalAgentActivity(ExternalAgentActivityRecord{Timestamp: now.Add(time.Duration(i) * time.Millisecond), Surface: ExternalAgentActivitySurfaceAgentAPI, Activity: ExternalAgentActivityFleetContext}); err != nil {+ t.Fatalf("RecordExternalAgentActivity: %v", err)+ }+ }+ loaded, err := cp.LoadExternalAgentActivityHistory()+ if err != nil {+ t.Fatalf("LoadExternalAgentActivityHistory: %v", err)+ }+ markers, others := 0, 0+ for _, event := range loaded.Events {+ if event.Activity == ExternalAgentActivityHistoryRead {+ markers+++ } else {+ others+++ }+ }+ if markers != 3 || others != maxExternalAgentActivityHistoryRecords {+ t.Fatalf("markers=%d others=%d; want 3 daily markers kept beside %d capped records", markers, others, maxExternalAgentActivityHistoryRecords)+ }+}diff --git a/internal/config/persistence.go b/internal/config/persistence.goindex 0963246f98..e7b988f51d 100644--- a/internal/config/persistence.go+++ b/internal/config/persistence.go@@ -8,6 +8,7 @@ import ("fmt""os""path/filepath"+ "slices""sort""strings""sync"@@ -3173,6 +3174,11 @@ const (ExternalAgentActivityActionPlan = "action_plan"ExternalAgentActivityActionDecision = "action_decision"ExternalAgentActivityActionExecute = "action_execute"+ // ExternalAgentActivityHistoryRead is a day marker, at most one per UTC+ // day, written after a successful requested history read+ // (list_recent_changes, get_metric_history). The request itself is still+ // recorded under its own activity, so existing counters keep their meaning.+ ExternalAgentActivityHistoryRead = "history_read"maxExternalAgentActivityHistoryRecords = 500externalAgentActivityHistoryRetention = 90 * 24 * time.Hour@@ -3301,11 +3307,42 @@ func pruneExternalAgentActivityRecords(records []ExternalAgentActivityRecord, cunormalized = kept}if maxRecords > 0 && len(normalized) > maxRecords {- normalized = normalized[len(normalized)-maxRecords:]+ // History-read day markers sit outside the cap: retention bounds them+ // to one per day, and a busy agent's per-request records must not push+ // out the days it read history on.+ kept := make([]ExternalAgentActivityRecord, 0, maxRecords)+ others := 0+ for i := len(normalized) - 1; i >= 0; i-- {+ if normalized[i].Activity == ExternalAgentActivityHistoryRead {+ kept = append(kept, normalized[i])+ continue+ }+ if others < maxRecords {+ kept = append(kept, normalized[i])+ others+++ }+ }+ slices.Reverse(kept)+ normalized = kept}return normalized}+// externalAgentHistoryReadMarkerRecorded reports whether record is a history+// read day marker for a UTC day that already has one.+func externalAgentHistoryReadMarkerRecorded(events []ExternalAgentActivityRecord, record ExternalAgentActivityRecord) bool {+ if record.Activity != ExternalAgentActivityHistoryRead {+ return false+ }+ day := record.Timestamp.UTC().Format(time.DateOnly)+ for _, event := range events {+ if event.Activity == ExternalAgentActivityHistoryRead && event.Timestamp.UTC().Format(time.DateOnly) == day {+ return true+ }+ }+ return false+}+func normalizeWorkflowPromptActivityRecord(record WorkflowPromptActivityRecord) (WorkflowPromptActivityRecord, bool) {if record.Timestamp.IsZero() {return WorkflowPromptActivityRecord{}, false@@ -3465,7 +3502,9 @@ func (c *ConfigPersistence) RecordExternalAgentActivity(record ExternalAgentActi"external agent activity history", "Resetting unreadable external agent activity history",newEmptyExternalAgentActivityHistoryData,func(history *ExternalAgentActivityHistoryData) {- history.Events = append(history.Events, record)+ if !externalAgentHistoryReadMarkerRecorded(history.Events, record) {+ history.Events = append(history.Events, record)+ }history.Events = pruneExternalAgentActivityRecords(history.Events,record.Timestamp.Add(-externalAgentActivityHistoryRetention),diff --git a/internal/telemetry/pulse_intelligence_evidence.go b/internal/telemetry/pulse_intelligence_evidence.goindex f6a6397563..0f95d6469c 100644--- a/internal/telemetry/pulse_intelligence_evidence.go+++ b/internal/telemetry/pulse_intelligence_evidence.go@@ -83,6 +83,11 @@ type PulseIntelligenceExternalAgentEvidence struct {OperatorStateRequests intFindingRequests intActionRequests int+ // HistoryReadDays counts distinct UTC days in the window with at least+ // one successful requested history read (list_recent_changes,+ // get_metric_history). It backs the event-record review and is not a+ // request count.+ HistoryReadDays int}// CollaborationActive reports whether an external agent or MCP adapter used a@@ -122,6 +127,14 @@ func PulseIntelligenceExternalAgentEvidenceFromHistory(history *config.ExternalAif history == nil {return evidence}+ // History-read days are whole UTC dates: the partial date the window+ // starts in is left out, so the count is at most 30 and a day is never+ // lost because its first read fell before the cutoff.+ firstHistoryReadDay := since.UTC().Truncate(24 * time.Hour)+ if firstHistoryReadDay.Before(since) {+ firstHistoryReadDay = firstHistoryReadDay.Add(24 * time.Hour)+ }+ historyReadDays := make(map[string]struct{})for _, event := range history.Events {if event.Timestamp.IsZero() || event.Timestamp.Before(since) {continue@@ -133,8 +146,12 @@ func PulseIntelligenceExternalAgentEvidenceFromHistory(history *config.ExternalAif strings.TrimSpace(event.Surface) == config.ExternalAgentActivitySurfacePulseMCP {evidence.MCPAdapterUsed = true}+ if strings.TrimSpace(event.Activity) == config.ExternalAgentActivityHistoryRead && !event.Timestamp.Before(firstHistoryReadDay) {+ historyReadDays[event.Timestamp.UTC().Format(time.DateOnly)] = struct{}{}+ }evidence.ApplyActivity(event.Activity)}+ evidence.HistoryReadDays = len(historyReadDays)return evidence}diff --git a/internal/telemetry/pulse_intelligence_evidence_branchcov0718_test.go b/internal/telemetry/pulse_intelligence_evidence_branchcov0718_test.goindex e89762d038..14966d050b 100644--- a/internal/telemetry/pulse_intelligence_evidence_branchcov0718_test.go+++ b/internal/telemetry/pulse_intelligence_evidence_branchcov0718_test.go@@ -395,3 +395,46 @@ func TestPulseIntelligenceExternalAgentEvidenceFromHistory(t *testing.T) {})}}++// HistoryReadDays counts distinct UTC days, not requests, and only inside the+// window and on external-agent surfaces.+func TestPulseIntelligenceExternalAgentEvidence_HistoryReadDays(t *testing.T) {+ now := time.Date(2026, 10, 29, 12, 0, 0, 0, time.UTC)+ since := now.Add(-30 * 24 * time.Hour)+ read := func(at time.Time, surface string) config.ExternalAgentActivityRecord {+ return config.ExternalAgentActivityRecord{Timestamp: at, Surface: surface, Activity: config.ExternalAgentActivityHistoryRead}+ }+ evidence := PulseIntelligenceExternalAgentEvidenceFromHistory(&config.ExternalAgentActivityHistoryData{Events: []config.ExternalAgentActivityRecord{+ read(now.Add(-2*time.Hour), config.ExternalAgentActivitySurfaceAgentAPI),+ read(now.Add(-1*time.Hour), config.ExternalAgentActivitySurfacePulseMCP),+ read(now.Add(-3*24*time.Hour), config.ExternalAgentActivitySurfacePulseMCP),+ read(now.Add(-40*24*time.Hour), config.ExternalAgentActivitySurfaceAgentAPI),+ read(now.Add(-5*24*time.Hour), "pulse_assistant"),+ {Timestamp: now.Add(-6 * 24 * time.Hour), Surface: config.ExternalAgentActivitySurfaceAgentAPI, Activity: config.ExternalAgentActivityFleetContext},+ }}, since)+ if evidence.HistoryReadDays != 2 {+ t.Fatalf("HistoryReadDays = %d; want 2 (two days in the window on agent surfaces)", evidence.HistoryReadDays)+ }+ if evidence.ContextRequests != 1 {+ t.Fatalf("ContextRequests = %d; history-read markers must not count as requests", evidence.ContextRequests)+ }+}++// History-read days are whole UTC dates inside the window: the partial date+// the window starts in is left out, so 31 dates of reads report 30.+func TestPulseIntelligenceExternalAgentEvidence_HistoryReadDaysAreWholeDates(t *testing.T) {+ now := time.Date(2026, 10, 31, 12, 0, 0, 0, time.UTC)+ since := now.Add(-30 * 24 * time.Hour)+ events := make([]config.ExternalAgentActivityRecord, 0, 31)+ for day := 0; day <= 30; day++ {+ events = append(events, config.ExternalAgentActivityRecord{+ Timestamp: time.Date(2026, 10, 1+day, 13, 0, 0, 0, time.UTC),+ Surface: config.ExternalAgentActivitySurfaceAgentAPI,+ Activity: config.ExternalAgentActivityHistoryRead,+ })+ }+ evidence := PulseIntelligenceExternalAgentEvidenceFromHistory(&config.ExternalAgentActivityHistoryData{Events: events}, since)+ if evidence.HistoryReadDays != 30 {+ t.Fatalf("HistoryReadDays = %d; want 30 whole dates", evidence.HistoryReadDays)+ }+}diff --git a/internal/telemetry/telemetry.go b/internal/telemetry/telemetry.goindex 02c4b29b84..e3bf585919 100644--- a/internal/telemetry/telemetry.go+++ b/internal/telemetry/telemetry.go@@ -228,7 +228,9 @@ const (// Schema v19 adds only the rolling count of successfully served metric// history responses containing data older than seven days.// Schema v20 adds aggregate reporting outcomes and distinct-period reuse.- TelemetrySchemaVersion = 20+ // Schema v21 adds only the count of distinct days, 0 to 30, on which an+ // external agent successfully read change or metric history.+ TelemetrySchemaVersion = 21)type installIDRecord struct {@@ -518,6 +520,7 @@ type Ping struct {PulseIntelligenceMCPAdapterUsed30d bool `json:"pulse_intelligence_mcp_adapter_used_30d"`PulseIntelligenceExternalAgentContextRequests30d int `json:"pulse_intelligence_external_agent_context_requests_30d"`PulseIntelligenceExternalAgentEventStreamRequests30d int `json:"pulse_intelligence_external_agent_event_stream_requests_30d"`+ PulseIntelligenceExternalAgentHistoryReadDays30d int `json:"pulse_intelligence_external_agent_history_read_days_30d"`PulseIntelligenceExternalAgentProvisioningRequests30d int `json:"pulse_intelligence_external_agent_provisioning_requests_30d"`PulseIntelligenceExternalAgentOperatorStateRequests30d int `json:"pulse_intelligence_external_agent_operator_state_requests_30d"`PulseIntelligenceExternalAgentFindingRequests30d int `json:"pulse_intelligence_external_agent_finding_requests_30d"`@@ -753,6 +756,7 @@ type Snapshot struct {PulseIntelligenceMCPAdapterUsed30d boolPulseIntelligenceExternalAgentContextRequests30d intPulseIntelligenceExternalAgentEventStreamRequests30d int+ PulseIntelligenceExternalAgentHistoryReadDays30d intPulseIntelligenceExternalAgentProvisioningRequests30d intPulseIntelligenceExternalAgentOperatorStateRequests30d intPulseIntelligenceExternalAgentFindingRequests30d int@@ -1556,6 +1560,7 @@ func applySnapshot(base Ping, fn SnapshotFunc) Ping {ping.PulseIntelligenceMCPAdapterUsed30d = s.PulseIntelligenceMCPAdapterUsed30dping.PulseIntelligenceExternalAgentContextRequests30d = s.PulseIntelligenceExternalAgentContextRequests30dping.PulseIntelligenceExternalAgentEventStreamRequests30d = s.PulseIntelligenceExternalAgentEventStreamRequests30d+ ping.PulseIntelligenceExternalAgentHistoryReadDays30d = s.PulseIntelligenceExternalAgentHistoryReadDays30dping.PulseIntelligenceExternalAgentProvisioningRequests30d = s.PulseIntelligenceExternalAgentProvisioningRequests30dping.PulseIntelligenceExternalAgentOperatorStateRequests30d = s.PulseIntelligenceExternalAgentOperatorStateRequests30dping.PulseIntelligenceExternalAgentFindingRequests30d = s.PulseIntelligenceExternalAgentFindingRequests30ddiff --git a/pkg/server/telemetry_pulse_intelligence.go b/pkg/server/telemetry_pulse_intelligence.goindex 982f86726e..5577088ec2 100644--- a/pkg/server/telemetry_pulse_intelligence.go+++ b/pkg/server/telemetry_pulse_intelligence.go@@ -378,6 +378,7 @@ func applyPulseIntelligenceExternalAgentSnapshot(snap.PulseIntelligenceMCPAdapterUsed30d = evidence.MCPAdapterUsedsnap.PulseIntelligenceExternalAgentContextRequests30d = evidence.ContextRequestssnap.PulseIntelligenceExternalAgentEventStreamRequests30d = evidence.EventStreamRequests+ snap.PulseIntelligenceExternalAgentHistoryReadDays30d = evidence.HistoryReadDayssnap.PulseIntelligenceExternalAgentProvisioningRequests30d = evidence.ProvisioningRequestssnap.PulseIntelligenceExternalAgentOperatorStateRequests30d = evidence.OperatorStateRequestssnap.PulseIntelligenceExternalAgentFindingRequests30d = evidence.FindingRequestsdiff --git a/tests/integration/tests/19-telemetry-disclosure.spec.ts b/tests/integration/tests/19-telemetry-disclosure.spec.tsindex ac77abffb8..4af68bdf2d 100644--- a/tests/integration/tests/19-telemetry-disclosure.spec.ts+++ b/tests/integration/tests/19-telemetry-disclosure.spec.ts@@ -10,7 +10,7 @@ import {import { createAuthenticatedStorageState } from "./helpers";const __dirname = path.dirname(fileURLToPath(import.meta.url));-const EXPECTED_TELEMETRY_SCHEMA_VERSION = 20;+const EXPECTED_TELEMETRY_SCHEMA_VERSION = 21;type WorkerFixtures = {authStorageStatePath: string;