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.

Count the days external agents read Pulse history

rcourtmanb94d8473ce5a
diff --git a/docs/PRIVACY.md b/docs/PRIVACY.md
index 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.md
index 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 the
same 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 same
diff --git a/docs/release-control/v6/internal/subsystems/api-contracts.md b/docs/release-control/v6/internal/subsystems/api-contracts.md
index 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 agent
reads as the place a new MCP user starts; its named tools are pinned to the
manifest'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-consumable
structured capability surface for a single resource: the governed
diff --git a/docs/release-control/v6/internal/subsystems/security-privacy.md b/docs/release-control/v6/internal/subsystems/security-privacy.md
index 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-free
approved-action refusal counters for target change, prerequisite failure, and
invalid typed contract so agent-side pre-mutation failures no longer collapse
into `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 the
outcome is `available`. No version, release tag, URL, response, or error text
leaves the install, and the receiver canonicalizes both strings to the released
vocabulary 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 the
operator-facing run history is trimmed. Finding volume has its own persistence
diff --git a/docs/release-control/v6/internal/subsystems/storage-recovery.md b/docs/release-control/v6/internal/subsystems/storage-recovery.md
index 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 reads
through the same history path the charts use (the metrics store, then the
in-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` agent
events add no persistence. They are published in memory after the monitor
adapter has recorded the matching `resource_changes` row, and per-resource
diff --git a/frontend-modern/browser-verification/da2e7dd841aaeb9b.json b/frontend-modern/browser-verification/da2e7dd841aaeb9b.json
new file mode 100644
index 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.md
index 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.ts
index 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.ts
index 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.ts
index 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.go
index 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.go
index e4a83422da..1f2f612e20 100644
--- a/internal/api/agent_activity_telemetry_test.go
+++ b/internal/api/agent_activity_telemetry_test.go
@@ -1,6 +1,7 @@
package api
import (
+ "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.go
index 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.go
index 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 = 500
externalAgentActivityHistoryRetention = 90 * 24 * time.Hour
@@ -3301,11 +3307,42 @@ func pruneExternalAgentActivityRecords(records []ExternalAgentActivityRecord, cu
normalized = 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.go
index 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 int
FindingRequests int
ActionRequests 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.ExternalA
if 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.ExternalA
if 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.go
index 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.go
index 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 bool
PulseIntelligenceExternalAgentContextRequests30d int
PulseIntelligenceExternalAgentEventStreamRequests30d int
+ PulseIntelligenceExternalAgentHistoryReadDays30d int
PulseIntelligenceExternalAgentProvisioningRequests30d int
PulseIntelligenceExternalAgentOperatorStateRequests30d int
PulseIntelligenceExternalAgentFindingRequests30d int
@@ -1556,6 +1560,7 @@ func applySnapshot(base Ping, fn SnapshotFunc) Ping {
ping.PulseIntelligenceMCPAdapterUsed30d = s.PulseIntelligenceMCPAdapterUsed30d
ping.PulseIntelligenceExternalAgentContextRequests30d = s.PulseIntelligenceExternalAgentContextRequests30d
ping.PulseIntelligenceExternalAgentEventStreamRequests30d = s.PulseIntelligenceExternalAgentEventStreamRequests30d
+ ping.PulseIntelligenceExternalAgentHistoryReadDays30d = s.PulseIntelligenceExternalAgentHistoryReadDays30d
ping.PulseIntelligenceExternalAgentProvisioningRequests30d = s.PulseIntelligenceExternalAgentProvisioningRequests30d
ping.PulseIntelligenceExternalAgentOperatorStateRequests30d = s.PulseIntelligenceExternalAgentOperatorStateRequests30d
ping.PulseIntelligenceExternalAgentFindingRequests30d = s.PulseIntelligenceExternalAgentFindingRequests30d
diff --git a/pkg/server/telemetry_pulse_intelligence.go b/pkg/server/telemetry_pulse_intelligence.go
index 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.MCPAdapterUsed
snap.PulseIntelligenceExternalAgentContextRequests30d = evidence.ContextRequests
snap.PulseIntelligenceExternalAgentEventStreamRequests30d = evidence.EventStreamRequests
+ snap.PulseIntelligenceExternalAgentHistoryReadDays30d = evidence.HistoryReadDays
snap.PulseIntelligenceExternalAgentProvisioningRequests30d = evidence.ProvisioningRequests
snap.PulseIntelligenceExternalAgentOperatorStateRequests30d = evidence.OperatorStateRequests
snap.PulseIntelligenceExternalAgentFindingRequests30d = evidence.FindingRequests
diff --git a/tests/integration/tests/19-telemetry-disclosure.spec.ts b/tests/integration/tests/19-telemetry-disclosure.spec.ts
index 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;