V2 workflow alerts: require acknowledgment, repeating sound, size options and team delivery (0.261.235)

[Paul Lizer (paullizer)]

Summary

• Workflow alert rules can now require acknowledgment. Such an alert keeps coming back after a refresh, in every tab and on every device, until someone selects Acknowledge or opens it. Closing it only shrinks it: V2 keeps a notice under My Workspace (in room of its own, never covering the rail items), classic keeps a banner with Review. Mark read, Dismiss and Mark all read never acknowledge. Alerts that need acknowledgment are shown before any others.
• A rule can play a sound once or repeat it every five seconds until acknowledged. Three locally bundled tones (chosen by severity) are generated by a stdlib-only script. One tab per browser sounds (shared Web Lock between classic and V2); several repeating alerts sound as one tone; Play once chimes once per browser, and alerts that arrive together chime once in the loudest tone. When autoplay is blocked the alert offers Enable sound until a sound plays. Admins control this with Enable Workflow Alert Sounds (on by default) and each device has a Play alert sounds switch.
• A rule can choose a size (small notice, medium opens the full alert, large is a full-screen takeover for wall displays), and in a group workflow can alert everyone in the group: one shared alert, one acknowledgment for everyone, "Acknowledged by name at time" in the bell, and a simpler member view (severity, workflow, matched rules, Open to what the run created in the group).
• V2 Preferences adds an Alert monitor switch for operations screens: checks every 30 s without backing off, even in a background tab. While an alert waits for acknowledgment, V2 re-checks every 20 s so an acknowledgment elsewhere stops it.

New route POST /api/notifications/<notification_id>/acknowledge (recipients only, 404 otherwise). GET /api/notifications/workflow-alerts also returns pending must-acknowledge alerts (no recency window) and team alerts from the caller's groups, with complete and sounds_enabled. Read, dismiss and acknowledge writes are now ETag-conditional with retry, so concurrent writes to a shared alert can't drop each other.

Commits after the feature

• Two review rounds. The second commit fixes 11 frontend review findings (sound follows what the store holds, Open leaves other pending alerts up, one chime per browser, pending alerts lead, the pending notice no longer covers rail items, the large dialog fills the screen, classic gives up the lock on refusal and retries refused chimes, Mark as read for ordinary alerts without links). The third fixes two more: "play once" alerts arriving together raced for the lock so a newer low alert could chime instead of an older critical one, and a V2 flyout that stepped aside could hide the next alert needing acknowledgment.
• Merged paullizer-react-v2-ui and renumbered to 0.261.235. Clearer saved-result error messages and repaired workflow test harnesses #1635 merged first as 0.261.234; this PR's release notes section, VERSION, docs and test headers now say 0.261.235.
• CodeQL notes. Removed the unused find_group_by_id import, the unused stopAllWorkflowAlertSounds helper and an unused test variable.

About the remaining CodeQL py/cyclic-import note

It reports functions_notifications → functions_group → functions_settings → content_screening.service → functions_notifications. That chain predates this PR (the base already imports functions_group at the top of functions_notifications); CodeQL reports it here because this PR edited that import line. py/cyclic-import is a recommendation-level maintainability rule that also counts imports made inside functions, and both links that close this chain are function-local (functions_settings.py lines 2254 and 2370, content_screening/service.py line 1234), so nothing can fail while modules load (py/unsafe-cyclic-import did not fire). Moving this PR's imports into functions wouldn't clear the note and would break the stub-loaded tests. New functional_tests/test_workflow_alert_notifications_import_cycle.py keeps any module-level cycle out of functions_notifications and loads the real modules cold and offline in each order the app reaches them. It can be dismissed as "won't fix", or left for a separate cleanup of the settings and screening imports.

Linked issue

Refs #1634

Release Notes & Latest Features

• New Feature
• Bug Fix
• UI Enhancement
• Breaking Change
• Internal only

Is this visible to end users?

• Yes
• No

Is this admin-facing (Admin Settings, governance, deployment, config)?

• Yes
• No

Should this become a Latest Feature card?

• Yes
• No
• Already added

Screenshot needed for the card?

• Yes
• No
• Attached

Version bump

• application/single_app/config.py VERSION third segment bumped, or not needed because this is docs-only (0.261.234 → 0.261.235; Clearer saved-result error messages and repaired workflow test harnesses #1635 took 0.261.234 first)
• deployers/version.txt bumped, or not needed because deployers/ was not changed

Testing / validation

After merging the base and the CodeQL changes (head 8f39dafad):

• python -m pytest functional_tests/test_workflow_alert_notifications_import_cycle.py — 16 passed. Mutation-checked: hoisting the two function-local imports to module level fails the static guard and the group-first cold import.
• python -m pytest on the workflow alert, notification, editor, docs-bell and route-policy functional files (the 24 files listed in the earlier run plus the new import test) — 444 passed, 1 failed: test_chat_completion_notifications.py::test_version_updated_for_feature, which requires exactly VERSION = "0.250.047" (stale, unrelated).
• python -m pytest ui_tests/test_workflow_alert_classic_acknowledgment.py ui_tests/test_v2_workflow_alerts.py — 48 passed
• node --check application/single_app/static/js/notifications.js — passed
• python scripts/check_xss_sinks.py --base-sha efee70775 --head-sha HEAD <63 changed files> — passed; python scripts/check_broken_access_control.py --base-sha efee70775 --head-sha HEAD <33 changed .py files> — passed; python scripts/check_swagger_routes.py <3 changed route files> — passed
• python functional_tests/test_docs_app_surface_coverage.py — 7/7 passed; python functional_tests/test_docs_site_quality.py — 6/6 passed

Earlier, at c78092a28 (no V2 source has changed since):

• npm --prefix application/v2_ui run typecheck and npm --prefix application/v2_ui run build — passed
• python -m pytest ui_tests/test_v2_workflow_alert_notices.py ui_tests/test_v2_notifications_bell.py ui_tests/test_v2_workflow_alerts.py — 132 passed
• python -m pytest ui_tests/test_workflow_alert_classic_acknowledgment.py — 18 passed (three consecutive runs)
• Regression tests for each review finding were mutation-checked: the 9 V2 and 4 classic tests from the second commit fail against the first, and the 4 V2 and 2 classic tests from the third fail against the second.

Not run, or failing for reasons unrelated to this change:

• Live UI tests that need SIMPLECHAT_UI_BASE_URL (a running, signed-in app) were skipped.
• test_notification_polling_redirect_guard.py is stale on the base branch too: it expects the notifications comment directly after {% if session.get('user') %} and a notifications.js tag without ?v=, and the base already has completion-audio-cues.js between them and the cache-buster.
• test_workflow_priority_alerts.py (CosmosClient credentials when config.py is imported) and test_group_notification_context.py (needs live Cosmos DB) need Azure configuration.
• Earlier OpenSSL failures (module 'lib' has no attribute 'GEN_EMAIL') came from a cryptography 50 / pyOpenSSL 25.3 mismatch in my local Python, not from the app; with a compatible cryptography those tests pass.

Known risks and limitations:

• After each page load, sound waits for a click or key press unless the browser policy allows the site to autoplay (AutoplayAllowlist in Edge and Chrome, documented). The alert itself always shows.
• Each of the alert reads is capped (V2 asks for 10, classic for 5). If more must-acknowledge alerts are pending than one read returns, the rest wait their turn: complete keeps them from being retired, and they appear as the others are acknowledged.
• A group manager's rule can make every member's browser sound. Admins can turn sounds off and each device can mute; there is no per-member opt-out from team alerts yet.
• Members other than the owner see a simplified alert by design (the full alert describes the owner's side of the run).

Documentation

• Release notes updated, or not needed
• Feature documentation updated, or not needed
• Fix documentation updated, or not needed

New docs/explanation/features/WORKFLOW_ALERT_ACKNOWLEDGMENT.md; updated WORKFLOW_ALERT_RULES.md, V2_WORKFLOW_ALERT_NOTICES.md, V2_WORKFLOW_ALERT_EDITING.md, WORKFLOW_PRIORITY_ALERTS.md, the create-a-workflow, manage-notifications and update-profile-preferences guides, docs/admin/workflow.md, docs/_data/features.yml and docs/_data/app_surface.yml, and a v0.261.235 release notes section.

Security checklist

• New Flask routes include @swagger_route(security=get_auth_security())
• Settings sent to non-admin frontends use sanitize_settings_for_user()
• Browser JavaScript is served from local SimpleChat static assets only; no CDN-hosted JS
• No secrets, keys, connection strings, or local-only artifacts are included