EPIC — Unified native Copilot, voice-chat continuity, and visual CI #360

New issue

Open

opened 2026-09-08 02:03:39 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-08 02:03:39 +00:00

Owner

Research: docs/research/002-unified-copilot-voice-visual-ci.md
Research branch: research/unified-copilot-20260905
Research baseline: 16b1eda8dd4a0b1e4a3dba7742787e8a75192347

Goal

Replace Zara's current two-chat-window desktop presentation model with one canonical adaptive native Copilot, make voice conversation sessions first-class durable chats, and make screenshot evidence a normal part of UI CI/review.

This epic changes presentation/lifecycle ownership. It must not create another assistant runtime, daemon protocol, conversation database, voice stack, Prolog stack, or provider configuration path.

Research findings

DesktopController currently owns both FullChatWindow and QuickCopilotWindow and manually resynchronizes them through one ConversationService.
The original desktop research explicitly chose separate Quick and Full windows. That assumption is now obsolete for the desired product: Quick Copilot should be Zara's primary desktop UI, not a launcher into another chat implementation.
QuickCopilotWindow already has hide/close/toggle machinery, but tray primary activation is wired to show_quick_copilot() rather than a true visibility toggle.
Runtime events already carry conversation_id and include correlated voice partial/final transcript, assistant, tool, and audio events. Voice-to-chat work should extend ownership/commit semantics rather than inventing a second event stream.
Conversation metadata already has a durable ID/title but needs summary/title provenance to safely support automatic finalization.
Main CI already uploads artifacts/; Qt can render widget trees to PNG, so screenshot evidence can be added without inventing a new artifact transport.

Required end state

One canonical desktop Copilot

Exactly one process-owned top-level chat surface supports:

hidden;
compact/quick mode;
expanded/full-conversation mode.

Compact and expanded modes share the same widgets/state/conversation ID. There is no Quick -> Full handoff between separate chat implementations.

Native-feeling UI

The normal healthy chat surface prioritizes conversation content and composer rather than permanent chrome.

Remove or demote:

redundant ZARA + Quick Copilot labels;
permanent Full Chat action;
full-width healthy runtime rail;
gratuitous layout gaps/card shells.

Preserve accessibility, tool state, error visibility, streaming/cancellation, attachments/context, keyboard navigation, and settings/diagnostics access.

Voice sessions are chats

Conversation mode must bind to one durable conversation_id.

partial STT remains ephemeral;
final transcript commits one USER message exactly once;
assistant/tool events mutate that same conversation;
hidden UI does not lose voice history;
stale stream/session events cannot mutate another chat;
voice session exit can asynchronously finalize automatic title/summary metadata.

Automatic title/summary

Durable runtime/conversation ownership, not Qt widget ownership.

manual rename wins;
summary is metadata, not a fake chat message;
generation is bounded and non-blocking;
failed generation has deterministic fallback;
retry/stale-result behavior is revision/idempotency safe;
all clients observe the same metadata.

Visibility/toggle contract

Primary tray click:

visible -> hide
hidden  -> show + raise + focus

Close and Escape in compact mode hide rather than kill Zara.

Expose a stable local command:

zara --toggle-desktop

It must target one existing desktop owner or start one if absent, without spawning duplicate runtimes. Client-local window visibility must not become a remote ZARA/1 assistant command.

Screenshot CI

Every relevant UI run emits deterministic PNG fixtures under artifacts/ui/ plus a small manifest.

Required states include at least empty, short chat, long wrap, streaming, error, disconnected/reconnecting, tool state, voice active/partial, expanded/history, and minimum supported size.

Initially hard-gate structural/layout invariants while always uploading screenshots. Add perceptual/golden regression only after the Nix/Qt/font render environment proves stable.

Automated visual review

RAGE/reviewers must be able to inspect screenshot artifacts and report concrete UI findings such as excessive gaps, clipping, overlap, bad widths, hidden composer, awkward empty states, duplicated chrome, contrast, and resize failures.

Integration/dependencies

#87 global shortcut work should invoke the unified Copilot rather than a legacy Quick window.
#88 context attachment UI targets the unified composer/surface.
#89 tool execution/approval UI targets the unified conversation renderer.
#92 settings/diagnostics remain secondary workspaces over the same configuration authority.
#133 remains authoritative for daemon/client/session continuity.
Android shares durable conversation/metadata semantics but does not share Qt presentation code.

Ordered implementation slices

Collapse Quick/Full into one adaptive Copilot and add screenshot CI in the same first slice.
Native layout/chrome overhaul driven by screenshot review.
Voice-session -> durable-conversation binding and exact-once final transcript commit.
Runtime-owned automatic title/summary metadata finalization.
Local desktop-control IPC + true tray toggle + zara --toggle-desktop.
Dotfiles integration consumes only the stable toggle command.

Invariants

one durable conversation authority;
one canonical desktop chat renderer;
no duplicated LLM/runtime/voice history;
daemon/client boundary remains intact;
Qt widgets do not call Prolog/tools/providers directly;
hiding windows does not define daemon/runtime lifetime;
voice works while UI is hidden;
manually renamed titles are never silently overwritten;
screenshot CI does not depend on network/providers/microphone.

Completion

Complete when Zara's desktop has one native adaptive Copilot, voice sessions appear in ordinary durable history with safe metadata finalization, tray/external toggle semantics are reliable, and significant UI changes always produce inspectable deterministic screenshot evidence.

Research: `docs/research/002-unified-copilot-voice-visual-ci.md` Research branch: `research/unified-copilot-20260905` Research baseline: `16b1eda8dd4a0b1e4a3dba7742787e8a75192347` ## Goal Replace Zara's current two-chat-window desktop presentation model with one canonical adaptive native Copilot, make voice conversation sessions first-class durable chats, and make screenshot evidence a normal part of UI CI/review. This epic changes presentation/lifecycle ownership. It must **not** create another assistant runtime, daemon protocol, conversation database, voice stack, Prolog stack, or provider configuration path. ## Research findings - `DesktopController` currently owns both `FullChatWindow` and `QuickCopilotWindow` and manually resynchronizes them through one `ConversationService`. - The original desktop research explicitly chose separate Quick and Full windows. That assumption is now obsolete for the desired product: Quick Copilot should be Zara's primary desktop UI, not a launcher into another chat implementation. - `QuickCopilotWindow` already has hide/close/toggle machinery, but tray primary activation is wired to `show_quick_copilot()` rather than a true visibility toggle. - Runtime events already carry `conversation_id` and include correlated voice partial/final transcript, assistant, tool, and audio events. Voice-to-chat work should extend ownership/commit semantics rather than inventing a second event stream. - Conversation metadata already has a durable ID/title but needs summary/title provenance to safely support automatic finalization. - Main CI already uploads `artifacts/`; Qt can render widget trees to PNG, so screenshot evidence can be added without inventing a new artifact transport. ## Required end state ### One canonical desktop Copilot Exactly one process-owned top-level chat surface supports: - hidden; - compact/quick mode; - expanded/full-conversation mode. Compact and expanded modes share the same widgets/state/conversation ID. There is no Quick -> Full handoff between separate chat implementations. ### Native-feeling UI The normal healthy chat surface prioritizes conversation content and composer rather than permanent chrome. Remove or demote: - redundant `ZARA` + `Quick Copilot` labels; - permanent `Full Chat` action; - full-width healthy runtime rail; - gratuitous layout gaps/card shells. Preserve accessibility, tool state, error visibility, streaming/cancellation, attachments/context, keyboard navigation, and settings/diagnostics access. ### Voice sessions are chats Conversation mode must bind to one durable `conversation_id`. - partial STT remains ephemeral; - final transcript commits one USER message exactly once; - assistant/tool events mutate that same conversation; - hidden UI does not lose voice history; - stale stream/session events cannot mutate another chat; - voice session exit can asynchronously finalize automatic title/summary metadata. ### Automatic title/summary Durable runtime/conversation ownership, not Qt widget ownership. - manual rename wins; - summary is metadata, not a fake chat message; - generation is bounded and non-blocking; - failed generation has deterministic fallback; - retry/stale-result behavior is revision/idempotency safe; - all clients observe the same metadata. ### Visibility/toggle contract Primary tray click: ```text visible -> hide hidden -> show + raise + focus ``` Close and Escape in compact mode hide rather than kill Zara. Expose a stable local command: ```text zara --toggle-desktop ``` It must target one existing desktop owner or start one if absent, without spawning duplicate runtimes. Client-local window visibility must not become a remote `ZARA/1` assistant command. ### Screenshot CI Every relevant UI run emits deterministic PNG fixtures under `artifacts/ui/` plus a small manifest. Required states include at least empty, short chat, long wrap, streaming, error, disconnected/reconnecting, tool state, voice active/partial, expanded/history, and minimum supported size. Initially hard-gate structural/layout invariants while always uploading screenshots. Add perceptual/golden regression only after the Nix/Qt/font render environment proves stable. ### Automated visual review RAGE/reviewers must be able to inspect screenshot artifacts and report concrete UI findings such as excessive gaps, clipping, overlap, bad widths, hidden composer, awkward empty states, duplicated chrome, contrast, and resize failures. ## Integration/dependencies - #87 global shortcut work should invoke the unified Copilot rather than a legacy Quick window. - #88 context attachment UI targets the unified composer/surface. - #89 tool execution/approval UI targets the unified conversation renderer. - #92 settings/diagnostics remain secondary workspaces over the same configuration authority. - #133 remains authoritative for daemon/client/session continuity. - Android shares durable conversation/metadata semantics but does not share Qt presentation code. ## Ordered implementation slices 1. Collapse Quick/Full into one adaptive Copilot **and add screenshot CI in the same first slice**. 2. Native layout/chrome overhaul driven by screenshot review. 3. Voice-session -> durable-conversation binding and exact-once final transcript commit. 4. Runtime-owned automatic title/summary metadata finalization. 5. Local desktop-control IPC + true tray toggle + `zara --toggle-desktop`. 6. Dotfiles integration consumes only the stable toggle command. ## Invariants - one durable conversation authority; - one canonical desktop chat renderer; - no duplicated LLM/runtime/voice history; - daemon/client boundary remains intact; - Qt widgets do not call Prolog/tools/providers directly; - hiding windows does not define daemon/runtime lifetime; - voice works while UI is hidden; - manually renamed titles are never silently overwritten; - screenshot CI does not depend on network/providers/microphone. ## Completion Complete when Zara's desktop has one native adaptive Copilot, voice sessions appear in ordinary durable history with safe metadata finalization, tray/external toggle semantics are reliable, and significant UI changes always produce inspectable deterministic screenshot evidence.