Skip to content
Merged
1 change: 1 addition & 0 deletions changelog.d/added-15964-hub-activity-events.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- The heartbeat `activity` block now carries the stage hops, opens and merges a spoke saw since the hub last acknowledged them (at most 200, oldest dropped first, drops disclosed as `events_dropped`), and `GET /api/hub/activity` serves them as `events` from a fleet-wide, memory-only ring of the last 1,000 events, filtered per user and per hive like items, so the hub board can animate movement and show merge toasts ([#15964](https://github.com/hivecommons/hive/issues/15964), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)).
8 changes: 8 additions & 0 deletions src/cmd/hive/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -5686,6 +5686,14 @@ func (b *boot) bootHeartbeatWith(deps bootHeartbeatDeps) {
}
return b.dashSrv.HubActivityItems(ctx)
},
// Snapshot supersedes Items and adds recent merges, from
// which the publisher derives merge events (#15964).
Snapshot: func(ctx context.Context) (hubactivity.Snapshot, bool) {
if b.dashSrv == nil {
return hubactivity.Snapshot{}, false
}
return b.dashSrv.HubActivitySnapshot(ctx)
},
Subscribe: func(notify func()) {
if b.dashSrv != nil {
b.dashSrv.OnStageTrackerPublish(notify)
Expand Down
4 changes: 2 additions & 2 deletions src/docs/api-reference/hub-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,15 +38,15 @@ Part of the [Dashboard REST API reference](../api-reference.md); see that page f
| `POST` | `/api/shared-agent-pool/leases` | Hub handler-specific | Acquire or renew a shared CLI session lease | `pkg/hub/server.go:1708` |
| `PUT` | `/api/shared-agent-pool/leases` | Hub handler-specific | Renew an active shared CLI session lease | `pkg/hub/server.go:1709` |
| `DELETE` | `/api/shared-agent-pool/leases` | Hub handler-specific | Release a shared CLI session lease | `pkg/hub/server.go:1710` |
| `POST` | `/api/heartbeat` | Hub handler-specific | Heartbeat. A request carrying `X-Hive-Activity-Update` is an activity-only update ([#15963](https://github.com/hivecommons/hive/issues/15963)): body `{"activity_update":{"hive_id","activity"}}`, the same per-hive bearer, accepted only for a hive already in the registry (`404` otherwise); it replaces the in-memory activity digest and nothing else, and the signed response carries `ok` and `activity_etag` | `pkg/hub/server.go:1711` |
| `POST` | `/api/heartbeat` | Hub handler-specific | Heartbeat. A request carrying `X-Hive-Activity-Update` is an activity-only update ([#15963](https://github.com/hivecommons/hive/issues/15963)): body `{"activity_update":{"hive_id","activity"}}`, the same per-hive bearer, accepted only for a hive already in the registry (`404` otherwise); it replaces the in-memory activity digest and nothing else, and the signed response carries `ok`, `activity_etag` and `activity_events_ack` (the highest activity event sequence number the hub holds for the hive, [#15964](https://github.com/hivecommons/hive/issues/15964); full heartbeat responses carry it too) | `pkg/hub/server.go:1711` |
| `POST` | `/api/task-status` | Hub handler-specific | Task Status | `pkg/hub/server.go:1712` |
| `GET` | `/api/registry` | Hub handler-specific | Registry | `pkg/hub/server.go:1720` |
| `GET` | `/api/hub/leaderboard` | Hub handler-specific | Leaderboard | `pkg/hub/server.go:1721` |
| `GET` | `/api/hub/stats` | Hub handler-specific | Stats | `pkg/hub/server.go:1722` |
| `GET` | `/api/fleet-stats` | Hub handler-specific | Fleet Stats | `pkg/hub/server.go:1723` |
| `GET` | `/api/hub/evidence` | Hub admin | Read-only cross-hive evidence drill-down from each spoke's stored heartbeat `evidence` summary ([#12116](https://github.com/hivecommons/hive/issues/12116)); non-admins get `403`. Returns `spokes`, `reporting`, pooled `calibration` (bucket 0–5 → `{n, bad, rate, lo, hi}`; the hub view folds the six buckets into four reviewer-confidence ranges), `findings[]` (the plain-language *What this says* sentences, generated from the same fields; [#12456](https://github.com/hivecommons/hive/issues/12456)), `by_acmm_level` (`level`, `hives`, `merged_90d`, `revert_rate`, and `time_to_merge` — `median_of_hive_medians_s`, `hives`, `n` — the median of the level's per-hive median time-to-merge, omitted when no hive at the level reports one; [#12464](https://github.com/hivecommons/hive/issues/12464)), `family_false_approve_rate` (`same`/`cross`/`mixed`, hives classed by their reviewer vs author family sets), fleet `record_coverage` (merged PRs with an evidence record over `prs_merged_90d`), fleet panels ([#12370](https://github.com/hivecommons/hive/issues/12370)) `outcomes_by_author_kind[]` (`kind`, `hives`, `n`, `merged`, `reverted`, `merge_rate`, `revert_rate`), `write_counters[]` (`tier`, `hives`, `attempted`, `blocked`, `block_rate`) and `shadow_gate` (`review_gate` / `intent` → `held` / `passed` outcomes with `revert_rate`), each omitted while no spoke reports it and repeated per `by_acmm_level[]` row, and per hive `hives[]` with `acmm_level`, `prs_merged_90d`, `record_coverage`, `family_mix`, false-approve / false-block / revert rates, families, a calibration series the raw `counts` behind them (including `by_author_kind`) so the drill-down can re-pool a hive / ACMM-level selection client-side, and `criteria[]`: the per-axis criteria table derived hub-side from the quadrant criteria (`axis`, `label`, `scored`, `criteria[]` with `name`, `label`, `status` `met`/`unmet`/`not_reported`, `display`/`score` when measured, `reason` otherwise; offline, evidence-less or unscored hives are `not_reported`, never `unmet`; [#12463](https://github.com/hivecommons/hive/issues/12463)). Every rate is `{n, rate, lo, hi}` with a 95% Wilson interval; `rate`/`lo`/`hi` are null when `n` < 10. Window selection ([RFC #12062](https://github.com/hivecommons/hive/issues/12062)): `?hours=24|168|720` pools each hive's matching heartbeat `windows` block instead of its 90-day block (any other or absent `hours` → 90 days); `?from=YYYY-MM-DD|RFC3339[&to=…]` (date-only `to` is inclusive, `to` defaults to now, `to` ≥ `from`, span ≤ 366 days, else `400`) is served from the smallest reported window that reaches back to `from` and flagged `window.approximate`. The response carries `window` (`hours`, `key`, `label`, `from`, `to`, `approximate`, `coverage_available` — `record_coverage` is only computed for the 90-day window because `prs_merged_90d` is a 90-day count), `window_unreported` and per-hive `window_unreported` for hives whose spoke predates per-window reporting. `?hive=<id>[,<id>…]` (repeatable) and `?level=<n>` restrict the registry server-side to those hives / that ACMM level before pooling. Hub admins open it from the Fleet quadrant card or its **🔬 Evidence** button ([#12117](https://github.com/hivecommons/hive/issues/12117)), pick a window (24h / 7d / 30d / 90d / custom), filter it by hive and ACMM level and read each section's ⓘ explainer; the per-hive author-kind revert counts behind the *Revert rate by author kind* panel are `hives[].counts.by_author_kind` ([#12326](https://github.com/hivecommons/hive/issues/12326)). Never consulted by merge decisions | `pkg/hub/evidence.go` |
| `GET` | `/api/hub/evidence/report` | Hub admin | Plain-language report of the hub evidence view ([#12456](https://github.com/hivecommons/hive/issues/12456)), rendered server-side from the same `EvidenceView` as `/api/hub/evidence` so every figure reconciles with the modal; non-admins get `403`. Same `hours=` / `from=` / `to=` window and `hive=` / `level=` filter parameters. `format=md` (default, `text/markdown`) or `format=html` (standalone page, inline CSS, no scripts or external assets, hive names escaped); any other value → `400`. `download=1` sets `Content-Disposition: attachment; filename="hive-evidence-<hive|fleet>-<from>-<to>.md|html"`, otherwise inline. Sections: Summary (the generated findings), What we measured and why, The numbers, How to read these, What is not reported yet and why, Grade per section, footer link to `review-evidence.md`. `Cache-Control: no-store`. Read-only; never consulted by merge decisions | `pkg/hub/evidence_report.go` |
| `GET` | `/api/hub/activity` | Signed-in user | Read-only hub-wide activity view ([#15951](https://github.com/hivecommons/hive/issues/15951), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)) merged from each spoke's heartbeat `activity` digest, held in hub memory only. Authorization is per user and per hive before aggregation: hub admins see every registered hive; everyone else only hives they own or hold an unexpired grant for; anonymous → `401`. Returns `hives[]` (`hive_id`, `name`, `status` `ok`/`stale`/`not_reporting`/`missing`, `reporting`, `stale` once the block is older than two heartbeats, `last_heartbeat`, `received_at`, `generated_at`, `totals` — `items`, `by_stage`, `by_modifier`, counting private and truncated items too — and `truncated`), `items[]` (`hive_id`, `repo`, `n`, `kind`, `title`, `author_kind`, `stage`, `stage_n`, `since`, `mods`, `private`) ordered needs-human/needs-decision, stalled, furthest stage, oldest, and a response-level `truncated` (cap 2000). Each digest carries at most 100 items by default and never more than the 250-item hub ceiling; private-repository items appear only when the spoke opts in. Filters: `hive`, `repo`, `stage`, `mod`, `author_kind`, `q` (title substring or `#<n>`), each ≤ 200 characters (else `400`). `ETag` + `If-None-Match` → `304`; `Cache-Control: private, no-cache`, `Vary: Cookie, Authorization`. No actions | `pkg/hub/activity.go` |
| `GET` | `/api/hub/activity` | Signed-in user | Read-only hub-wide activity view ([#15951](https://github.com/hivecommons/hive/issues/15951), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)) merged from each spoke's heartbeat `activity` digest, held in hub memory only. Authorization is per user and per hive before aggregation: hub admins see every registered hive; everyone else only hives they own or hold an unexpired grant for; anonymous → `401`. Returns `hives[]` (`hive_id`, `name`, `status` `ok`/`stale`/`not_reporting`/`missing`, `reporting`, `stale` once the block is older than two heartbeats, `last_heartbeat`, `received_at`, `generated_at`, `totals` — `items`, `by_stage`, `by_modifier`, counting private and truncated items too — `truncated` and `events_dropped`), `items[]` (`hive_id`, `repo`, `n`, `kind`, `title`, `author_kind`, `stage`, `stage_n`, `since`, `mods`, `private`) ordered needs-human/needs-decision, stalled, furthest stage, oldest, a response-level `truncated` (cap 2000), and `events[]` ([#15964](https://github.com/hivecommons/hive/issues/15964): `hive_id`, `received_at`, `seq`, `type` `opened`/`stage`/`merged`, `repo`, `n`, `kind`, `title`, `from`, `stage`, `at`, `private`), oldest first, from a fleet-wide in-memory ring of the last 1,000 events. Events are filtered per user and per hive exactly like items, before aggregation, so an event for a hive the viewer cannot see is never delivered; `mod`/`author_kind` filters keep only events whose item is still on the hive's board. A spoke block carries at most 200 events; drops are disclosed per hive as `events_dropped`. New events change the `ETag`. Each digest carries at most 100 items by default and never more than the 250-item hub ceiling; private-repository items appear only when the spoke opts in. Filters: `hive`, `repo`, `stage`, `mod`, `author_kind`, `q` (title substring or `#<n>`), each ≤ 200 characters (else `400`). `ETag` + `If-None-Match` → `304`; `Cache-Control: private, no-cache`, `Vary: Cookie, Authorization`. No actions | `pkg/hub/activity.go` |
| `GET` | `/api/hub/version` | Hub handler-specific | Hub Version | `pkg/hub/server.go:1731` |
| `DELETE` | `/api/hub/registry/{id}` | Hub handler-specific | Registry Delete | `pkg/hub/server.go:1741` |
| `POST` | `/api/contribute/register` | Hub handler-specific | Contribute Proxy | `pkg/hub/server.go:1742` |
Expand Down
2 changes: 1 addition & 1 deletion src/docs/telemetry.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ hub:
share_private: false # private-repository items are dropped (still counted in totals) unless true
```

When the cap applies, items needing a human or a decision are kept first, then stalled ones, then the furthest stage, and the number left out is reported as `truncated`. A repository counts as public only when the hub lists the hive as public (`hub.is_public`, its project repos) or it is on `HIVE_PUBLIC_REPOS`. Once the hub acknowledges a digest's etag, later beats send only `etag` and `generated_at` until the tracker changes. A tracker change also sends an activity-only update over the heartbeat endpoint and bearer, at most one every 15 seconds; changes arriving meanwhile are merged into it. `hub.heartbeat_omit` applies: `repos` withholds every item (totals remain) and `task_titles` blanks titles.
When the cap applies, items needing a human or a decision are kept first, then stalled ones, then the furthest stage, and the number left out is reported as `truncated`. A repository counts as public only when the hub lists the hive as public (`hub.is_public`, its project repos) or it is on `HIVE_PUBLIC_REPOS`. Once the hub acknowledges a digest's etag, later beats send only `etag` and `generated_at` until the tracker changes. A tracker change also sends an activity-only update over the heartbeat endpoint and bearer, at most one every 15 seconds; changes arriving meanwhile are merged into it. The block also carries `events` ([#15964](https://github.com/hivecommons/hive/issues/15964)): the stage hops, opens and merges the spoke saw since the hub last acknowledged them, derived by diffing successive tracker snapshots (the first one only seeds the baseline), each with a sequence number. At most 200 are buffered; the oldest are dropped first and `events_dropped` discloses how many. Events stay buffered, and are resent, until a heartbeat or update response's `activity_events_ack` covers them. Private-repository items yield no events unless `share_private` is on. The hub keeps the last 1,000 events across the fleet in memory only. `hub.heartbeat_omit` applies: `repos` withholds every item and event (totals remain) and `task_titles` blanks titles.

## Telemetry agent

Expand Down
34 changes: 28 additions & 6 deletions src/pkg/dashboard/hub_activity.go
Original file line number Diff line number Diff line change
Expand Up @@ -46,26 +46,48 @@ func (s *Server) notifyStageTrackerPublish() {
// while the spoke has no status or the tracker cannot be built. Reading
// does not count as a tracker client, so it adds no SSE nudges.
func (s *Server) HubActivityItems(ctx context.Context) ([]hubactivity.Item, bool) {
snap, ok := s.HubActivitySnapshot(ctx)
return snap.Items, ok
}

// HubActivitySnapshot is HubActivityItems plus the tracker's recently
// merged pull requests (RecentlyMerged), which the heartbeat publisher
// turns into merge events (#15964). Merges carry Private the same way.
func (s *Server) HubActivitySnapshot(ctx context.Context) (hubactivity.Snapshot, bool) {
if s == nil {
return nil, false
return hubactivity.Snapshot{}, false
}
s.statusMu.RLock()
status := s.status
s.statusMu.RUnlock()
if status == nil {
return nil, false
return hubactivity.Snapshot{}, false
}
body, _, _, _ := s.stageTrackerPayloadFrom(ctx, status, time.Now().UTC(), false)
if body == nil {
return nil, false
return hubactivity.Snapshot{}, false
}
var tracker struct {
Items []StageTrackerItem `json:"items"`
Items []StageTrackerItem `json:"items"`
RecentlyMerged []StageTrackerMerged `json:"recently_merged"`
}
if err := json.Unmarshal(body, &tracker); err != nil {
return nil, false
return hubactivity.Snapshot{}, false
}
public := s.publicRepos()
return hubactivity.Snapshot{
Items: hubActivityItems(tracker.Items, public),
Merged: hubActivityMerges(tracker.RecentlyMerged, public),
}, true
}

// hubActivityMerges maps the tracker's recently merged list to merge rows.
func hubActivityMerges(merged []StageTrackerMerged, public publicRepoSet) []hubactivity.Merge {
out := make([]hubactivity.Merge, 0, len(merged))
for _, m := range merged {
out = append(out, hubactivity.Merge{Repo: m.Repo, Number: m.Number, MergedAt: m.MergedAt, Private: !public.allows(m.Repo)})
}
return hubActivityItems(tracker.Items, s.publicRepos()), true
return out
}

// hubActivityItems maps tracker rows to digest rows. A row the tracker
Expand Down
19 changes: 17 additions & 2 deletions src/pkg/hub/activity.go
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,8 @@ type storedActivity struct {
type activityStore struct {
mu sync.Mutex
byHive map[string]storedActivity
// events is the fleet-wide ring of recent activity events (#15964).
events activityEventRing
}

// record applies a heartbeat's activity block and returns the etag the hub
Expand All @@ -85,6 +87,9 @@ func (st *activityStore) record(hiveID string, block *hubactivity.Digest, now ti
}
return ""
}
// Events ride on markers and full digests alike, and are taken even
// when the marker's etag misses.
st.events.ingest(hiveID, block.Events, block.EventsDropped, now)
if block.IsUnchangedMarker() {
// Compare in the stored (cleaned) form, or a marker whose etag
// changes under cleaning would never match and wedge the handshake.
Expand Down Expand Up @@ -124,6 +129,7 @@ func (st *activityStore) forget(hiveID string) {
st.mu.Lock()
defer st.mu.Unlock()
delete(st.byHive, hiveID)
st.events.forget(hiveID)
}

func (st *activityStore) forgetOldLocked(now time.Time) {
Expand All @@ -132,6 +138,7 @@ func (st *activityStore) forgetOldLocked(now time.Time) {
delete(st.byHive, id)
}
}
st.events.forgetOld(now, activityForgetAfter)
}

// snapshot copies the blocks of the given hives only, so data of hives the
Expand Down Expand Up @@ -262,6 +269,9 @@ type ActivityHiveView struct {
Totals *hubactivity.Totals `json:"totals,omitempty"`
// Truncated is how many of this hive's items its digest left out.
Truncated int `json:"truncated,omitempty"`
// EventsDropped is how many of this hive's events the spoke's or the
// hub's per-block cap dropped before they reached the ring (#15964).
EventsDropped int `json:"events_dropped,omitempty"`
}

// ActivityViewItem is one merged item tagged with its hive.
Expand All @@ -274,6 +284,9 @@ type ActivityViewItem struct {
type ActivityView struct {
Hives []ActivityHiveView `json:"hives"`
Items []ActivityViewItem `json:"items"`
// Events are the visible hives' recent stage hops, opens and merges
// from the fleet-wide ring, oldest first (#15964).
Events []ActivityViewEvent `json:"events"`
// Truncated is how many matching items the response cap left out, on
// top of what each hive's own digest already left out.
Truncated int `json:"truncated,omitempty"`
Expand All @@ -282,7 +295,7 @@ type ActivityView struct {
// buildActivityView merges the blocks of the visible hives only. Hives must
// already be authorized for the viewer.
func buildActivityView(hives []activityHive, blocks map[string]storedActivity, f activityFilter, now time.Time) ActivityView {
view := ActivityView{Hives: []ActivityHiveView{}, Items: []ActivityViewItem{}}
view := ActivityView{Hives: []ActivityHiveView{}, Items: []ActivityViewItem{}, Events: []ActivityViewEvent{}}
for _, h := range hives {
hv := ActivityHiveView{HiveID: h.ID, Name: h.Name, LastHeartbeat: h.LastHeartbeat}
block, ok := blocks[h.ID]
Expand Down Expand Up @@ -359,7 +372,9 @@ func (s *HubServer) handleHubActivity(w http.ResponseWriter, r *http.Request) {
for i, h := range hives {
ids[i] = h.ID
}
view := buildActivityView(hives, s.activity.snapshot(ids), f, now)
blocks := s.activity.snapshot(ids)
view := buildActivityView(hives, blocks, f, now)
addActivityEvents(&view, hives, blocks, s.activity.eventsSnapshot(ids), f)
body, err := json.Marshal(view)
if err != nil {
s.logger.Error("hub activity: encode view", "error", err)
Expand Down
Loading
Loading