237 lines
13 KiB
Markdown
237 lines
13 KiB
Markdown
---
|
|
status: active
|
|
system: ui
|
|
created: 2026-08-07
|
|
owners:
|
|
- kandev
|
|
---
|
|
# Reorder Queued Messages Requirements
|
|
|
|
## Overview
|
|
|
|
Pending messages run in strict FIFO order, so a later, more urgent prompt waits behind everything queued before it. Today the only workarounds are remove-and-requeue (destructive) or Send Now (interrupts the active turn). Users need to rearrange pending messages so execution order matches priority without losing content.
|
|
|
|
## Requirements
|
|
|
|
### REQ-UI-MESSAGE-QUEUE-REORDER-001: Reorder Queued Messages
|
|
|
|
**Intent:** Pending messages run in strict FIFO order, so a later, more urgent prompt waits behind everything queued before it. Today the only workarounds are remove-and-requeue (destructive) or Send Now (interrupts the active turn). Users need to rearrange pending messages so execution order matches priority without losing content.
|
|
|
|
#### Acceptance criteria
|
|
|
|
- **AC-UI-MESSAGE-QUEUE-REORDER-001.1:** Every visible pending message in the queue panel offers a **grab handle** on its left edge. The handle is a small dotted grip (2-column dot grid).
|
|
- **AC-UI-MESSAGE-QUEUE-REORDER-001.2:** The handle is a **floating overlay** anchored to the row's left edge, vertically centered. It does not participate in layout: no row or panel content moves to make room for it. While shown it may cover the row's `#N` position label; the label returns when the handle hides.
|
|
- **AC-UI-MESSAGE-QUEUE-REORDER-001.3:** On a fine pointer the handle is hidden by default and appears when the pointer hovers the row or keyboard focus reaches it. On a coarse pointer (touch) it is always visible, attached flush to the message box's left edge, and painted **behind** the row content — no chip surface, so the dotted grip reads as part of the box edge. The position label and sender icon stay painted above it (and pass touches through), and the interactive hit area is at least 44 by 44 CSS pixels.
|
|
- **AC-UI-MESSAGE-QUEUE-REORDER-001.4:** Dragging starts **only** from the handle. Pointer interaction with the row body (text selection, expand toggle, edit/merge/remove/send-now actions) is unchanged. Dragging requires pointer movement (activation distance), so a click on the handle does nothing by itself.
|
|
- **AC-UI-MESSAGE-QUEUE-REORDER-001.5:** Dropping the handle onto another row commits a new order. The queue panel updates immediately (optimistic) and reconciles to the backend result.
|
|
- **AC-UI-MESSAGE-QUEUE-REORDER-001.6:** The new order is **persisted server-side** and survives reload, session switch-back, and restart. All connected views reconcile to it.
|
|
- **AC-UI-MESSAGE-QUEUE-REORDER-001.7:** Displayed positions remain compact one-based ordinals (`#1` through `#N`) derived from the visible order, exactly as after remove/merge.
|
|
- **AC-UI-MESSAGE-QUEUE-REORDER-001.8:** Reordering applies to every visible pending row **regardless of provenance** (user, agent, workflow, system), matching the Remove action. Server-reserved rows already in flight stay hidden and are never reordered.
|
|
|
|
## Migrated source detail
|
|
|
|
## Why
|
|
|
|
Pending messages run in strict FIFO order, so a later, more urgent prompt
|
|
waits behind everything queued before it. Today the only workarounds are
|
|
remove-and-requeue (destructive) or Send Now (interrupts the active turn).
|
|
Users need to rearrange pending messages so execution order matches priority
|
|
without losing content.
|
|
|
|
## What
|
|
|
|
- Every visible pending message in the queue panel offers a **grab handle**
|
|
on its left edge. The handle is a small dotted grip (2-column dot grid).
|
|
- The handle is a **floating overlay** anchored to the row's left edge,
|
|
vertically centered. It does not participate in layout: no row or panel
|
|
content moves to make room for it. While shown it may cover the row's
|
|
`#N` position label; the label returns when the handle hides.
|
|
- On a fine pointer the handle is hidden by default and appears when the
|
|
pointer hovers the row or keyboard focus reaches it. On a coarse pointer
|
|
(touch) it is always visible, attached flush to the message box's left
|
|
edge, and painted **behind** the row content — no chip surface, so the
|
|
dotted grip reads as part of the box edge. The position label and sender
|
|
icon stay painted above it (and pass touches through), and the interactive
|
|
hit area is at least 44 by 44 CSS pixels.
|
|
- Dragging starts **only** from the handle. Pointer interaction with the row
|
|
body (text selection, expand toggle, edit/merge/remove/send-now actions)
|
|
is unchanged. Dragging requires pointer movement (activation distance),
|
|
so a click on the handle does nothing by itself.
|
|
- Dropping the handle onto another row commits a new order. The queue panel
|
|
updates immediately (optimistic) and reconciles to the backend result.
|
|
- The new order is **persisted server-side** and survives reload, session
|
|
switch-back, and restart. All connected views reconcile to it.
|
|
- Displayed positions remain compact one-based ordinals (`#1` through
|
|
`#N`) derived from the visible order, exactly as after remove/merge.
|
|
- Reordering applies to every visible pending row **regardless of
|
|
provenance** (user, agent, workflow, system), matching the Remove action.
|
|
Server-reserved rows already in flight stay hidden and are never
|
|
reordered.
|
|
- The handle is disabled while a queue mutation or backend cancellation for
|
|
the session is pending (the same `isLoading`/`cancellationPending` gate as
|
|
Send Now), and is hidden while the row is being edited.
|
|
- Keyboard reordering is supported: focusing the handle and using
|
|
Space/Enter plus the arrow keys moves the row, matching the platform's
|
|
sortable-list convention.
|
|
- Reordering changes nothing else: merge, edit, Remove, Send Now, FIFO
|
|
Auto-run, and capacity semantics are unchanged. When Auto-run next takes an
|
|
entry, it uses the new FIFO head. Protocol-level Send Now **all** and FIFO
|
|
drain dispatch in the current reordered order.
|
|
|
|
## API Surface
|
|
|
|
New WebSocket action:
|
|
|
|
```text
|
|
message.queue.reorder
|
|
```
|
|
|
|
Request:
|
|
|
|
```json
|
|
{
|
|
"session_id": "session-id",
|
|
"ordered_ids": ["entry-b", "entry-a", "entry-c"]
|
|
}
|
|
```
|
|
|
|
`session_id` is required. `ordered_ids` is required, non-empty, and must
|
|
contain each visible pending entry id of the session exactly once.
|
|
|
|
Successful response:
|
|
|
|
```json
|
|
{
|
|
"session_id": "session-id",
|
|
"reordered": 3
|
|
}
|
|
```
|
|
|
|
`reordered` is the number of entries in the submitted order — equal to the
|
|
visible pending count on success. A no-op reorder (submitting the current
|
|
order) reports the same count, since positions are rewritten to the compacted
|
|
`1..N` sequence.
|
|
|
|
Errors:
|
|
|
|
- `validation`: `session_id` missing, `ordered_ids` missing/empty, or
|
|
duplicate ids in `ordered_ids`.
|
|
- `queue_changed`: the submitted id set does not match the current visible
|
|
pending set — an entry was drained, removed, merged, or newly queued
|
|
since the client's snapshot. The request is rejected atomically with no
|
|
partial reorder; the client refetches the authoritative queue.
|
|
- Session access is required; the existing non-enumerating session-not-found
|
|
response is used before any queue read or mutation.
|
|
|
|
On success the handler publishes the existing `message.queue.status_changed`
|
|
event so every connected view reconciles.
|
|
|
|
## Data Model
|
|
|
|
No schema change. Order lives in the existing `queued_messages.position`
|
|
integer column (lower = head). A successful reorder rewrites positions to a
|
|
strictly increasing sequence: reserved in-flight rows keep their place in the
|
|
sequence, and the visible rows appear in the submitted order. Positions are
|
|
compacted (`1..N`) by the same operation, so subsequent inserts take
|
|
`MAX(position) + 1` as today.
|
|
|
|
## Permissions
|
|
|
|
- Any caller with access to the session may reorder its visible pending
|
|
entries, regardless of entry provenance (same rule as Remove and Send Now).
|
|
- The action accepts no caller-supplied content, `user_id`, `task_id`, or
|
|
identity. Only `session_id` and the entry ids are taken from the caller,
|
|
and the ids are validated against the persisted visible set.
|
|
|
|
## Failure Modes
|
|
|
|
- **Drain/remove/merge races the drag:** the submitted set no longer matches
|
|
the visible set; the backend rejects the whole request with `queue_changed`
|
|
and the client refetches silently (self-recovering, no error toast).
|
|
- **Backend mutation fails for another reason:** the client refetches to
|
|
restore the authoritative order and shows a localized error toast.
|
|
- **Concurrent clients:** the last successful reorder wins. A client with a
|
|
stale snapshot receives `queue_changed` and reconciles on its next refetch.
|
|
- **Reserved in-flight rows:** they are invisible to the client and excluded
|
|
from validation; they are never reordered and keep their delivery
|
|
reservation.
|
|
- **Rapid repeated drags:** while a reorder request is in flight the handles
|
|
are disabled, so overlapping reorder requests cannot be issued from one
|
|
client.
|
|
|
|
## Persistence Guarantees
|
|
|
|
The reordered sequence persists in `queued_messages.position` in SQLite and
|
|
survives a Kandev restart. It is queue state, not a client preference, and is
|
|
shared by every view of the session. A process crash mid-reorder leaves the
|
|
transaction uncommitted and the previous order intact.
|
|
|
|
## Responsive and Mobile Behavior
|
|
|
|
- The existing inline queue panel remains the desktop and phone composition;
|
|
the queue list stays the single internal scroll owner and the composer
|
|
stays visible.
|
|
- Desktop: the handle is a hover/focus-revealed floating overlay on the
|
|
row's left edge; nothing shifts in layout.
|
|
- Phone/coarse-pointer: the handle is always visible, attached flush to the
|
|
box's left edge, and painted behind the row content (background, no chip
|
|
surface). The row's position label / sender icon render above it and are
|
|
`pointer-events: none`, so touches reach the handle's 44 by 44 CSS-pixel
|
|
target while the label stays readable. `touch-action: none` on the handle
|
|
keeps a touch-drag reordering instead of scrolling; vertical scrolling of
|
|
the queue list is unaffected elsewhere.
|
|
- The queue hook, backend action, optimistic order, and reconciliation are
|
|
shared across viewports; only the handle's visibility and size differ.
|
|
- Mobile Playwright coverage proves the same reorder result with touch input.
|
|
|
|
## Scenarios
|
|
|
|
- **GIVEN** three messages are queued in order A, B, C, **WHEN** the user
|
|
drags C's handle above A, **THEN** the panel shows `#1` C, `#2` A, `#3` B
|
|
and reloading the page keeps that order.
|
|
- **GIVEN** a fine-pointer desktop with a queued message, **WHEN** the
|
|
pointer is not over the row, **THEN** no handle is visible, and the row
|
|
box has the same width and content position as without the feature.
|
|
- **GIVEN** the pointer hovers a queued message row, **WHEN** the pointer
|
|
moves onto the left edge, **THEN** the dotted grab handle appears as a
|
|
floating overlay and the row content does not shift.
|
|
- **GIVEN** a queued message row, **WHEN** the user presses and drags on the
|
|
row body (not the handle), **THEN** no drag starts; text selection and row
|
|
actions behave as before.
|
|
- **GIVEN** a row is being edited, **WHEN** the user looks at it, **THEN**
|
|
no grab handle is shown for that row.
|
|
- **GIVEN** a queue mutation or cancellation is in flight, **WHEN** the user
|
|
looks at any row, **THEN** the handles are visible but disabled.
|
|
- **GIVEN** the user starts dragging entry A and another client drains A
|
|
before the drop, **WHEN** the drop commits, **THEN** the backend returns
|
|
`queue_changed`, the panel silently refetches, and no error toast appears.
|
|
- **GIVEN** a queue whose head is a hidden reserved in-flight lifecycle row,
|
|
**WHEN** the user reorders the visible entries, **THEN** the visible
|
|
entries assume the submitted order around the reserved row and its
|
|
delivery/acknowledgement is unaffected.
|
|
- **GIVEN** the backend reorder fails for a non-race reason, **WHEN** the
|
|
drop commits, **THEN** the panel refetches the authoritative order and
|
|
shows the localized "failed to reorder" toast.
|
|
- **GIVEN** a queue containing user, agent, workflow, and system rows, **WHEN**
|
|
the user drags any of them, **THEN** the row moves to the dropped position.
|
|
- **GIVEN** a reordered queue and a protocol client invokes Send Now **all**,
|
|
**THEN** the bulk prompt concatenates the bodies in reordered FIFO order.
|
|
- **GIVEN** a phone viewport with queued messages, **WHEN** the user opens
|
|
the queue panel, **THEN** every row shows an always-visible touch-sized
|
|
handle attached flush to the box's left edge and painted behind the row
|
|
content (position labels stay readable), and a touch drag reorders the
|
|
queue with the same persisted result.
|
|
- **GIVEN** the user focuses a row's handle with the keyboard, **WHEN** they
|
|
press Space, Arrow Up, then Space, **THEN** the row moves one position up
|
|
and the order is persisted.
|
|
|
|
## Out of Scope
|
|
|
|
- Bulk selection or multi-row drag.
|
|
- Dedicated up/down move buttons as an alternative to dragging (keyboard
|
|
reordering is covered by the sortable keyboard sensor).
|
|
- Reordering hidden reserved in-flight rows.
|
|
- Cross-session or cross-task reordering.
|
|
- Changing merge, edit, Remove, Send Now, Auto-run, FIFO drain, or capacity
|
|
semantics.
|