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

UI Refresh — Implementation Spec

Status: ready to implement. Audience: the implementing agent (has full repo access). Scope: full-stack (data model → stores → connector contract → gateway → REST/WS → React). Backward compatibility: none required — pre-launch, no users. Redesign cleanly; migrate on-disk state by deletion if needed.

Companion docs

• UX rationale + decisions: UX-DECISIONS.md (the why; don't violate it).
• Visual spec: ../ui-mocks/redesign.html (the look).
• Tests + acceptance: UI-REFRESH-VERIFICATION.md.
• Test harness: FAKE-SLACK-SPEC.md (separate deliverable — build first; the verification suite depends on it).

Throughout, → marks a file to change. Verify signatures against current code before editing.

---

0. Principles

1. One connector contract, Slack is the reference. No Slack special-casing in the core. Every connector adapter implements the same interface (§2); Slack-specific mechanics (Socket Mode, Web API, Block Kit, name resolution) live behind it. New connectors (Salesforce, HubSpot, …) implement the contract and "just work" in the UI via the registry (§1).
2. Structured, not stringly-typed. Connector inbound messages become structured records carrying identities + display names (§3), so the GUI renders rich cards and the model still gets framed text. No parsing of "💬 New message on slack:C…" in the frontend.
3. Connection hierarchy (UX §4, Decided): account-connected → persona-default-enabled → session-override. Effective = connected AND persona-default(unless session override) AND not session-disabled (§4).
4. Names everywhere, ids on hover. Resolve + cache id → display name for users and channels at the connector boundary (§2.3); persist names with messages.

---

1. Connector registry metadata (brand color + logo)

Goal: the UI renders any connector by logo id + brand_color, with a neutral fallback.

Backend

• → coworker/connectors/descriptors.py: add to ConnectorDescriptor:
  • brand_color: str = "#6b7280" (hex; the connector's brand, fallback gray)
  • logo: str = "" (a stable logo id, e.g. "slack", "github"; empty → fallback)
  • Populate for slack/telegram and the not-yet-shipped ones referenced by personas (github, datadog, salesforce, hubspot, pagerduty) — descriptors may exist as available:false placeholders so recommendations can render. (A placeholder descriptor = id, title, icon, blurb, brand_color, logo, available=False, two_way as appropriate, no connect.)
• → coworker/connectors/setup.py::connector_list: include brand_color, logo per connector.

Frontend

• → surfaces/gui/src/connectors/registry.ts (new): CONNECTORS: Record<string, {label; logo}> mapping logo id → an imported SVG component, plus FALLBACK. A <ConnectorIcon connector=…/> and <ConnectorBadge/> component reads brand_color from API data and the SVG from the registry; unknown id → fallback plug glyph + the provided/neutral color. (Mirror the mock's CONNECTORS object + data-brand tinting.)
• Logos are bundled frontend SVG assets keyed by id; brand color comes from the API so it's one source of truth.

---

2. Connector contract (the abstraction)

Define the interface every adapter satisfies. Today BasePlatformAdapter + SlackAdapter/ TelegramAdapter (coworker/connectors/adapters.py) and Gateway (gateway.py) already cover most of this; this section formalizes + extends it.

2.1 Interface (adapter)

class PlatformAdapter:
    platform: str
    brand: ConnectorBrand            # {color, logo} (mirror descriptor)
    async def connect() -> bool
    async def disconnect() -> None
    async def send(chat_id, text, *, thread_id=None) -> SendResult
    async def send_interactive(chat_id, text, buttons: list[Button]) -> str   # returns message id
    async def update_message(chat_id, message_id, text, *, buttons=None) -> None
    async def resolve_user_name(user_id) -> str | None      # cached (§2.3)
    async def resolve_channel_name(chat_id) -> str | None    # cached (§2.3)
    # inbound: adapter calls gateway handlers with MessageEvent / InteractionEvent

Slack already implements connect/disconnect/send/_display_name; add send_interactive, update_message (currently on senders/gateway — keep, but route through the adapter), and resolve_channel_name. Telegram implements the subset it supports (no buttons → send_interactive falls back to text + numbered replies, already partially present).

2.2 Inbound event shape

• → coworker/connectors/base.py: extend SessionSource with chat_name: Optional[str] = None (channel/DM display name; user_name already exists). MessageEvent already carries text, source, message_id (the ts). Adapters MUST populate user_name + chat_name (resolved, §2.3) before handing the event to the gateway.
• _dispatch_inbound (§3) builds the structured MessageSource from these.

2.3 Name resolution + cache

• Slack adapter has _display_name (users.info, cached). Add _channel_name (conversations.info, cached) with the same pattern; both keyed by id, in-memory dict, best-effort (None on failure, caller falls back to id). A short TTL is optional (names rarely change) — start with no expiry, re-resolved on process restart.
• Cache lives on the adapter instance. The gateway's recent-senders map (gateway._record_recent) already stores user_name; ensure it's the resolved name.

---

3. Structured connector inbound messages (rich card)

Today a connector message reaches a session as a framed text blob. Make it structured so the GUI renders a card (logo + channel/person names + hover ids + ts) while the model still sees framed text.

3.1 Data

• → coworker/connectors/base.py (or a new messages.py): MessageSource dataclass:

  connector: str         # platform id, e.g. "slack"
  kind: str              # "channel" | "dm"
  channel_id: str        # e.g. "C0BD7KZ1AH5"
  channel_name: str      # e.g. "#ocw-test"  (resolved; falls back to id)
  sender_id: str
  sender_name: str       # resolved; falls back to id
  ts: float              # epoch seconds
  text: str              # the RAW message (what the card shows)
  

• The persisted user message gains an optional sidecar. Decide the storage seam by reading coworker/engine.py + the conversation/session store:
  • The model-facing content stays the framed text (so replay keeps the agent's instructions: "💬 New message on {channel} from {sender}: {text}\n(You're subscribed… reply with send_message…)").
  • Attach source (the MessageSource) to that message record for display only. Persist it; strip it before sending to the provider (providers must not receive unknown keys). The cleanest approach: store transcript messages as the existing dicts plus a parallel message_meta[index] or an ocw_source key that the provider serializer drops. Pick whichever matches the current message model with least friction; document the choice in the PR.

3.2 Plumbing

• → coworker/server/manager.py:
  • deliver_to_session(session_id, message, *, source: MessageSource | None = None). When source is set, the engine records the user message with the framed text and the source sidecar.
  • _dispatch_inbound: build MessageSource (resolved names from the event) and pass it through for both the channel-subscription path and the DM path.
• → coworker/engine.py: run(...) / the user-message append path accepts the optional source and stores it on the recorded user message; TURN_START event data includes source (so the live render shows the card immediately — see §1 event bus already broadcasts turn_start).
• → coworker/server/app.py:
  • GET /v1/sessions/{id}/messages: each message includes source when present.
  • WS turn_start: include source in the event data (already forwards input).

3.3 Frontend

• → surfaces/gui/src/components/ConnectorMessageCard.tsx (new): renders header (ConnectorBadge + channel_name + sender_name + relative time + "via {label}") with an id-on-hover swap (channel_id · sender_id), body = source.text. Brand-tinted header + left edge (mock parity).
• → surfaces/gui/src/App.tsx: the conversation item model gains an optional source. In itemsFromMessages and the turn_start handler, when a user message has source.connector, push a { kind: "connector", source } item rendered by ConnectorMessageCard instead of the plain user bubble. (Generalizes to Salesforce/HubSpot via the registry.)

---

4. Connection hierarchy (data model) — UX §4

Three layers. No backward compat: replace the current global per-connector enabled semantics.

4.1 Layers

1. account-connected — a connector profile with valid creds exists (secrets[<name>:default]). Unchanged (connector_list[].connected).
2. persona-default-enabled — per persona, which connected connectors are on by default for its sessions. User-editable (persona detail page), seeded from the manifest.
3. session-override — per session, explicit on/off overriding the persona default.

Effective(session, connector) = connected AND session_override[c] if present else persona_default[persona, c].

4.2 Stores (JSON, mirror SubscriptionStore/UnroutedStore)

• → coworker/connections.py (new):
  • PersonaConnectionStore(path) — {persona_id: {connector: bool}}. defaults_for(persona_id, manifest): if no stored row, seed from the manifest — a recommends item with tier: core whose connector is connected → default on; everything else off. set(persona_id, connector, bool), get(persona_id).
  • SessionConnectionStore(path) — {session_id: {connector: bool}} (overrides only; absence = inherit). set/clear(session_id, connector, bool|None), get(session_id). remove_session(id) on delete (like subscriptions).
  • effective(session_id, persona_id, *, connected: set[str]) -> dict[str, bool] — the resolver.
• Manager owns both: self.persona_connections, self.session_connections.

4.3 Runtime gating

The effective set must actually change behavior:

• Inbound (_dispatch_inbound): a channel subscription belongs to a session; deliver only if the source connector is effective-enabled for that session. A muted connector → skip delivery (still buffer for catch-up).
• Outbound/tools: when building a session's engine, expose a connector's tools only if effective-enabled for that session (extend the existing connector-tool gating that already checks global enabled/experimental — read agent.py / catalog / _enabled_connector_tools).
• DM routing: a DM to the designated session is delivered only if that session has the connector effective-enabled.

---

5. Persona surface (recommends + detail page)

Manifest recommends already exists (coworker/personas/manifest.py, Recommendation). Surface it

• the persona-default connections + identity to the GUI.

Backend → coworker/server/app.py + coworker/personas/registry.py + manager:

• GET /v1/personas/{id} → identity (id, name, icon, tagline, description), tools, recommended_models, default_permission_mode, workspace, enabled (persona on/off), recommends: [{kind, ref, reason, tier, connected: bool}] (annotate connected from connector_list), and default_connections: [{connector, enabled, connected}] (from PersonaConnectionStore.defaults_for).
• POST /v1/personas/{id}/connections {connector, enabled} → set persona default.
• POST /v1/personas/{id}/enable {enabled} → enable/disable the persona (persona registry already tracks enabled/surfaced; reuse it).
• GET /v1/personas (list) already exists for the picker — ensure it returns enabled personas with icon + name + tagline.

Frontend → surfaces/gui/src/components/PersonaView.tsx (new): the detail page (mock parity) — identity + Enable toggle, About, capabilities (tools), "Connections for full benefit" (recommends, core/optional + reason + connect state), "New sessions get by default" (default_connections toggles), defaults. Opened from the grouped-nav gear and the New-session menu's "Manage personas…" (UX §9).

---

6. Per-session connections (Sources bar + drawer)

Backend → coworker/server/app.py + manager:

• GET /v1/sessions/{id}/connections →
  • connected: [{connector, enabled, detail}] — effective-enabled connectors for the session, with a short detail (e.g. Slack: "#ocw-test · DMs"). enabled reflects the session override/persona default so the drawer toggle shows correct state.
  • recommended: [{connector, reason, tier, connected}] — the persona's recommends not yet connected (drives the ⚠ N count = len(recommended where not connected)).
  • attention: int — the ⚠ N.
• POST /v1/sessions/{id}/connections {connector, enabled} → set the session override (mute/unmute). Clearing back to inherit = send enabled matching the persona default, or add a clear flag.

Frontend → surfaces/gui/src/components/SourcesBar.tsx + SourcesDrawer.tsx (new):

• Sources bar: icons-only avatar stack + ⚠ N badge (UX §3); click opens the drawer.
• Drawer: persona why-connect blurb (from GET /v1/personas/{id}), Connected (with enable toggles → POST …/connections), Recommended connectors + MCP (Connect/Add), link to global Integrations.

---

7. Frontend — views, components, state

• Session view: add the Sources bar (§6) under the title; render ConnectorMessageCard (§3.3); wrap tool/approval items in a collapsed <details>-style StepGroup ("N actions · M approvals") — pure frontend grouping of existing tool_*/permission_*/approval items (UX §2b).
• Per-session drawer (§6) + Persona detail page (§5) as new routed surfaces; generalize the view switch (mock uses session/integrations/persona).
• Integrations → surfaces/gui/src/components/IntegrationsView.tsx: restructure into a left sub-nav: Connectors · Messaging routing · Activity · MCP (UX §6). Move the existing DM-route/subscriptions/approvals-routing controls under "Messaging routing"; Unrouted under "Activity"; allow-list stays inline on the Slack connector card.
• Sidebar → Sidebar.tsx: dual layout (flat ↔ grouped-by-persona) toggled by an icon by the wordmark; grouped = bounded per-persona cards with a gear → PersonaView (UX §7). Persist the choice in prefs (GET/POST the existing settings/prefs; add nav_layout).
• New session: split button — primary = last/default persona; ▾ = enabled personas (from /v1/personas) + "Manage personas…" (UX §8).
• api.ts: add typed clients + interfaces for every endpoint in §§3,5,6 and the connector brand_color/logo fields; add MessageSource, PersonaDetail, SessionConnections.

---

8. REST/WS contract (net-new / changed)

Method	Path	Purpose
GET	/v1/connectors	+ brand_color, logo per connector (§1)
GET	/v1/sessions/{id}/messages	+ source on connector messages (§3)
WS	turn_start	+ source in event data (§3)
GET	/v1/personas/{id}	identity + recommends(+connected) + default_connections (§5)
POST	/v1/personas/{id}/connections	set persona-default connection (§5)
POST	/v1/personas/{id}/enable	enable/disable persona (§5)
GET	/v1/sessions/{id}/connections	connected + recommended + ⚠ count (§6)
POST	/v1/sessions/{id}/connections	set session override (§6)
GET/POST	settings nav_layout	persist flat/grouped nav (§7)

---

9. Build phases (suggested)

1. Foundation: connector registry metadata (§1) + connector contract tidy-up (§2, incl. resolve_channel_name). Land FakeSlack (separate deliverable) so later phases test deterministically.
2. Structured messages (§3) — backend + ConnectorMessageCard. High user-visible value.
3. Connection hierarchy (§4) — stores + resolver + runtime gating. The core data-model change.
4. Persona + session surfaces (§5, §6) — APIs + PersonaView + SourcesBar/Drawer.
5. Frontend polish (§7) — Integrations sub-nav, dual nav, split button, StepGroup.

Each phase: code + tests (see VERIFICATION) green before the next. Commit per phase.