5.2 KiB
5.2 KiB
status, created, updated, owner
| status | created | updated | owner |
|---|---|---|---|
| draft | 2026-08-16 | 2026-08-23 | kandev |
Quick Chat Activity Indicators
Why
Quick chat agents continue to work after the user closes the dialog. Users need to see which tab is active and whether background work is complete.
What
- Each server-backed Quick Chat conversation tab shows the shared grid spinner while its agent has live work.
- Live work includes session startup, a running session, reported background activity, and environment preparation.
- Setup tabs and Quick Terminal tabs do not show the grid spinner.
- The Quick Chat entry shows an activity bubble only while the Quick Chat dialog is closed.
- A blue bubble means that at least one Quick Chat agent in the active workspace has live work.
- An emerald bubble means that all Quick Chat agents in the active workspace have settled and at least one result is unseen.
- The running state has priority when some agents are settled and at least one agent still has live work.
- The bubble appears on the collapsed sidebar item, expanded sidebar shortcut, tablet header, mobile header, and mobile task-switcher entry.
- Opening the Quick Chat dialog clears all unseen completion markers and hides the entry bubble.
- If the user closes the dialog while work continues, the blue bubble appears again.
- If the user closes the dialog after all results are seen, no bubble appears until new work starts or a new result arrives.
- Completion markers are scoped to a workspace. A tab removal or backing-task deletion removes its marker.
- Button labels describe the running or finished state. The colored bubble remains decorative.
State machine
The entry indicator is derived from live session rows and the existing client-only completion markers.
| State | Condition while the dialog is closed | Transition |
|---|---|---|
| hidden | No agent has live work and no unseen completion exists | A new turn starts or an unseen completion arrives |
| running | At least one Quick Chat agent has live work | The last working agent settles, or the dialog opens |
| finished | No agent has live work and at least one unseen completion exists | A new turn starts, the dialog opens, or the marked tab is removed |
Opening the dialog clears unseenIdleByWorkspace for all workspaces. Live activity remains in the session store and is not copied into a second ledger.
Failure modes
- If the WebSocket is disconnected, the live row can be stale until the existing resync updates it.
- If a completion event is missed, no finished bubble appears for that result. The indicator remains a best-effort cue.
- If a session row is not loaded, that session does not count as running. Its existing unseen marker can still produce the finished state.
- A completion received before its Quick Chat tab is known does not create a marker.
- Failed, canceled, and abandoned turns count as settled. This rule preserves the existing completion indicator behavior.
- Duplicate settle events use the existing 60-minute, 500-session ledger. They do not restore a marker while their ledger entry remains.
- A duplicate can restore a marker after its ledger entry expires or is removed by the entry limit.
- Marker timing uses receipt time. An event handled while the dialog is open is seen, even if the turn settled before the dialog opened.
Persistence guarantees
The running state comes from live session data. Unseen completion markers remain browser-memory state and reset on page reload.
Scenarios
- GIVEN a Quick Chat agent starts work, WHEN its conversation tab is visible, THEN that tab shows a grid spinner.
- GIVEN a Quick Chat agent settles, WHEN its conversation tab is visible, THEN that tab does not show a grid spinner.
- GIVEN the dialog is closed and one agent has live work, WHEN the Quick Chat entry renders, THEN it shows a blue running bubble.
- GIVEN one agent has settled and another agent still works, WHEN the Quick Chat entry renders, THEN it keeps the blue running bubble.
- GIVEN the dialog is closed and the last working agent settles, WHEN the completion arrives, THEN the bubble changes from blue to emerald.
- GIVEN an emerald finished bubble, WHEN the user opens the dialog, THEN the bubble disappears and the results become seen.
- GIVEN the user opens and closes the dialog after all work settles, WHEN no new work occurs, THEN no bubble appears.
- GIVEN the user opens and closes the dialog while an agent still works, WHEN the dialog closes, THEN the blue running bubble appears again.
- GIVEN the dialog is open, WHEN a turn completes, THEN no finished bubble is stored for that completion.
- GIVEN activity belongs to workspace A, WHEN the user views workspace B, THEN workspace B does not show that activity.
- GIVEN a marked session, WHEN its tab or backing task is removed, THEN that session stops contributing to the bubble.
Out of scope
- No backend, database, or WebSocket contract changes.
- No persisted notification history.
- No sound, toast, operating-system notification, or command-palette indicator.
- No activity bubble for Quick Terminal tabs.