José Almeida
8f2fe7a8e6
* feat(web): add agent message comments * fix(web): harden agent message comments * fix(web): address message comment review findings * fix(web): allow comments on legacy agent messages * fix(web): address latest message comment review * fix(web): address follow-up message comment review * fix(web): address remaining message comment review * fix(web): keep failed mobile comments open * fix(web): preserve selections over message comments
60 lines
5.4 KiB
Markdown
60 lines
5.4 KiB
Markdown
---
|
|
status: shipped
|
|
created: 2026-07-20
|
|
owner: cfl
|
|
---
|
|
|
|
# Agent-message inline comments
|
|
|
|
## Why
|
|
|
|
Users need to point an agent at one exact part of an ordinary settled reply without copying prose into a new prompt. Inline comments turn a message selection into durable, visible prompt context while keeping the existing chat and queue delivery paths intact.
|
|
|
|
## What
|
|
|
|
- In Task Chat and Quick Chat, users can select text from the ordinary prose portion of a settled agent reply (`message` or `content`). Rich blocks rendered beside that prose remain outside the selectable surface.
|
|
- Current streaming replies, user messages, raw views, thinking, tools, status/progress, `agent_plan`, and rich-block content do not expose inline-comment controls.
|
|
- Selection first reveals the same accent comment affordance used by plan selection. Activating it opens the shared plan-comment popover on desktop or the equivalent coarse-pointer/mobile bottom Drawer. The keyboard shortcut and Add/Run action hierarchy match plan comments.
|
|
- **Add** stores a pending agent-message comment in browser `sessionStorage`, renders the same accent highlight and comment badge used in plans when its message is mounted, and adds a removable context chip to the composer.
|
|
- Activating a pending comment's highlight or badge reopens the editor so the feedback can be updated or deleted.
|
|
- **Run** sends the single comment immediately when the session is idle or appends it to the existing queue when the agent is busy. Successful delivery removes the pending comment.
|
|
- Sending normal composer content includes all pending agent-message comments in Markdown and removes them only after successful direct or passthrough delivery. Failed sends preserve draft and context.
|
|
- Highlights identify selections using message-local text anchors, not global DOM positions. Virtualized/unmounted chat rows restore highlights when remounted.
|
|
- Existing diff, plan, PR-feedback, walkthrough, attachment, file, prompt, and passthrough context behavior remains unchanged.
|
|
|
|
## Data model and persistence
|
|
|
|
`AgentMessageComment` extends the frontend comment union with `source: "agent-message"`, session id, message id, selected text, user feedback, pending/sent status, and a message-local anchor containing start/end text offsets plus nearby prefix/suffix context. Comments are persisted per session using the existing browser `sessionStorage` comment store. No backend table, API, WebSocket schema, or `task_comments` change is in scope.
|
|
|
|
## Markdown and delivery
|
|
|
|
Agent-message comments format as a Markdown section containing the selected response text and user feedback as blockquotes. All existing comment types retain their current format. Normal, queued, immediate, and passthrough sends use the existing message/queue APIs; only the final client-side message composition changes.
|
|
|
|
## Mobile contract
|
|
|
|
- Desktop entry point: select settled agent prose, activate the plan-style comment affordance, then act from the shared anchored plan popover.
|
|
- Mobile entry point: select settled agent prose, activate a touch-sized version of the same affordance, then act from an inset bottom Drawer following existing phone context surfaces.
|
|
- Drawer hierarchy and language mirror the desktop popover: selected text preview, feedback input, attached Add/Run actions, and edit/delete controls. One internal scroll owner; controls have touch-sized hitboxes and safe-area bottom padding.
|
|
- Shared state and delivery handlers are reused. Only overlay presentation differs by pointer/viewport.
|
|
- Mobile E2E proves selection, Drawer presentation, Add, composer context, and Run delivery outcome without document horizontal overflow.
|
|
|
|
## Scenarios
|
|
|
|
- **GIVEN** a settled agent prose reply, **WHEN** the user selects non-empty text, **THEN** a plan-style comment affordance appears for that selection.
|
|
- **GIVEN** a visible selection affordance, **WHEN** the user activates it, **THEN** the plan-style editor opens with the exact selected text.
|
|
- **GIVEN** a current streaming reply or non-prose/rich message, **WHEN** the user selects text, **THEN** no inline-comment action surface opens.
|
|
- **GIVEN** feedback and a selection, **WHEN** the user chooses **Add**, **THEN** the comment is persisted in sessionStorage, highlighted in the message, and shown as a composer chip.
|
|
- **GIVEN** a pending comment, **WHEN** the user reloads the tab or the virtualized row remounts, **THEN** state and highlight restore for the same message-local anchor.
|
|
- **GIVEN** a pending comment highlight or badge, **WHEN** the user activates it, **THEN** they can update or delete the pending feedback.
|
|
- **GIVEN** a pending comment, **WHEN** the user chooses **Run** while idle, **THEN** one Markdown message is sent immediately and the comment is removed after success.
|
|
- **GIVEN** a pending comment, **WHEN** the user chooses **Run** while busy, **THEN** one Markdown queue entry is appended and the comment is removed after success.
|
|
- **GIVEN** pending comment context and composer text, **WHEN** the user submits successfully, **THEN** the Markdown context is included and pending comments are cleared.
|
|
- **GIVEN** a failed direct, queued, or passthrough send, **THEN** pending context and draft remain available.
|
|
|
|
## Out of scope
|
|
|
|
- Backend/API/schema/task-comment persistence.
|
|
- Comments on user messages, streaming replies, tools, status, thinking, plans, rich-block content, or raw views.
|
|
- Cross-message selections or server-side highlight rendering.
|
|
- Editing an already-sent inline comment.
|