Improve the Control Center dashboard and add Chat with this dashboard

[Paul Lizer (paullizer)]

Summary

An admin review of the V2 Control Center Dashboard found four problems: rankings showed GUIDs, DAU/WAU/MAU were labelled only "unique users", the token filters sat at the top of the page so they looked page-wide but changed only the token charts, and Chat with these trends failed with HTTP 401 for every admin.

• The dashboard reads clearly. Top token consumers and Most active show names (users with their email, the ID on hover, deleted groups and workspaces labelled). The page is split into Directory, Sign-ins, Conversations and documents, Token usage and Most active, and every figure says what it counts; DAU/WAU/MAU name the end date and window. The token filters now sit inside Token usage, say they change only that section, and have Clear filters.
• Drill-through opens the right records. Sign-ins and conversations have separate charts, a click on a stacked bar opens the segment under the pointer instead of the first series, token drill-throughs keep the filters, and links only appear for sections the viewer can open.
• Chat with this dashboard replaces the broken trends chat. When everything is set up, it opens a new chat with Orchestrate on and a prompt describing the dashboard's dates and token filters, ready to edit and send. Otherwise it shows a checklist marking each requirement Ready or Needs set-up, with what to do and, for admins, a link to the setting.
• A new read-only Control Center action answers usage questions in chat from the same aggregation as the dashboard, so the numbers match. Only Control Center dashboard viewers can see or run it.

Design notes for review

• Shared aggregation. functions_control_center_dashboard.py (standard library only) now holds the dashboard aggregation used by both the V2 summary/insights routes, which become thin wrappers, and the action. The 90-second cache is split into an activity half keyed by date range and a token half keyed by date range plus token filters, so changing a token filter recomputes only token figures. Names come from cached point reads, and every query passes the Cosmos query guard.
• Action access is enforced three times. The control_center type is global-only (ensure_action_type_access refuses it in personal and group scope). functions_action_catalog.py lists and resolves it only when the caller's roles grant can_view_dashboard. Each function re-checks capabilities from the signed-in session, so scheduled runs fail closed. Orchestration call sites now pass the caller's captured roles explicitly (functions_orchestration_*, route_backend_orchestration.py); that threading deserves a careful look.
• Readiness API. GET /api/v2/control-center/dashboard/chat-readiness (login plus Control Center dashboard access) reports requirement states, never setting values, returns settings links only to admins, and is sent with Cache-Control: no-store. The browser renders only allowlisted /admin/settings/<section> and /admin/actions paths.
• Prompt hand-off. The prompt reaches the composer through router state only (composerDraftHandoff.ts) and is applied once, so a URL cannot prefill anyone's composer and a reload does not reapply it.
• Removed endpoint. POST /api/admin/control-center/activity-trends/chat and the classic page's chat modal and script are gone. The route read session['user_id'], which is never set (hence the 401), wrote a malformed conversation, and V2 linked to a non-existent /chat/<id>; the classic modal had no button that opened it. The classic activity-trends GET and CSV export are unchanged.
• Small supporting routes. /admin/settings/:sectionId deep links and a one-shot ?type= preselect in the action editor, used by the checklist links.

Linked issue

N/A (no issue was filed for this work)

Release Notes & Latest Features

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

Is this visible to end users?

• Yes
• No

Only Control Center admins and dashboard readers see the dashboard, the chat button and the action.

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
• deployers/version.txt bumped, or not needed because deployers/ was not changed

VERSION is 0.261.297; the base branch is at 0.261.296. deployers/ is unchanged.

Testing / validation

All run on the final branch, after merging the latest paullizer-react-v2-ui, with the V2 SPA rebuilt for the UI tests.

• python -m pytest -q -p no:cacheprovider --continue-on-collection-errors functional_tests/test_v2_control_center_dashboard.py functional_tests/test_v2_control_center_action.py functional_tests/test_orchestration_action_catalog.py functional_tests/test_v2_control_center_cosmos_query_compatibility.py functional_tests/test_control_center_token_filters.py functional_tests/test_v2_api_security.py functional_tests/route_tests/test_route_blueprint_policy_inventory.py functional_tests/route_tests/test_route_unauthenticated_policy_contract.py functional_tests/route_tests/test_route_policy_test_coverage.py functional_tests/test_docs_app_surface_coverage.py functional_tests/test_docs_site_quality.py: 154 passed, 1 failed. The failure, test_config_version_bumped_for_token_filters, asserts the exact version 0.239.164 and fails on the base branch too.
• python functional_tests/test_v2_control_center_action.py: 18/18 passed. python -O -m pytest -q functional_tests/test_v2_control_center_action.py: 18 passed.
• python -m pytest -q -p no:cacheprovider functional_tests/test_workspace_authoring_backend.py: 58 passed, 80 failed. The same 80 tests fail on the current base (f34094ae5) in this environment, all with the route's generic HTTP 503.
• npm --prefix application/v2_ui run typecheck and npm --prefix application/v2_ui run build: passed.
• python -m pytest -q -m ui ui_tests/test_v2_control_center_dashboard.py: 6 passed (sections and definitions, names, token filter scope, capability-aware links, sign-in and stacked-segment drill-through, requirements checklist and Check again, prompt hand-off into an orchestrated chat that a reload does not reapply).
• python -m pytest -q -m ui on the other 16 ui_tests/*control_center*.py files (V2 and classic): 35 passed, 11 skipped (live-environment tests).
• python -m pytest -q -m ui ui_tests/test_v2_admin_global_agents_actions.py ui_tests/test_v2_admin_governance_settings.py ui_tests/test_v2_admin_settings_rail_collapse.py ui_tests/test_v2_admin_settings_wide_layout.py ui_tests/test_v2_orchestration_composer.py ui_tests/test_v2_orchestration_actions.py ui_tests/test_v2_workspace_authoring.py ui_tests/test_v2_group_actions.py: 177 passed, 12 failed. The 12 are MCP/OpenAPI action-editor tests in test_v2_workspace_authoring.py and test_v2_group_actions.py; the same 12 fail on a build of the base branch (49a52bb5c) without this branch's changes.
• python -m pytest -q -m ui ui_tests/test_v2_prompt_composer_experience.py: 56 passed.
• python scripts/check_xss_sinks.py --base-sha origin/paullizer-react-v2-ui --head-sha HEAD <changed UI files>, python scripts/check_broken_access_control.py --full-file <changed Python files> and python scripts/check_swagger_routes.py application/single_app/route_backend_control_center.py: passed.
• python scripts/build_docs_inventory.py: regenerated docs/_data/app_surface.yml.
• functional_tests/test_logging_tag_standardization.py fails on the base branch too, for unrelated tags; the new [CONTROL_CENTER_ACTION] tag is documented in docs/reference/logging-tags.md.
• Not validated against a live deployment: the UI tests run the built SPA against mocked APIs.

Documentation

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

New: docs/explanation/features/CONTROL_CENTER_ACTION.md, docs/explanation/fixes/V2_CONTROL_CENTER_DASHBOARD_USABILITY_FIX.md, docs/reference/actions/control-center.md. Updated: V2_CONTROL_CENTER.md, docs/guides/v2-control-center.md, docs/admin/agents-actions.md, docs/admin/orchestration.md, the actions index, logging tags and release notes (0.261.297).

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

The readiness route sends derived requirement states and labels, not settings values. The new action runs fixed, parameterized, bounded reads, writes nothing, and maps storage errors to a generic message.