From 4f06d30e0758a6f8ef9fa345e86ab42f823a73e0 Mon Sep 17 00:00:00 2001 From: Jason Walker <913443@dadeschools.net> Date: Sat, 25 Jul 2026 16:41:16 -0400 Subject: [PATCH 1/2] feat(webui): implement notifications and human-attention routing (#648) --- docs/webui-notifications.md | 81 +++++ tests/test_webui_notifications.py | 276 +++++++++++++++++ webui/app.py | 25 ++ webui/nav.py | 1 + webui/notification_views.py | 158 ++++++++++ webui/notifications.py | 480 ++++++++++++++++++++++++++++++ 6 files changed, 1021 insertions(+) create mode 100644 docs/webui-notifications.md create mode 100644 tests/test_webui_notifications.py create mode 100644 webui/notification_views.py create mode 100644 webui/notifications.py diff --git a/docs/webui-notifications.md b/docs/webui-notifications.md new file mode 100644 index 0000000..7ef2e05 --- /dev/null +++ b/docs/webui-notifications.md @@ -0,0 +1,81 @@ +# Web Console: Notifications & Human-Attention Routing (#648) + +- **Status:** Phase 3 Live +- **Tracking Issue:** [#648](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/648) +- **Parent Epic:** [#631](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/631) +- **Attention Boundary Reference:** [#628](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/628) + +--- + +## 1. Overview + +The **Notifications & Human-Attention Console** (`/notifications`, `/api/v1/notifications`) provides intelligent event classification and human-attention routing for autonomous workflow operations. + +To prevent alert fatigue while ensuring critical escalation boundaries are never missed, events are classified into three distinct **Attention Classes**: + +1. **`human-required`** (Urgent Escalation Boundary): + - Items requiring immediate human intervention or business decisions. + - Triggers: Auth failures, hard stops, irrecoverable state, decision locks, failed report validations, critical probe errors. + - Display: Highlighted in red (`badge-blocked`) with a `HUMAN REQUIRED` badge. + +2. **`operator`** (Operational Inbox): + - Items requiring controller or operator review/triage during routine execution. + - Triggers: Blocked PRs (merge conflicts), stale leases, duplicate PRs on issues, unassigned ready work. + - Display: Displayed in orange/yellow (`badge-claimed`). + +3. **`routine`** (Background Workflow Transitions): + - Normal, healthy workflow transitions and state progressions. + - Triggers: Active PRs/issues in standard state, clean branch creation, routine heartbeats. + - Display: Filtered out of default inbox views to eliminate notification spam; viewable on demand via the "Routine" or "All" tab. + +--- + +## 2. API Endpoints + +### `GET /api/v1/notifications` +*Compatibility Alias:* `GET /api/notifications` + +#### Query Parameters: +- `project_id` (optional): Filter notifications by project ID. +- `attention_class` (optional): `inbox` (default: human-required + operator), `human-required`, `operator`, `routine`, `all`. + +#### Example JSON Response: +```json +{ + "project_id": "gitea-tools", + "repo_label": "Scaled-Tech-Consulting/Gitea-Tools", + "human_required_count": 0, + "operator_count": 2, + "routine_count": 5, + "total_count": 7, + "fetch_error": null, + "inbox_items": [ + { + "id": "notif-pr-block-742", + "attention_class": "operator", + "category": "blocker", + "title": "Blocked PR #742", + "summary": "PR #742 requires merge conflict resolution.", + "work_kind": "pr", + "work_number": 742, + "project_id": "gitea-tools", + "repo_label": "Scaled-Tech-Consulting/Gitea-Tools", + "created_at": "2026-07-25T16:39:47Z", + "deep_link": "/traffic", + "requires_human": false, + "extra": {} + } + ], + "all_items": [...] +} +``` + +--- + +## 3. UI Navigation + +- Access via the **Traffic** navigation menu: **Traffic → Notifications**. +- The main view displays: + - **Metrics Summary Bar**: Highlighting counts for Human Required, Operator Inbox, and Routine items. + - **Attention Filter Tabs**: Toggle between Inbox (Human + Operator), Human Required, Operator, Routine, and All. + - **Structured Event Table**: Displays category, title, summary, work item links, and timestamps. diff --git a/tests/test_webui_notifications.py b/tests/test_webui_notifications.py new file mode 100644 index 0000000..db89d4c --- /dev/null +++ b/tests/test_webui_notifications.py @@ -0,0 +1,276 @@ +"""Unit tests for Phase 3 Notifications and Human-Attention Console (#648).""" + +from __future__ import annotations + +import pytest +from starlette.testclient import TestClient + +from webui.app import create_app +from webui.notifications import ( + ATTENTION_HUMAN_REQUIRED, + ATTENTION_OPERATOR, + ATTENTION_ROUTINE, + CATEGORY_AUTH, + CATEGORY_BLOCKER, + CATEGORY_LEASE, + CATEGORY_SYSTEM, + CATEGORY_VALIDATION, + CATEGORY_WORKFLOW, + NotificationItem, + NotificationSnapshot, + classify_attention_event, + load_notifications_snapshot, + snapshot_to_dict, +) +from webui.notification_views import render_notifications_page +from webui.project_registry import load_registry +from webui.queue_loader import QueueItem, QueueSnapshot +from webui.lease_loader import CollisionWarning, LeaseSnapshot +from webui.system_health import DependencyProbe, SystemHealthSnapshot, VersionInfo, StaleRuntime + + +def test_classify_attention_event_rules(): + # 1. Critical escalation boundaries -> human-required + att_cls, req_human = classify_attention_event( + CATEGORY_AUTH, "Auth error", "Unauthorized access attempt", is_auth_failure=True + ) + assert att_cls == ATTENTION_HUMAN_REQUIRED + assert req_human is True + + att_cls, req_human = classify_attention_event( + CATEGORY_SYSTEM, "Hard stop", "Hard stop triggered", is_hard_stop=True + ) + assert att_cls == ATTENTION_HUMAN_REQUIRED + assert req_human is True + + att_cls, req_human = classify_attention_event( + CATEGORY_VALIDATION, "Validation Error", "Report validation failed", is_validation_failure=True + ) + assert att_cls == ATTENTION_HUMAN_REQUIRED + assert req_human is True + + # 2. Operational issues -> operator + att_cls, req_human = classify_attention_event( + CATEGORY_BLOCKER, "PR Blocked", "Merge conflict detected", is_blocker=True + ) + assert att_cls == ATTENTION_OPERATOR + assert req_human is False + + att_cls, req_human = classify_attention_event( + CATEGORY_LEASE, "Lease Expired", "Session lease expired", is_stale=True + ) + assert att_cls == ATTENTION_OPERATOR + assert req_human is False + + # 3. Routine workflow transitions -> routine + att_cls, req_human = classify_attention_event( + CATEGORY_WORKFLOW, "PR Active", "PR in review" + ) + assert att_cls == ATTENTION_ROUTINE + assert req_human is False + + +def test_notification_snapshot_aggregation(): + reg = load_registry() + proj_id = reg.projects[0].id if reg.projects else "gitea-tools" + + mock_queue = QueueSnapshot( + project_id=proj_id, + repo_label="org/repo", + prs=( + QueueItem( + number=101, + title="Blocked PR", + badges=("blocked",), + extra={}, + ), + QueueItem( + number=102, + title="Normal PR", + badges=("in-review",), + extra={}, + ), + ), + issues=(), + pr_pagination=None, + issue_pagination=None, + ) + + mock_leases = LeaseSnapshot( + project_id=proj_id, + repo_label="org/repo", + issue_lock=None, + claim_inventory={}, + reviewer_leases=( + { + "pr_number": 101, + "status": "expired", + "is_expired": True, + }, + ), + duplicate_prs=( + CollisionWarning( + kind="duplicate_pr", + message="Multiple open PRs for issue #101", + issue_number=101, + pr_numbers=(101, 103), + ), + ), + duplicate_branches=(), + collision_history=(), + fetch_error=None, + ) + + mock_version = VersionInfo( + git_sha="abc1234", + git_describe="v1.0.0", + control_plane_schema_version=1, + python_version="3.11", + known=True, + ) + + mock_stale = StaleRuntime( + daemon_head="abc1234", + checkout_head="abc1234", + remote_head="abc1234", + stale=False, + determinable=True, + mutation_safe=True, + reasons=(), + ) + + mock_health = SystemHealthSnapshot( + status="degraded", + ready=False, + readiness_complete=True, + readiness_reasons=("Auth failure",), + service="webui", + mode="test", + version=mock_version, + started_at="2026-07-25T00:00:00Z", + uptime_seconds=100.0, + timestamp="2026-07-25T00:00:00Z", + deep_probes_requested=True, + dependencies=( + DependencyProbe( + name="auth_service", + kind="auth", + status="unauthorized", + detail="Token expired", + required=True, + ), + ), + mcp_namespaces=(), + stale_runtime=mock_stale, + probe_errors=(), + ) + + snapshot = load_notifications_snapshot( + proj_id, + load_queue=lambda _id: mock_queue, + load_leases=lambda **_kwargs: mock_leases, + load_health=lambda **_kwargs: mock_health, + ) + + assert snapshot.project_id == proj_id + assert snapshot.total_count == 5 + assert snapshot.human_required_count >= 1 # auth probe failure + assert snapshot.operator_count >= 3 # blocked PR + expired lease + duplicate PR collision + assert snapshot.routine_count >= 1 # normal PR + + # Inbox items should include operator and human-required items only + inbox_classes = {item.attention_class for item in snapshot.inbox_items} + assert ATTENTION_ROUTINE not in inbox_classes + assert ATTENTION_OPERATOR in inbox_classes + assert ATTENTION_HUMAN_REQUIRED in inbox_classes + + +def test_snapshot_to_dict_and_redaction(): + item = NotificationItem( + id="notif-1", + attention_class=ATTENTION_HUMAN_REQUIRED, + category=CATEGORY_AUTH, + title="Auth Error", + summary="Failed auth header: Bearer secret_token_12345", + work_kind="system", + work_number=None, + project_id="test-proj", + repo_label="org/repo", + created_at="2026-07-25T16:00:00Z", + requires_human=True, + ) + snap = NotificationSnapshot( + project_id="test-proj", + repo_label="org/repo", + items=(item,), + human_required_count=1, + operator_count=0, + routine_count=0, + total_count=1, + ) + + data = snapshot_to_dict(snap) + assert data["project_id"] == "test-proj" + assert data["human_required_count"] == 1 + assert len(data["inbox_items"]) == 1 + + # Redaction test + summary = data["inbox_items"][0]["summary"] + assert "secret_token_12345" not in summary + assert "" in summary or "Bearer" in summary + + +def test_notifications_html_views(): + item = NotificationItem( + id="notif-1", + attention_class=ATTENTION_HUMAN_REQUIRED, + category=CATEGORY_AUTH, + title="Critical Auth Failure", + summary="Auth failure details", + work_kind="issue", + work_number=42, + project_id="test-proj", + repo_label="org/repo", + created_at="2026-07-25T16:00:00Z", + requires_human=True, + ) + snap = NotificationSnapshot( + project_id="test-proj", + repo_label="org/repo", + items=(item,), + human_required_count=1, + operator_count=0, + routine_count=0, + total_count=1, + ) + + html = render_notifications_page(snap, filter_class="inbox") + assert "Notifications & Attention Inbox" in html or "Notifications & Attention Inbox" in html + assert "Critical Auth Failure" in html + assert "HUMAN REQUIRED" in html + assert "Human Required" in html + + +def test_notifications_app_routes(): + app = create_app() + client = TestClient(app) + + # 1. HTML Route + res = client.get("/notifications") + assert res.status_code == 200 + assert "Notifications" in res.text + assert "Attention Inbox" in res.text + + # 2. API Route /api/v1/notifications + res_api = client.get("/api/v1/notifications") + assert res_api.status_code == 200 + json_data = res_api.json() + assert "human_required_count" in json_data + assert "operator_count" in json_data + assert "routine_count" in json_data + assert "inbox_items" in json_data + + # 3. Compatibility Alias /api/notifications + res_alias = client.get("/api/notifications") + assert res_alias.status_code == 200 + assert res_alias.json()["project_id"] == json_data["project_id"] diff --git a/webui/app.py b/webui/app.py index 560ec75..3840874 100644 --- a/webui/app.py +++ b/webui/app.py @@ -72,6 +72,11 @@ from webui.system_health import ( snapshot_to_dict as system_health_to_dict, ) from webui.system_health_views import render_system_health_page +from webui.notifications import ( + load_notifications_snapshot, + snapshot_to_dict as notifications_snapshot_to_dict, +) +from webui.notification_views import render_notifications_page _READ_ONLY_METHODS = frozenset({"GET", "HEAD", "OPTIONS"}) _AUDIT_MUTATION_PATHS = frozenset({"/audit", "/api/audit"}) @@ -739,6 +744,23 @@ async def api_v1_analytics_ingest(request: Request) -> JSONResponse: ) +async def notifications_route(request: Request) -> HTMLResponse: + project_id = request.query_params.get("project_id") + attention_class = request.query_params.get("attention_class") or "inbox" + snap = load_notifications_snapshot(project_id) + html = render_notifications_page( + snap, filter_class=attention_class, filter_project=project_id + ) + return HTMLResponse(html) + + +async def api_notifications(request: Request) -> JSONResponse: + project_id = request.query_params.get("project_id") + snap = load_notifications_snapshot(project_id) + data = notifications_snapshot_to_dict(snap) + return JSONResponse(data) + + async def method_not_allowed(request: Request, _exc: Exception) -> Response: path = request.url.path if path in _AUDIT_MUTATION_PATHS and request.method == "POST": @@ -767,6 +789,9 @@ def create_app(*, bind_host: str | None = None) -> Starlette: Route("/api/queue", api_queue, methods=["GET"]), Route("/traffic", traffic, methods=["GET"]), Route("/api/traffic", api_traffic, methods=["GET"]), + Route("/notifications", notifications_route, methods=["GET"]), + Route("/api/notifications", api_notifications, methods=["GET"]), + Route("/api/v1/notifications", api_notifications, methods=["GET"]), Route("/projects", projects, methods=["GET"]), Route("/projects/{project_id}", project_detail, methods=["GET"]), Route("/api/projects", api_projects, methods=["GET"]), diff --git a/webui/nav.py b/webui/nav.py index da9f763..b9165e9 100644 --- a/webui/nav.py +++ b/webui/nav.py @@ -45,6 +45,7 @@ NAV_GROUPS: tuple[NavGroup, ...] = ( NavItem("/queue", "Queue"), NavItem("/leases", "Leases"), NavItem("/actions", "Actions"), + NavItem("/notifications", "Notifications"), )), NavGroup("Runtime/Sessions", ( NavItem("/runtime", "Runtime health"), diff --git a/webui/notification_views.py b/webui/notification_views.py new file mode 100644 index 0000000..e4b6ab9 --- /dev/null +++ b/webui/notification_views.py @@ -0,0 +1,158 @@ +"""HTML rendering for Phase 3 Notifications and Human-Attention Console (#648).""" + +from __future__ import annotations + +from html import escape +from typing import Sequence + +from webui.layout import render_page +from webui.notifications import ( + ATTENTION_HUMAN_REQUIRED, + ATTENTION_OPERATOR, + ATTENTION_ROUTINE, + NotificationItem, + NotificationSnapshot, +) + + +def _render_attention_badge(attention_class: str) -> str: + cls = "badge" + if attention_class == ATTENTION_HUMAN_REQUIRED: + cls += " badge-blocked" + elif attention_class == ATTENTION_OPERATOR: + cls += " badge-claimed" + else: + cls += " muted" + return f'{escape(attention_class)}' + + +def _render_notification_row(item: NotificationItem) -> str: + category_label = escape(item.category.upper()) + id_str = escape(item.id) + title_str = escape(item.title) + summary_str = escape(item.summary) + att_badge = _render_attention_badge(item.attention_class) + + work_item_html = "—" + if item.work_number and item.work_kind: + kind_label = escape(item.work_kind.upper()) + num_str = f"#{item.work_number}" + link = item.deep_link or "#" + work_item_html = f'{kind_label} {num_str}' + + requires_human_label = ( + 'HUMAN REQUIRED' + if item.requires_human + else "" + ) + + return f""" + {category_label}
{id_str} + +
{title_str} {att_badge} {requires_human_label}
+
{summary_str}
+ + {work_item_html} + {escape(item.created_at[:19])} +""" + + +def _render_notifications_table(items: Sequence[NotificationItem], empty_message: str) -> str: + if not items: + return f'

{escape(empty_message)}

' + + rows = "".join(_render_notification_row(item) for item in items) + return f""" + + + + + + + + + + {rows} + +
Category & IDTitle & Attention SummaryWork ItemTime
""" + + +def render_notifications_page( + snapshot: NotificationSnapshot, + *, + filter_class: str = "inbox", + filter_project: str | None = None, +) -> str: + """Render the notifications and attention inbox page.""" + title = "Notifications & Attention Inbox" + + err_html = "" + if snapshot.fetch_error: + err_html = f'

Fetch Warning: {escape(snapshot.fetch_error)}

' + + # Determine items to render based on filter_class + if filter_class == ATTENTION_HUMAN_REQUIRED: + display_items = snapshot.human_required_items + active_tab_title = "Human-Required Escalations" + elif filter_class == ATTENTION_OPERATOR: + display_items = snapshot.operator_items + active_tab_title = "Operator Inbox Items" + elif filter_class == ATTENTION_ROUTINE: + display_items = snapshot.routine_items + active_tab_title = "Routine Workflow Transitions" + elif filter_class == "all": + display_items = snapshot.items + active_tab_title = "All Events (including Routine)" + else: # "inbox" default + display_items = snapshot.inbox_items + active_tab_title = "Attention Inbox (Human + Operator)" + + hr_cls = "badge-blocked" if snapshot.human_required_count > 0 else "muted" + op_cls = "badge-claimed" if snapshot.operator_count > 0 else "muted" + + metrics_html = f"""
+
+ Human Required +

{snapshot.human_required_count}

+

Critical escalation boundary

+
+
+ Operator Inbox +

{snapshot.operator_count}

+

Operational items needing review

+
+
+ Routine Transitions +

{snapshot.routine_count}

+

Background transitions (filtered)

+
+
""" + + # Filter navigation links + def _tab_link(target_class: str, label: str) -> str: + is_active = (filter_class == target_class) + style = "font-weight:bold; border-bottom:2px solid currentColor;" if is_active else "color:#4a5568;" + return f'{label}' + + tabs_html = f"""
+ {_tab_link("inbox", f"Attention Inbox ({snapshot.human_required_count + snapshot.operator_count})")} + {_tab_link("human-required", f"Human Required ({snapshot.human_required_count})")} + {_tab_link("operator", f"Operator ({snapshot.operator_count})")} + {_tab_link("routine", f"Routine ({snapshot.routine_count})")} + {_tab_link("all", f"All Events ({snapshot.total_count})")} +
""" + + table_html = _render_notifications_table( + display_items, + f"No items match attention filter '{filter_class}'.", + ) + + body = f"""

{escape(title)}

+

Phase 3 console surface for human-attention routing (#648). Routine workflow transitions are filtered by default to eliminate notification fatigue.

+{err_html} +{metrics_html} +{tabs_html} +

{escape(active_tab_title)}

+{table_html}""" + + return render_page(title=title, body_html=body) diff --git a/webui/notifications.py b/webui/notifications.py new file mode 100644 index 0000000..15753b9 --- /dev/null +++ b/webui/notifications.py @@ -0,0 +1,480 @@ +"""Notifications and human-attention routing module for Phase 3 web console (#648). + +Defines attention classes, event classification rules, and inbox aggregation so +operators receive direct alerts only for human-required escalation boundaries +(#628) while routine workflow transitions remain available for pull-based review. +""" + +from __future__ import annotations + +import os +from dataclasses import dataclass, field +from datetime import datetime, timezone +from typing import Any, Callable, Sequence + +from webui import console_redaction +from webui.project_registry import find_project, load_registry +from webui.queue_loader import QueueSnapshot, load_queue_snapshot +from webui.lease_loader import LeaseSnapshot, load_lease_snapshot +from webui.system_health import SystemHealthSnapshot, load_system_health + +# Attention class definitions (#628, #648) +ATTENTION_ROUTINE = "routine" +ATTENTION_OPERATOR = "operator" +ATTENTION_HUMAN_REQUIRED = "human-required" + +ATTENTION_CLASSES = ( + ATTENTION_ROUTINE, + ATTENTION_OPERATOR, + ATTENTION_HUMAN_REQUIRED, +) + +# Notification categories +CATEGORY_AUTH = "auth" +CATEGORY_BLOCKER = "blocker" +CATEGORY_LEASE = "lease" +CATEGORY_VALIDATION = "validation" +CATEGORY_WORKFLOW = "workflow" +CATEGORY_SYSTEM = "system" + +CATEGORIES = ( + CATEGORY_AUTH, + CATEGORY_BLOCKER, + CATEGORY_LEASE, + CATEGORY_VALIDATION, + CATEGORY_WORKFLOW, + CATEGORY_SYSTEM, +) + + +@dataclass(frozen=True) +class NotificationItem: + """A single notification or inbox event.""" + + id: str + attention_class: str # "routine", "operator", "human-required" + category: str # "auth", "blocker", "lease", "validation", etc. + title: str + summary: str + work_kind: str | None # "issue", "pr", "session", "system" + work_number: int | None + project_id: str + repo_label: str + created_at: str + deep_link: str | None = None + requires_human: bool = False + extra: dict[str, Any] = field(default_factory=dict) + + def as_dict(self) -> dict[str, Any]: + return { + "id": self.id, + "attention_class": self.attention_class, + "category": self.category, + "title": self.title, + "summary": console_redaction.redact_text(self.summary), + "work_kind": self.work_kind, + "work_number": self.work_number, + "project_id": self.project_id, + "repo_label": self.repo_label, + "created_at": self.created_at, + "deep_link": self.deep_link, + "requires_human": self.requires_human, + "extra": self.extra, + } + + +@dataclass(frozen=True) +class NotificationSnapshot: + """Snapshot of notifications and attention inbox state.""" + + project_id: str + repo_label: str + items: tuple[NotificationItem, ...] + human_required_count: int + operator_count: int + routine_count: int + total_count: int + fetch_error: str | None = None + + @property + def inbox_items(self) -> tuple[NotificationItem, ...]: + """Items requiring operator or human attention (excluding routine).""" + return tuple( + item + for item in self.items + if item.attention_class in {ATTENTION_OPERATOR, ATTENTION_HUMAN_REQUIRED} + ) + + @property + def human_required_items(self) -> tuple[NotificationItem, ...]: + return tuple( + item for item in self.items if item.attention_class == ATTENTION_HUMAN_REQUIRED + ) + + @property + def operator_items(self) -> tuple[NotificationItem, ...]: + return tuple( + item for item in self.items if item.attention_class == ATTENTION_OPERATOR + ) + + @property + def routine_items(self) -> tuple[NotificationItem, ...]: + return tuple( + item for item in self.items if item.attention_class == ATTENTION_ROUTINE + ) + + def as_dict(self) -> dict[str, Any]: + return { + "project_id": self.project_id, + "repo_label": self.repo_label, + "human_required_count": self.human_required_count, + "operator_count": self.operator_count, + "routine_count": self.routine_count, + "total_count": self.total_count, + "fetch_error": self.fetch_error, + "inbox_items": [item.as_dict() for item in self.inbox_items], + "all_items": [item.as_dict() for item in self.items], + } + + +def classify_attention_event( + category: str, + title: str, + summary: str, + *, + is_hard_stop: bool = False, + is_auth_failure: bool = False, + is_irrecoverable: bool = False, + is_decision_lock: bool = False, + is_validation_failure: bool = False, + is_stale: bool = False, + is_blocker: bool = False, +) -> tuple[str, bool]: + """Classify an event into an attention class and human requirement flag. + + Rules (#628, #648): + 1. Critical boundaries (hard stop, auth failure, irrecoverable state, + decision lock, validation failure) -> ATTENTION_HUMAN_REQUIRED (requires_human=True). + 2. Operational queues (blocker, stale lease, unassigned ready work, queue collision) + -> ATTENTION_OPERATOR (requires_human=False). + 3. Routine state transitions (clean progression, healthy heartbeats) -> ATTENTION_ROUTINE (requires_human=False). + """ + if ( + is_hard_stop + or is_auth_failure + or is_irrecoverable + or is_decision_lock + or is_validation_failure + or category in {CATEGORY_AUTH, CATEGORY_VALIDATION} + or "hard stop" in summary.lower() + or "unauthorized" in summary.lower() + or "irrecoverable" in summary.lower() + ): + return ATTENTION_HUMAN_REQUIRED, True + + if is_stale or is_blocker or category in {CATEGORY_BLOCKER, CATEGORY_LEASE}: + return ATTENTION_OPERATOR, False + + return ATTENTION_ROUTINE, False + + +def load_notifications_snapshot( + project_id: str | None = None, + *, + load_queue: Callable[..., QueueSnapshot] | None = None, + load_leases: Callable[..., LeaseSnapshot] | None = None, + load_health: Callable[..., SystemHealthSnapshot] | None = None, +) -> NotificationSnapshot: + """Load and classify attention notifications across queue, leases, and system health.""" + registry = load_registry() + project = None + if project_id: + for entry in registry.projects: + if entry.id == project_id: + project = entry + break + else: + project = registry.projects[0] if registry.projects else None + + if project is None: + return NotificationSnapshot( + project_id=project_id or "", + repo_label="", + items=(), + human_required_count=0, + operator_count=0, + routine_count=0, + total_count=0, + fetch_error="project not found in registry", + ) + + queue_loader_fn = load_queue or load_queue_snapshot + lease_loader_fn = load_leases or load_lease_snapshot + health_loader_fn = load_health or load_system_health + + try: + queue_snap = queue_loader_fn(project.id) + except TypeError: + queue_snap = queue_loader_fn(project_id=project.id) + + try: + lease_snap = lease_loader_fn(project_id=project.id) + except TypeError: + lease_snap = lease_loader_fn(project.id) + + try: + health_snap = health_loader_fn(project_id=project.id) + except TypeError: + try: + health_snap = health_loader_fn(project.id) + except TypeError: + health_snap = health_loader_fn() + + items: list[NotificationItem] = [] + now_iso = datetime.now(timezone.utc).isoformat() + + # 1. System health alerts (highest priority) + for probe_err in getattr(health_snap, "probe_errors", ()): + att_cls, req_human = classify_attention_event( + CATEGORY_SYSTEM, + "System Health Probe Error", + probe_err, + is_blocker=True, + ) + items.append( + NotificationItem( + id=f"notif-sys-err-{project.id}", + attention_class=att_cls, + category=CATEGORY_SYSTEM, + title="System Health Error", + summary=f"System health error: {probe_err}", + work_kind="system", + work_number=None, + project_id=project.id, + repo_label=f"{project.gitea_owner}/{project.repo_name}", + created_at=now_iso, + deep_link="/system", + requires_human=req_human, + ) + ) + + for probe in getattr(health_snap, "dependencies", ()): + if probe.status not in ("ok", "healthy"): + att_cls, req_human = classify_attention_event( + CATEGORY_SYSTEM, + f"Probe Failure: {probe.name}", + probe.detail or probe.status, + is_hard_stop=("stop" in probe.status or "fatal" in probe.status), + is_auth_failure=("auth" in probe.name.lower() or "unauthorized" in probe.status.lower()), + is_blocker=True, + ) + items.append( + NotificationItem( + id=f"notif-probe-{probe.name}", + attention_class=att_cls, + category=CATEGORY_AUTH if "auth" in probe.name.lower() else CATEGORY_SYSTEM, + title=f"Health Probe Alert: {probe.name}", + summary=f"Probe '{probe.name}' reported status '{probe.status}': {probe.detail}", + work_kind="system", + work_number=None, + project_id=project.id, + repo_label=f"{project.gitea_owner}/{project.repo_name}", + created_at=now_iso, + deep_link="/system", + requires_human=req_human, + ) + ) + + # 2. Queue items (PRs and Issues) + for pr in queue_snap.prs: + if "blocked" in pr.badges: + att_cls, req_human = classify_attention_event( + CATEGORY_BLOCKER, + f"PR #{pr.number} Blocked", + f"PR #{pr.number} '{pr.title}' is blocked or has merge conflicts.", + is_blocker=True, + ) + items.append( + NotificationItem( + id=f"notif-pr-block-{pr.number}", + attention_class=att_cls, + category=CATEGORY_BLOCKER, + title=f"Blocked PR #{pr.number}", + summary=f"PR #{pr.number} ({pr.title}) requires merge conflict resolution.", + work_kind="pr", + work_number=pr.number, + project_id=project.id, + repo_label=f"{project.gitea_owner}/{project.repo_name}", + created_at=now_iso, + deep_link=f"/traffic", + requires_human=req_human, + ) + ) + elif "stale" in pr.badges: + att_cls, req_human = classify_attention_event( + CATEGORY_WORKFLOW, + f"PR #{pr.number} Stale", + f"PR #{pr.number} '{pr.title}' has had no activity for over 14 days.", + is_stale=True, + ) + items.append( + NotificationItem( + id=f"notif-pr-stale-{pr.number}", + attention_class=att_cls, + category=CATEGORY_WORKFLOW, + title=f"Stale PR #{pr.number}", + summary=f"PR #{pr.number} ({pr.title}) is stale.", + work_kind="pr", + work_number=pr.number, + project_id=project.id, + repo_label=f"{project.gitea_owner}/{project.repo_name}", + created_at=now_iso, + deep_link=f"/queue", + requires_human=req_human, + ) + ) + else: + # Routine PR transition + att_cls, req_human = classify_attention_event( + CATEGORY_WORKFLOW, + f"PR #{pr.number} Active", + f"PR #{pr.number} '{pr.title}' is in routine state {', '.join(pr.badges)}.", + ) + items.append( + NotificationItem( + id=f"notif-pr-routine-{pr.number}", + attention_class=att_cls, + category=CATEGORY_WORKFLOW, + title=f"Routine PR #{pr.number}", + summary=f"PR #{pr.number} ({pr.title}) state: {', '.join(pr.badges)}.", + work_kind="pr", + work_number=pr.number, + project_id=project.id, + repo_label=f"{project.gitea_owner}/{project.repo_name}", + created_at=now_iso, + deep_link=f"/queue", + requires_human=req_human, + ) + ) + + for issue in queue_snap.issues: + if "duplicate" in issue.badges: + att_cls, req_human = classify_attention_event( + CATEGORY_BLOCKER, + f"Issue #{issue.number} Duplicate PRs", + f"Issue #{issue.number} has multiple linked PRs.", + is_blocker=True, + ) + items.append( + NotificationItem( + id=f"notif-issue-dup-{issue.number}", + attention_class=att_cls, + category=CATEGORY_BLOCKER, + title=f"Duplicate PRs on Issue #{issue.number}", + summary=f"Issue #{issue.number} ({issue.title}) linked to multiple PRs.", + work_kind="issue", + work_number=issue.number, + project_id=project.id, + repo_label=f"{project.gitea_owner}/{project.repo_name}", + created_at=now_iso, + deep_link=f"/traffic", + requires_human=req_human, + ) + ) + elif "claimed" in issue.badges or "in-review" in issue.badges: + att_cls, req_human = classify_attention_event( + CATEGORY_WORKFLOW, + f"Issue #{issue.number} Active", + f"Issue #{issue.number} '{issue.title}' in state {', '.join(issue.badges)}.", + ) + items.append( + NotificationItem( + id=f"notif-issue-routine-{issue.number}", + attention_class=att_cls, + category=CATEGORY_WORKFLOW, + title=f"Routine Issue #{issue.number}", + summary=f"Issue #{issue.number} ({issue.title}) state: {', '.join(issue.badges)}.", + work_kind="issue", + work_number=issue.number, + project_id=project.id, + repo_label=f"{project.gitea_owner}/{project.repo_name}", + created_at=now_iso, + deep_link=f"/queue", + requires_human=req_human, + ) + ) + + # 3. Leases / Collisions + for lease in lease_snap.reviewer_leases: + if lease.get("is_expired") or lease.get("status") == "expired": + pr_num = lease.get("pr_number") or lease.get("work_item_number") + att_cls, req_human = classify_attention_event( + CATEGORY_LEASE, + f"Reviewer Lease Expired for PR #{pr_num}", + f"Reviewer lease for PR #{pr_num} has expired.", + is_stale=True, + ) + items.append( + NotificationItem( + id=f"notif-lease-exp-pr-{pr_num}", + attention_class=att_cls, + category=CATEGORY_LEASE, + title=f"Expired Reviewer Lease (PR #{pr_num})", + summary=f"Reviewer lease for PR #{pr_num} expired.", + work_kind="pr", + work_number=pr_num, + project_id=project.id, + repo_label=f"{project.gitea_owner}/{project.repo_name}", + created_at=now_iso, + deep_link="/leases", + requires_human=req_human, + ) + ) + + for collision in lease_snap.duplicate_prs: + att_cls, req_human = classify_attention_event( + CATEGORY_BLOCKER, + f"Duplicate PR Collision ({collision.kind})", + collision.message, + is_blocker=True, + ) + items.append( + NotificationItem( + id=f"notif-collision-{collision.issue_number or 0}", + attention_class=att_cls, + category=CATEGORY_BLOCKER, + title=f"Collision Alert ({collision.kind})", + summary=collision.message, + work_kind="issue" if collision.issue_number else "pr", + work_number=collision.issue_number, + project_id=project.id, + repo_label=f"{project.gitea_owner}/{project.repo_name}", + created_at=now_iso, + deep_link="/leases", + requires_human=req_human, + ) + ) + + human_req_count = sum(1 for i in items if i.attention_class == ATTENTION_HUMAN_REQUIRED) + operator_count = sum(1 for i in items if i.attention_class == ATTENTION_OPERATOR) + routine_count = sum(1 for i in items if i.attention_class == ATTENTION_ROUTINE) + + fetch_err = queue_snap.fetch_error or lease_snap.fetch_error or getattr(health_snap, "probe_errors", None) + if isinstance(fetch_err, (tuple, list)): + fetch_err = "; ".join(fetch_err) if fetch_err else None + + return NotificationSnapshot( + project_id=project.id, + repo_label=f"{project.gitea_owner}/{project.repo_name}", + items=tuple(items), + human_required_count=human_req_count, + operator_count=operator_count, + routine_count=routine_count, + total_count=len(items), + fetch_error=fetch_err, + ) + + +def snapshot_to_dict(snapshot: NotificationSnapshot) -> dict[str, Any]: + """JSON-serializable export for /api/v1/notifications.""" + return snapshot.as_dict() -- 2.43.7 From a64ba08e274975e6a0a4f001241196b4f9e40485 Mon Sep 17 00:00:00 2001 From: Jason Walker <913443@dadeschools.net> Date: Sat, 25 Jul 2026 18:26:46 -0400 Subject: [PATCH 2/2] fix(webui): address #905 REQUEST_CHANGES on notifications classifier MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit B1: classify_attention_event uses structured flags/category only — never substring-match human-authored title/summary for escalation. B2: make notification ids unique across probe_errors and collisions (include loop index / kind). B3: do not assign probe_errors to fetch_error (avoids false Fetch Warning and double-reporting). Regression tests cover all three blockers. Refs #648 --- tests/test_webui_notifications.py | 189 ++++++++++++++++++++++++++++++ webui/notifications.py | 28 +++-- 2 files changed, 206 insertions(+), 11 deletions(-) diff --git a/tests/test_webui_notifications.py b/tests/test_webui_notifications.py index db89d4c..c928f7a 100644 --- a/tests/test_webui_notifications.py +++ b/tests/test_webui_notifications.py @@ -274,3 +274,192 @@ def test_notifications_app_routes(): res_alias = client.get("/api/notifications") assert res_alias.status_code == 200 assert res_alias.json()["project_id"] == json_data["project_id"] + + +def test_classify_ignores_human_authored_title_and_summary_keywords(): + """B1: keywords in human-authored titles must not escalate routine work (#905).""" + # Routine transition whose title/summary mention critical-boundary words + att_cls, req_human = classify_attention_event( + CATEGORY_WORKFLOW, + "record irrecoverable decision lock provenance", + "PR #999 'record irrecoverable decision lock provenance' is in routine state in-review.", + ) + assert att_cls == ATTENTION_ROUTINE + assert req_human is False + + att_cls, req_human = classify_attention_event( + CATEGORY_WORKFLOW, + "fix unauthorized token path", + "Issue #1 'fix unauthorized token path' state: claimed. hard stop docs only.", + ) + assert att_cls == ATTENTION_ROUTINE + assert req_human is False + + # Structured flags still escalate (machine-driven) + att_cls, req_human = classify_attention_event( + CATEGORY_SYSTEM, + "anything", + "anything with hard stop in text", + is_hard_stop=True, + ) + assert att_cls == ATTENTION_HUMAN_REQUIRED + assert req_human is True + + +def test_notification_ids_are_unique_across_probe_errors_and_collisions(): + """B2: published notification ids must be unique within a snapshot (#905).""" + reg = load_registry() + proj_id = reg.projects[0].id if reg.projects else "gitea-tools" + + mock_queue = QueueSnapshot( + project_id=proj_id, + repo_label="org/repo", + prs=(), + issues=(), + pr_pagination=None, + issue_pagination=None, + ) + mock_leases = LeaseSnapshot( + project_id=proj_id, + repo_label="org/repo", + issue_lock=None, + claim_inventory={}, + reviewer_leases=(), + duplicate_prs=( + CollisionWarning( + kind="duplicate_pr", + message="Multiple open PRs for issue #10", + issue_number=10, + pr_numbers=(10, 11), + ), + CollisionWarning( + kind="duplicate_branch", + message="Another collision without issue", + issue_number=None, + pr_numbers=(12, 13), + ), + CollisionWarning( + kind="duplicate_pr", + message="Second issue collision", + issue_number=10, + pr_numbers=(14, 15), + ), + ), + duplicate_branches=(), + collision_history=(), + fetch_error=None, + ) + mock_version = VersionInfo( + git_sha="abc1234", + git_describe="v1.0.0", + control_plane_schema_version=1, + python_version="3.11", + known=True, + ) + mock_stale = StaleRuntime( + daemon_head="abc1234", + checkout_head="abc1234", + remote_head="abc1234", + stale=False, + determinable=True, + mutation_safe=True, + reasons=(), + ) + mock_health = SystemHealthSnapshot( + status="degraded", + ready=False, + readiness_complete=True, + readiness_reasons=(), + service="webui", + mode="test", + version=mock_version, + started_at="2026-07-25T00:00:00Z", + uptime_seconds=100.0, + timestamp="2026-07-25T00:00:00Z", + deep_probes_requested=True, + dependencies=(), + mcp_namespaces=(), + stale_runtime=mock_stale, + probe_errors=("error alpha", "error beta"), + ) + + snapshot = load_notifications_snapshot( + proj_id, + load_queue=lambda _id: mock_queue, + load_leases=lambda **_kwargs: mock_leases, + load_health=lambda **_kwargs: mock_health, + ) + ids = [item.id for item in snapshot.items] + assert len(ids) == len(set(ids)), f"duplicate notification ids: {ids}" + assert any(i.startswith(f"notif-sys-err-{proj_id}-") for i in ids) + assert any(i.startswith("notif-collision-") for i in ids) + + +def test_probe_errors_do_not_set_fetch_error(): + """B3: probe_errors must not be reported as fetch_error (#905).""" + reg = load_registry() + proj_id = reg.projects[0].id if reg.projects else "gitea-tools" + + mock_queue = QueueSnapshot( + project_id=proj_id, + repo_label="org/repo", + prs=(), + issues=(), + pr_pagination=None, + issue_pagination=None, + fetch_error=None, + ) + mock_leases = LeaseSnapshot( + project_id=proj_id, + repo_label="org/repo", + issue_lock=None, + claim_inventory={}, + reviewer_leases=(), + duplicate_prs=(), + duplicate_branches=(), + collision_history=(), + fetch_error=None, + ) + mock_version = VersionInfo( + git_sha="abc1234", + git_describe="v1.0.0", + control_plane_schema_version=1, + python_version="3.11", + known=True, + ) + mock_stale = StaleRuntime( + daemon_head="abc1234", + checkout_head="abc1234", + remote_head="abc1234", + stale=False, + determinable=True, + mutation_safe=True, + reasons=(), + ) + mock_health = SystemHealthSnapshot( + status="degraded", + ready=False, + readiness_complete=True, + readiness_reasons=(), + service="webui", + mode="test", + version=mock_version, + started_at="2026-07-25T00:00:00Z", + uptime_seconds=100.0, + timestamp="2026-07-25T00:00:00Z", + deep_probes_requested=True, + dependencies=(), + mcp_namespaces=(), + stale_runtime=mock_stale, + probe_errors=("probe blew up",), + ) + + snapshot = load_notifications_snapshot( + proj_id, + load_queue=lambda _id: mock_queue, + load_leases=lambda **_kwargs: mock_leases, + load_health=lambda **_kwargs: mock_health, + ) + assert snapshot.fetch_error is None + # probe errors still appear as items + assert any("probe blew up" in item.summary for item in snapshot.items) diff --git a/webui/notifications.py b/webui/notifications.py index 15753b9..9dd8e90 100644 --- a/webui/notifications.py +++ b/webui/notifications.py @@ -7,13 +7,12 @@ operators receive direct alerts only for human-required escalation boundaries from __future__ import annotations -import os from dataclasses import dataclass, field from datetime import datetime, timezone -from typing import Any, Callable, Sequence +from typing import Any, Callable from webui import console_redaction -from webui.project_registry import find_project, load_registry +from webui.project_registry import load_registry from webui.queue_loader import QueueSnapshot, load_queue_snapshot from webui.lease_loader import LeaseSnapshot, load_lease_snapshot from webui.system_health import SystemHealthSnapshot, load_system_health @@ -158,7 +157,13 @@ def classify_attention_event( 2. Operational queues (blocker, stale lease, unassigned ready work, queue collision) -> ATTENTION_OPERATOR (requires_human=False). 3. Routine state transitions (clean progression, healthy heartbeats) -> ATTENTION_ROUTINE (requires_human=False). + + Classification uses structured flags and category only. Human-authored + ``title`` / ``summary`` text is never substring-matched for escalation + (PR #905 review B1) — callers that need text signals must set flags from + machine-generated status/detail fields before calling this function. """ + del title, summary # kept for API stability; never used for classification if ( is_hard_stop or is_auth_failure @@ -166,9 +171,6 @@ def classify_attention_event( or is_decision_lock or is_validation_failure or category in {CATEGORY_AUTH, CATEGORY_VALIDATION} - or "hard stop" in summary.lower() - or "unauthorized" in summary.lower() - or "irrecoverable" in summary.lower() ): return ATTENTION_HUMAN_REQUIRED, True @@ -234,7 +236,7 @@ def load_notifications_snapshot( now_iso = datetime.now(timezone.utc).isoformat() # 1. System health alerts (highest priority) - for probe_err in getattr(health_snap, "probe_errors", ()): + for err_idx, probe_err in enumerate(getattr(health_snap, "probe_errors", ())): att_cls, req_human = classify_attention_event( CATEGORY_SYSTEM, "System Health Probe Error", @@ -243,7 +245,7 @@ def load_notifications_snapshot( ) items.append( NotificationItem( - id=f"notif-sys-err-{project.id}", + id=f"notif-sys-err-{project.id}-{err_idx}", attention_class=att_cls, category=CATEGORY_SYSTEM, title="System Health Error", @@ -431,16 +433,18 @@ def load_notifications_snapshot( ) ) - for collision in lease_snap.duplicate_prs: + for col_idx, collision in enumerate(lease_snap.duplicate_prs): att_cls, req_human = classify_attention_event( CATEGORY_BLOCKER, f"Duplicate PR Collision ({collision.kind})", collision.message, is_blocker=True, ) + issue_part = collision.issue_number if collision.issue_number is not None else "none" + kind_part = (collision.kind or "unknown").replace(" ", "-") items.append( NotificationItem( - id=f"notif-collision-{collision.issue_number or 0}", + id=f"notif-collision-{kind_part}-{issue_part}-{col_idx}", attention_class=att_cls, category=CATEGORY_BLOCKER, title=f"Collision Alert ({collision.kind})", @@ -459,7 +463,9 @@ def load_notifications_snapshot( operator_count = sum(1 for i in items if i.attention_class == ATTENTION_OPERATOR) routine_count = sum(1 for i in items if i.attention_class == ATTENTION_ROUTINE) - fetch_err = queue_snap.fetch_error or lease_snap.fetch_error or getattr(health_snap, "probe_errors", None) + # Fetch errors are transport/load failures only — not probe results that + # already surface as first-class notification items (PR #905 review B3). + fetch_err = queue_snap.fetch_error or lease_snap.fetch_error if isinstance(fetch_err, (tuple, list)): fetch_err = "; ".join(fetch_err) if fetch_err else None -- 2.43.7