Skip to content

feat(monitoring): serve the monitor kind list at runtime so contributed kinds are not blocked - #28367

Merged
bolichen97 merged 1 commit into
mainfrom
fix/monitor-contract-runtime
Nov 4, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/monitor-contract-runtime

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A monitor of a kind an edition contributed at boot shows its real state in the dashboard, with save and restart enabled, instead of appearing blocked.

An edition can register its own pull-request-shaped monitor kind at boot (register_monitor_kind), and the backend accepts and probes it. The dashboard, though, reads its monitor-kind vocabulary only from the checked-in snapshot website/src/monitoring/contract.json, imported at build time by automation.ts and autoNudgeLoop.ts. A monitor whose kind is absent from that snapshot was rendered as blocked even while it probed normally, and its save and restart controls were disabled. Stop still worked.

Why it matters

Until this lands, a downstream edition cannot ship a contributed monitor kind to users: every monitor of that kind reads as blocked in the session automation popover regardless of its real state, with save and restart unavailable.

Not a goal

  • No new runtime registry protocol and no change to how monitors are armed or probed.
  • No change to built-in kinds' behaviour, limits, or wording.
  • The bundled contract.json and its parity test are kept as the fallback; this does not remove the snapshot.
  • No change to the experience of a user with no contributed kinds registered (the stock dashboard): the runtime contract equals the bundled snapshot for them.

What changed (motivation → approach → change)

Symptom: a contributed-kind monitor reads as blocked because the dashboard's supported gate checks the monitor kind against the bundled snapshot, which lists only the built-in kinds. Root cause: the kind vocabulary is a build-time snapshot, and monitor_frontend_contract() itself drew pullRequestMonitorKinds from the frozen built-in constant rather than the live registry.

Approach: serve the contract at runtime and prefer it over the snapshot, keeping the snapshot as the fallback (chosen over regenerating the snapshot per edition, which cannot cover kinds registered at a downstream's boot).

  • monitor_frontend_contract() now builds pullRequestMonitorKinds from the live registry (built-ins plus contributed kinds) via a new registry.all_pull_request_monitor_kinds(). With no plugins the result equals the frozen built-in set.
  • New read route GET /api/monitor-contract returns the runtime contract. It is a cookie-authed browser read registered beside GET /api/autonudge, deliberately not on the strict-internal paths, and exposes only the same vocabulary the bundle already ships — no per-session or owner data.
  • The dashboard fetches it once (useMonitorContract, react-query) and installs its kind list through a runtime seam in monitoring/automation.ts that the record normalizer's supported gate and the pull-request-watch check consult. The installed set is bundled ∪ runtime, so a payload can only add kinds, never shrink the built-ins. On a 404 (older gateway), any fetch error, or a payload without the kind list, the bundled vocabulary stays in force.
  • When the set changes on install, the hook invalidates the normalizer-fed queries and re-runs the authoritative automation seed, so a contributed-kind record already projected into Redux as blocked is re-normalized to its real state without waiting for the next poll.
  • Editing a contributed-kind monitor's target skips the built-in-only client parser (which would reject it) and sends the trimmed target for the backend's kind-specific validation; built-in editing and all creation are unchanged, and a backend refusal surfaces through the existing error path.

Backwards compatibility

Compatible: the change only ADDS kinds to the dashboard's vocabulary and adds one read route; it rejects, renames, and removes nothing. monitor_frontend_contract() returns the same shape; with no contributed kinds its pullRequestMonitorKinds is byte-identical to the bundled snapshot (pinned by the snapshot parity test). An older gateway without the new route is handled by the client's 404 fallback.

Removes nothing: no path, record, key, or public function is hidden, deleted, renamed, or tightened.

Tests

  • automationContributedKind.test.ts: a contributed kind reads as blocked without the runtime contract and as its real, actionable state with it; built-ins are unchanged with no contributed kinds; a partial/older payload and a payload omitting a bundled kind both leave the bundled kinds in force (add-only).
  • useMonitorContract.test.ts: success installs the kinds; a 404 and other errors fall back to the bundled contract; a record normalized before the contract arrives flips from blocked to its real state once installed, with the contract fetched exactly once; a payload adding nothing touches no queries.
  • hooks/websocket/monitorContractReseed.test.tsx: a contributed-kind monitor seeded into Redux as blocked flips to actionable when the contract installs, driven by a REST re-seed (never a websocket frame), contract fetched once.
  • SessionAutomationPopover.test.tsx: a contributed-kind target edit is sent trimmed to the update endpoint (not refused client-side), and a backend refusal surfaces through the error path; built-in editing unchanged.
  • Backend: api_monitor_contract returns the contract and names a contributed kind; all_pull_request_monitor_kinds() and the contract include a contributed kind and still agree with the built-ins when none is registered; the route-sweep integration test proves the new read answers 401/403 unauthenticated; the snapshot parity test and the server composition contract are updated and green.

Proof: not provable -- frontend test (prove.py runs Python only); the normalizer behaviour change is a frontend .ts change, and the backend tests exercise added surface rather than reverting a production hunk.

Manual verification

N/A — unit and integration coverage is sufficient. The visible effect requires a downstream edition to register a contributed kind, which the stock dashboard cannot do; the contributed-kind paths are covered by the tests above.

Screenshots / video

Why no screenshot: the stock dashboard registers no contributed monitor kinds, so there is no rendered delta to capture; the visible change (a contributed-kind monitor showing its real state with save/restart enabled) only appears once a downstream edition registers a kind, and is covered by the normalizer and popover tests.

Related Issues

Closes #25689

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (monitor-architecture spec and the plugin docstring)
  • No secrets, credentials, or internal references in the diff

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 2, 2026
@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of 776266f729863d512f55d67cba9d114997e0e2f1 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks: the diff adds no new control or string. A monitor of an edition-registered kind now shows the existing states and save/restart controls, so no screenshot can show a change on the stock dashboard.

Notes

  • When a contributed-kind target edit is refused, the user sees whatever the backend sends back, because the client-side parser is skipped for these kinds. In api_monitor_update, return refusal text written in the user's words (what went wrong, then what to do), not a raw validation message.

[UX-REVIEWED] 776266f

Description read

[DESCRIPTION-READ] 595cce3355140a9a834079220ca79cae23052f15ff8e3e23ae0bfc84bf00b36e

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 776266f729863d512f55d67cba9d114997e0e2f1 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. The contract is served at runtime and only ever adds kinds, and the bundled snapshot stays as the fallback. That fixes the root cause the PR names, and it stays reversible.

Notes

  • activeMonitorKinds() and setRuntimeMonitorContract keep their state in a module-level global. Any normalizer call that runs before the fetch, or outside the hook's mount, still sees only the bundled kinds. The re-seed handles this for Redux and for the listed query keys. Anything that caches normalized output somewhere else would need to be added to CONTRACT_DEPENDENT_QUERY_KEYS.

[DESIGN-REVIEWED] 776266f

Description read

[DESCRIPTION-READ] 309948d9376a6705d2db32a2028edaa60e37bcfddbaba26fcceded63623b348d

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 776266f729863d512f55d67cba9d114997e0e2f1 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing blocks. Linked issue #25689 is the defect's provenance, and the fix removes the cause (a build-time kind vocabulary) rather than special-casing one kind. One undeclared rider and one unweighed deletion are noted below.

Notes

  • Item 1: no smaller alternative was weighed. The gateway is already the authority on kinds: per the plugins.py docstring, a monitor whose kind is no longer registered is stopped as blocked. The only new thing the client learns from this endpoint is the kind list. Subtraction: drop isKnownMonitorKind(monitor.kind) from the supported gate in automation.ts. If the gateway's blocked state covers the dropped case, the route, the hook, the global seam and the reseed and reconnect paths can all go.
  • Item 6 (undeclared): serverState.ts now refetches the contract on every reconnect, which the description never mentions. Its own comment says the contract is "fetched once with no staleTime", but the hook sets staleTime: Infinity, so the two contradict each other.

What this change ships

Inventory (6 items) — 4 justified

Intent: a monitor of an edition-contributed kind shows its real state with save and restart enabled in the dashboard. This is an ADDITION.

  1. The dashboard fetches the gateway's monitor-kind list and treats contributed kinds as supported — justified
  2. New cookie-authed read GET /api/monitor-contract (1 consumer: useMonitorContract) — justified
  3. The contract's pullRequestMonitorKinds now lists contributed kinds (all_pull_request_monitor_kinds, 1 consumer) — justified
  4. A contributed-kind monitor already shown as blocked flips to its real state when the contract arrives (invalidate plus reseed) — justified
  5. Editing a contributed kind's target skips the client-side parser, and the backend validates it — justified
  6. The contract is re-fetched after a socket reconnect — undeclared

[FIRST-PRINCIPLES-REVIEWED] 776266f

Description read

[DESCRIPTION-READ] a8c5c191145695ef742e13d7f5b25857c029b820a1b459351483b69b5280713a

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 776266f729863d512f55d67cba9d114997e0e2f1 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 776266f

Verdict parsed from the review's SHA-scoped output markers for commit 776266f729863d512f55d67cba9d114997e0e2f1.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 776266f729863d512f55d67cba9d114997e0e2f1 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 776266f729863d512f55d67cba9d114997e0e2f1 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 776266f

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 776266f729863d512f55d67cba9d114997e0e2f1 false-positive: <reason, 20 to 500 characters>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 2, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/monitor-contract-runtime branch from 8120f35 to 7ac98f0 Compare November 2, 2026 17:57
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Both findings addressed in 7ac98f0ccd93ee6de1753473d79dca5bca91564e (not an override).

F1 (useMonitorContract.ts — seeded Redux monitors stay blocked after install). Confirmed: useSessionAutomation prefers the Redux record (liveAutomation ?? automationSnapshot.data), and invalidating React Query alone did not touch it. Fixed as named: setRuntimeMonitorContract now reports whether the kind set changed, and when it does, useMonitorContract re-runs the existing generation-fenced automation seed (seedAutomations, wired through useWebSocket), which re-normalizes the Redux projection against the installed vocabulary. A contributed-kind record seeded as actionable: false flips to its real state on install without waiting for a frame or reconnect. Covered by hooks/websocket/monitorContractReseed.test.tsx (blocked → actionable on install, driven by a REST re-seed, no websocket frame, contract fetched once).

F2 (automation.ts / writeMonitor — valid contributed-kind target edits refused). Confirmed: the built-in-only normalizePullRequestMonitorTarget rejected a contributed kind's URL. Fixed as named: when editing a monitor whose kind is not a built-in (isBuiltInPullRequestMonitorKind), writeMonitor skips client-side normalization and sends the trimmed target for the backend's kind-specific validation (api_monitor_update); a backend refusal surfaces through the existing error path. Built-in editing and all creation are unchanged. Covered by two SessionAutomationPopover.test.tsx cases (trimmed target sent to the update endpoint, not refused client-side; and a backend refusal surfaced through the error path).

Also, per the other lanes: removed the issue/PR numbers from code comments and docstrings (comment-history gate passes locally with 0), added the **Goal:** line and rebuilt the description from the template, and used the no-visual-delta waiver with a justification (the stock dashboard registers no contributed kinds, so there is no rendered delta to capture).

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 2, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/monitor-contract-runtime branch from 7ac98f0 to 2879bf9 Compare November 2, 2026 18:35
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Nov 2, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/monitor-contract-runtime branch from 2879bf9 to 7945883 Compare November 3, 2026 11:51
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased onto current main to clear the merge conflict; no content change. Head: 7945883.

@chenmingwei23
chenmingwei23 force-pushed the fix/monitor-contract-runtime branch from 7945883 to e7a9cc3 Compare November 3, 2026 12:08
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Both upheld findings addressed in e7a9cc36453d69aaf1fa83584966ffcc2c722521 (not an override).

F1 (useMonitorContract.ts:53 - contract not refreshed on reconnect). The reconnect invalidation list in website/src/hooks/websocket/serverState.ts (refreshServerStateAfterReconnect) now invalidates ['monitor-contract'], so a gateway restart that registered a contributed kind while the socket was down re-fetches the runtime contract, installs the new vocabulary, and feeds the existing re-seed that re-normalizes the affected records. Covered by a new case in serverState.reconnectDashboard.test.ts: a reconnect refetches the contract once and a contributed-kind record flips from blocked to actionable (fails without the fix).

F2 (feature-map row). The "Monitor loops" row in docs/feature-map/README.md now lists GET /api/monitor-contract and useMonitorContract ownership.

Diff vs the prior head touches only serverState.ts, that test, and the feature map.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 3, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/monitor-contract-runtime branch from e7a9cc3 to 8776beb Compare November 3, 2026 12:56
@chenmingwei23
chenmingwei23 marked this pull request as ready for review November 3, 2026 15:29
@chenmingwei23
chenmingwei23 requested review from a team and KiroCrewCaptain as code owners November 3, 2026 15:29
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 3, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

Hold for human review at 8776beb.

This adds a new dashboard route, GET /api/monitor-contract (mcp_routes.py#L677), and new routes are reserved for a human reviewer. I found no defect: the handler returns only monitor_frontend_contract() under the same cookie auth as GET /api/autonudge, the client merges the runtime kinds with the bundled ones so built-ins cannot drop out, and older gateways fall back on 404. All AI lanes pass at this head, the author answered the earlier-head findings with fixes, and checks are green.

What clears it: a maintainer confirming the new route's exposure (cookie-authed read, no strict-internal registration) is intended.

AI findings judged non-blocking:

  • UX Review: brief 'blocked' flash before the contract loads; downstream editions only, cosmetic.
  • Design Review: stale contributed kind stays actionable; in fact the set is rebuilt from bundled plus the latest payload (automation.ts#L64), and the backend refuses unknown kinds.
  • First Principles: reconnect re-fetch not described; framing only.

— crew-pr-reviewer (r144)

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 4, 2026
@chenmingwei23
chenmingwei23 force-pushed the fix/monitor-contract-runtime branch from 8776beb to 9172199 Compare November 4, 2026 15:36
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased onto current main to clear the merge conflict (route-table test pins only); no content change. New head: 9172199.

@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 4, 2026
…ed kinds are not blocked

An edition can register its own pull-request-shaped monitor kind at boot, and
the backend probes it, but the dashboard reads its kind vocabulary only from the
checked-in snapshot website/src/monitoring/contract.json. A monitor whose kind is
absent from that snapshot was rendered as blocked even while it probed normally,
with its save and restart controls disabled.

Serve the contract from the gateway at runtime and prefer it over the bundled
snapshot:

- GET /api/monitor-contract returns monitor_frontend_contract(), now built from
  the live registry (built-ins plus contributed kinds) via a new
  all_pull_request_monitor_kinds(). It is a cookie-authed read registered beside
  the other dashboard monitor reads, deliberately not on the strict-internal
  paths, so a browser reaches it under the same auth as GET /api/autonudge.
- The dashboard fetches it once (useMonitorContract, react-query) and installs
  its kind list through a runtime seam in monitoring/automation.ts that the
  record normalizer and the pull-request watch check consult. The installed set
  is bundled-union-runtime, so a payload can only add kinds, never shrink the
  built-ins. A 404 (older gateway), any fetch error, or a payload without the
  kind list all leave the bundled vocabulary in force.
- On install the hook invalidates the normalizer-fed queries and re-runs the
  authoritative automation seed, so a contributed-kind record already projected
  into Redux as blocked is re-normalized to its real state without a poll.
- Editing a contributed-kind monitor's target skips the built-in-only client
  parser (which would reject it) and sends the trimmed target for the backend's
  kind-specific validation; built-in editing and creation are unchanged, and a
  backend refusal surfaces through the existing error path.
- Reconnect refreshes the runtime contract: the reconnect invalidation list in
  serverState.ts now invalidates the monitor-contract query, so a gateway
  restart that registered a contributed kind while the socket was down installs
  the new vocabulary (and re-seeds) instead of leaving its monitors blocked
  until a page reload.
- Lists GET /api/monitor-contract and useMonitorContract ownership in the
  Monitor loops row of the feature map.

The bundled contract.json and its parity test are unchanged; with no contributed
kinds the runtime contract equals the snapshot. Built-in kinds' behaviour is
unchanged. Updates the monitor-architecture spec and the plugin docstring that
documented the gap.

Closes #25689
@chenmingwei23
chenmingwei23 force-pushed the fix/monitor-contract-runtime branch from 9172199 to 776266f Compare November 4, 2026 19:42
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Rebased onto current main to clear the merge conflict (route-table test pin only); no content change. New head: 776266f.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 4, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at 776266f.

I read every product hunk; the PR touches 26 files, most of them tests.

  • Backend: GET /api/monitor-contract returns monitor_frontend_contract(), which now lists all_pull_request_monitor_kinds(), the built-ins plus kinds registered at boot. It is a read-only route with no per-session or owner data, on the same cookie auth as GET /api/autonudge.
  • Client: useMonitorContract fetches it once with no retry, and setRuntimeMonitorContract can only add kinds to the bundled set, never remove a built-in. A 404 from an older gateway leaves the bundled contract in force. The dependent queries and the automation seed are refreshed only when the kind set grows, and a reconnect refetches the contract.
  • Editing a contributed kind skips the built-in URL parser and sends the trimmed target for the backend's own validation. Built-in kinds keep the client parser.

No regex added. All checks are green.

@bolichen97
bolichen97 merged commit 20c5654 into main Nov 4, 2026
155 of 157 checks passed
@bolichen97
bolichen97 deleted the fix/monitor-contract-runtime branch November 4, 2026 23:35
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

dashboard: serve the monitor kind list at runtime so contributed monitor kinds are not shown as blocked

3 participants