feat: show queued prompt count badge in the task sidebar (#2354)
This commit is contained in:
@@ -0,0 +1,149 @@
|
||||
---
|
||||
status: shipped
|
||||
created: 2026-08-04
|
||||
owner: kandev
|
||||
---
|
||||
|
||||
# Sidebar Queued Prompt Count Badge
|
||||
|
||||
## Why
|
||||
|
||||
A task with en-queued prompts looks identical to an idle one in the left
|
||||
task view: nothing distinguishes "the agent is busy and three follow-ups are
|
||||
waiting" from "nothing is waiting". Users bounce between the sidebar and each
|
||||
task's queue panel to find where their typed work is stuck. A compact per-row
|
||||
count on the metadata line (the same line that already carries the last
|
||||
update time and PR number) makes queued work visible at a glance, for tasks
|
||||
and subtasks alike.
|
||||
|
||||
## What
|
||||
|
||||
### The badge
|
||||
|
||||
- Every task row and subtask row in the left task view (`TaskSessionSidebar`)
|
||||
shows, on its metadata line, a badge with a mail icon followed by the number
|
||||
of prompts currently en-queued for that task.
|
||||
- The count covers all of the task's sessions. It counts persisted queue
|
||||
entries whose `task_id` is the task, excluding rows already reserved for
|
||||
in-flight delivery (the same pending semantics as `message.queue.get`).
|
||||
- A count of `0` renders no badge: the metadata line is unchanged from today
|
||||
for tasks with nothing queued.
|
||||
- The badge is display-only: it is not a button, has no hover dependency, and
|
||||
never pushes the row to a second line.
|
||||
|
||||
### Data path
|
||||
|
||||
- **Initial load:** every task list/snapshot endpoint (HTTP list, workspace
|
||||
list, workflow/workspace snapshot, WS list, single task) carries the count in
|
||||
the task's status summary (`status_summary.queued_prompt_count`). The count
|
||||
is computed fresh from the queue table at assembly time so the sidebar is
|
||||
correct on first paint regardless of projector state.
|
||||
- **Live updates:** the task status summary projector subscribes to the
|
||||
internal `message.queue.status_changed` event, recomputes the affected
|
||||
task's pending count, and publishes the existing workspace-wide
|
||||
`task.status_summary.updated` broadcast. The sidebar therefore updates for
|
||||
every task in the workspace without any new per-session subscription.
|
||||
- **Queue panel payload:** the WebSocket `message.queue.status_changed` event
|
||||
(session-scoped, unchanged routing) gains an informational `task_id` field.
|
||||
Its `entries` content remains session-scoped; it is never broadcast
|
||||
workspace-wide.
|
||||
|
||||
## API Surface
|
||||
|
||||
No new actions or endpoints. Payload additions only:
|
||||
|
||||
```text
|
||||
task status summary (HTTP DTO, WS task.status_summary.updated)
|
||||
status_summary.queued_prompt_count: int // omitted when 0
|
||||
|
||||
message.queue.status_changed (WebSocket, session-scoped as today)
|
||||
task_id: string // informational addition
|
||||
```
|
||||
|
||||
## Data Model
|
||||
|
||||
No table migration. The count derives from the existing `queued_messages`
|
||||
table (`task_id` column, written at insert from the session's owning task).
|
||||
Pending semantics match `messagequeue.Service.GetStatus`: a row carrying
|
||||
`lifecycle_reserved_in_flight` metadata is excluded; durable lifecycle rows
|
||||
not yet reserved remain pending and count. The persisted
|
||||
`task_status_summaries` payload gains `queued_prompt_count` through the
|
||||
existing `SemanticJSON` envelope; old rows decode with the field absent
|
||||
(0).
|
||||
|
||||
## State and Concurrency
|
||||
|
||||
- The projector refreshes the count only when the queue event's computed count
|
||||
differs from its current value; unchanged counts do not bump the summary
|
||||
revision or republish.
|
||||
- The projector restores the last persisted count on restart and corrects it on
|
||||
the next queue event. List/snapshot assembly always reads the count fresh,
|
||||
so a missed event or projector startup ordering cannot leave a stale badge on
|
||||
initial load.
|
||||
- A queue mutation and a list assembly racing read the same queue table; the
|
||||
list response may carry a count from either side of the mutation, both
|
||||
authoritative snapshots.
|
||||
- Reserved-in-flight rows are excluded exactly as in `GetStatus`; a prompt
|
||||
already handed to a dispatch attempt is not "queued".
|
||||
|
||||
## Responsive and Mobile Behavior
|
||||
|
||||
- The badge renders inside the existing metadata row on both desktop and
|
||||
mobile sidebar layouts; it is a static text+icon pair, so it adds no hit
|
||||
target, no hover behavior, and no scroll owner.
|
||||
- The row's ellipsis/overflow behavior is unchanged: the badge is inline-flex
|
||||
and shrink-safe, so narrow viewports truncate the title rather than wrap the
|
||||
badge.
|
||||
- The accessible name is localized; the visible text is only the count.
|
||||
|
||||
## Failure Modes
|
||||
|
||||
- **Queue event missed (startup ordering, projector down):** initial list
|
||||
loads still show the correct count (fresh assembly); the next queue event
|
||||
repairs the live path.
|
||||
- **Session→task resolution fails at a publish site:** the event is published
|
||||
without `task_id`; the projector skips it and the next successful event (or
|
||||
the next list load) reconciles.
|
||||
- **Summary row missing and count is 0:** nothing to show; the row behaves as
|
||||
today.
|
||||
- **Summary row missing and count > 0 (hydration failed):** the badge is
|
||||
absent on that row until a summary exists; the queue panel remains the
|
||||
fallback surface. Same degradation class as other summary-only fields.
|
||||
- **Count query failure at assembly:** the list endpoint logs and serves the
|
||||
rest of the row without the badge: the response DTO clears any existing
|
||||
`queued_prompt_count` to `0` for that request only. The cleared value is
|
||||
never persisted back to the summary store, so a later successful count or
|
||||
projector event restores the badge. Matching the existing status-summary
|
||||
load behavior.
|
||||
- **Queued-counter provider unavailable (unwired):** the DTO leaves the
|
||||
projected `queued_prompt_count` untouched instead of stamping a zero over
|
||||
it, so a previously projected positive count survives list loads.
|
||||
|
||||
## Scenarios
|
||||
|
||||
- **GIVEN** a task with three prompts queued across its sessions, **WHEN** the
|
||||
sidebar loads, **THEN** its row shows a mail icon and `3` on the metadata
|
||||
line.
|
||||
- **GIVEN** a task with an empty queue, **WHEN** the sidebar loads, **THEN**
|
||||
its row shows no mail badge and the metadata line is unchanged.
|
||||
- **GIVEN** a task with two queued prompts, **WHEN** one is drained, **THEN**
|
||||
the badge updates to `1` without a reload, and to nothing when the last one
|
||||
drains.
|
||||
- **GIVEN** a prompt reserved for in-flight delivery while a later prompt
|
||||
remains pending, **WHEN** the sidebar renders, **THEN** only the pending
|
||||
prompt counts.
|
||||
- **GIVEN** a subtask with one queued prompt, **WHEN** the sidebar renders the
|
||||
subtree, **THEN** the subtask row shows the same badge treatment as a
|
||||
top-level task.
|
||||
- **GIVEN** a phone viewport, **WHEN** the sidebar renders a row with queued
|
||||
prompts, **THEN** the badge is visible without hover and the row does not
|
||||
overflow horizontally.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- Clicking the badge to open the queue panel (the row click still navigates).
|
||||
- Per-session breakdown of the count.
|
||||
- WIP overflow queues (`queued_for_step_id`) — a different queue concept with
|
||||
its own UI.
|
||||
- Queue capacity display, queue contents, or provenance in the sidebar.
|
||||
- Changing the session-scoped routing of `message.queue.status_changed`.
|
||||
Reference in New Issue
Block a user