/platform/docs/UI-REFRESH-VERIFICATION.md

UI Refresh — Verification & Test Plan

Companion to UI-REFRESH-SPEC.md. Defines the test cases, the manual checks, and the acceptance bar for each phase. The implementing agent must land these (green) alongside the code. Several integration tests depend on the FakeSlack harness (FAKE-SLACK-SPEC.md) — build that first.

How to run

• Python: ./.runtests.sh platform/tests/<file> -q (uses the agent-platform venv). Whole suite: ./.runtests.sh platform/tests/ -q. Baseline is green except 3 pre-existing SDK-import failures (test_anthropic_provider, test_gemini_provider, test_provider_router) — unrelated; don't "fix" by mocking the SDK.
• Frontend: cd platform/surfaces/gui && npx tsc --noEmit (must be clean) and npm run build.
• Server under the aisuite venv: PYTHONPATH=platform /Users/rohit/fleet/ro4d/aisuite/platform/.venv/bin/python -m coworker.server.run --port 8765. Dev GUI on :1420 defaults to backend 8765.

Conventions

• Backend unit tests use ScriptedProvider + SessionManager(workspace=tmp_path, provider=…) and TestClient(create_app(mgr)) (see test_session_events.py, test_subscriptions.py).
• Messaging integration tests use FakeSlack instead of the network: point the Slack adapter at the fake, drive inbound/button events through the fake's control API, assert on outbound calls it recorded. No COWORKER_DEBUG_INJECT, no real tokens.

---

Phase 1 — connector registry + contract

Unit

• test_descriptor_brand_logo: every descriptor exposes brand_color (hex) + logo; /v1/connectors surfaces them; an unknown/placeholder connector still returns a color (fallback gray) + logo.
• test_placeholder_connectors_listed: github/datadog/salesforce/hubspot/pagerduty appear as available:false so personas can recommend them; they have no connect.
• test_slack_resolve_channel_name: _channel_name(id) returns the resolved name, caches (one conversations.info call for repeats), returns None on failure. (Pattern mirrors the existing test_slack_resolves_and_caches_display_name.)

Frontend

• ConnectorIcon/ConnectorBadge renders the registry SVG for a known id and the fallback for an unknown id; brand color applied from prop. (Component test or a Storybook-style render assertion.)

Manual: Integrations → Connectors shows correct logos/colors incl. a placeholder (e.g. Datadog) with the fallback-or-brand badge.

---

Phase 2 — structured connector messages

Unit

• test_inbound_builds_message_source: _dispatch_inbound of a channel MessageEvent (with user_name, chat_name set) delivers to the subscribed session with a MessageSource (connector/kind/channel_id/channel_name/sender_id/sender_name/ts/text).
• test_message_source_persisted_and_stripped: after the turn, GET /v1/sessions/{id}/messages returns the user message with source; the provider received the framed text and no source/unknown keys (assert against the ScriptedProvider's captured messages).
• test_turn_start_carries_source: the WS turn_start event for a delivered connector message includes source (register a fake session client, like test_session_events.py).
• test_dm_message_source_kind_dm: a DM yields kind="dm".

Frontend

• itemsFromMessages maps a message with source.connector to a connector item; turn_start with source renders ConnectorMessageCard (not a plain bubble). Hover swaps names→ids.

Manual (FakeSlack): post a channel message via FakeSlack → the session's open view shows the connector card live (names, hover→ids, ts); reselect the session → the card persists (re-rendered from /messages).

---

Phase 3 — connection hierarchy

Unit (test_connections.py, new)

• test_persona_defaults_seeded_from_manifest: PersonaConnectionStore.defaults_for(ops, manifest) → core+connected recommends on, others off; persisted after first read.
• test_effective_resolution: with connected={slack,github}, persona-default {slack:on, github:on, datadog:off}, session override {slack:off} → effective {github:on} (slack muted, datadog not connected).
• test_session_override_clear_inherits: clearing a session override returns to persona default.
• test_remove_session_clears_overrides: deleting a session drops its overrides.

Runtime gating

• test_muted_connector_not_delivered: a session subscribed to a Slack channel but with Slack muted (session override off) does not receive _dispatch_inbound for that channel (still buffered).
• test_muted_connector_tools_absent: building that session's engine omits the connector's tools.
• test_dm_muted_session_not_delivered: DM routed to a session with the connector muted is parked/ skipped, not delivered.

Manual: in a session's Sources drawer, toggle Slack off → posting in the subscribed channel no longer wakes the session; toggle on → it resumes. Confirm the persona-level default is unchanged.

---

Phase 4 — persona + session connection surfaces

Unit (TestClient)

• test_persona_detail_endpoint: GET /v1/personas/ops returns identity, tools, recommends with connected annotated, and default_connections.
• test_persona_set_default_connection: POST /v1/personas/ops/connections {github,false} flips the persona default; reflected in the next GET and in new sessions' effective set.
• test_persona_enable_toggle: POST /v1/personas/ops/enable {false} removes it from the /v1/personas picker list.
• test_session_connections_endpoint: GET /v1/sessions/{id}/connections returns connected + recommended + attention = count of not-yet-connected recommends.
• test_session_set_override: POST /v1/sessions/{id}/connections {slack,false} sets the override; effective resolution + GET reflect it.

Frontend

• PersonaView renders detail from the endpoint; toggling a default connection POSTs and re-reads.
• SourcesBar shows ⚠ N = attention; opening the drawer lists connected (with working toggles) + recommended (Connect/Add).

Manual: open a persona's gear → detail page shows recommends with reasons + connect state + the "new sessions get by default" toggles; flip one and start a new session of that persona → the default is reflected in its Sources drawer.

---

Phase 5 — frontend polish

Frontend / manual

• Integrations sub-nav (Connectors/Messaging/Activity/MCP); the three messaging controls live under "Messaging routing"; Unrouted under "Activity".
• Sidebar layout toggle persists across reload (prefs nav_layout); grouped view shows bounded per-persona cards with a working gear.
• New-session split button: primary starts last/default persona; ▾ lists enabled personas + opens PersonaView via "Manage personas…".
• StepGroup: tool/approval items render collapsed ("N actions · M approvals ✓"), expandable.
• npx tsc --noEmit clean; npm run build succeeds.

---

Cross-cutting acceptance (end-to-end, via FakeSlack)

A single scripted scenario the FakeSlack harness can drive, asserting the whole refresh:

1. Connect Slack (against FakeSlack); allow a user; subscribe the Ops "incident" session to a channel.
2. Post a channel message → session shows the connector card live (resolved names).
3. Agent proposes a tool needing approval; session is Unattended with approvals routed to a channel → FakeSlack receives a Block Kit card; inject the Approve click → turn resumes, reply posts back to the origin channel (FakeSlack records the outbound).
4. Mute Slack for the session in the drawer → a further channel post does not wake it.
5. GET /v1/sessions/{id}/connections attention matches the persona's unconnected recommends.

This scenario lives as test_ui_refresh_e2e.py against FakeSlack and is the merge gate.

Regression bar

• Whole suite green (minus the 3 known SDK-import failures).
• No real-network calls in tests (grep the diff for slack.com, real tokens — there should be none outside FakeSlack config).
• tsc --noEmit clean; npm run build passes.