feat(web): add agent message comments (#1835)
* 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
This commit is contained in:
@@ -0,0 +1,49 @@
|
||||
# Agent-message inline comments — implementation plan
|
||||
|
||||
Status: complete
|
||||
|
||||
Spec: [`docs/specs/ui/agent-message-comments.md`](../../specs/ui/agent-message-comments.md)
|
||||
|
||||
## Constraints
|
||||
|
||||
- Frontend-only. Do not change backend/API/schema/task_comments unless implementation evidence disproves the approved boundary.
|
||||
- Use existing frontend comment store and browser sessionStorage persistence.
|
||||
- Ordinary settled agent prose only: `message`/`content`, inactive turn, no raw view. Sibling rich blocks remain outside the selectable prose surface.
|
||||
- Preserve normal Task Chat, Quick Chat, passthrough, queue, attachments, and existing comment types.
|
||||
|
||||
## Waves and tasks
|
||||
|
||||
### Wave 1 — comment foundation
|
||||
|
||||
1. [`task-01-comment-foundation.md`](task-01-comment-foundation.md) — Extend the comment union, message-local anchor helpers, sessionStorage hydration, Markdown formatting, and focused tests.
|
||||
|
||||
### Wave 2 — selection and overlays
|
||||
|
||||
2. [`task-02-selection-and-overlay.md`](task-02-selection-and-overlay.md) — Capture local text selections, restore plan-style highlights and badges after virtualization, and provide the plan comment affordance plus shared desktop Popover/mobile Drawer actions.
|
||||
|
||||
### Wave 3 — composer and delivery wiring
|
||||
|
||||
3. [`task-03-chat-wiring.md`](task-03-chat-wiring.md) — Add message-comment context chips, composer inclusion/cleanup, immediate/queued Run, Task Chat/Quick Chat integration, and passthrough preservation.
|
||||
|
||||
### Wave 4 — browser verification
|
||||
|
||||
4. [`task-04-e2e-and-verification.md`](task-04-e2e-and-verification.md) — Add render-cost/component coverage plus Chromium and mobile-chrome E2E for Add, restore, Drawer, and Run paths.
|
||||
|
||||
## Mobile design contract
|
||||
|
||||
- Entry point: select settled agent prose in Task Chat or Quick Chat, then activate the plan-style comment affordance.
|
||||
- Exemplar: existing inset `Drawer` context surfaces (`mobile-menu-sheet.tsx`) and `useTouchDrawer` coarse-pointer branching.
|
||||
- Hierarchy: selected excerpt → feedback input → attached Add/Run actions, with update/delete for pending comments.
|
||||
- Surface: the shared plan-comment Popover on desktop; an equivalent phone inset bottom Drawer. Drawer owns its content scroll and clears safe area.
|
||||
- Shared: comment model, anchor resolver, store, formatter, context chips, and delivery callbacks shared across compositions.
|
||||
- Verification: desktop Chromium and `mobile-chrome` selection/Add/Run tests, containment, and no horizontal document overflow.
|
||||
|
||||
## Verification commands
|
||||
|
||||
- `cd apps && pnpm --filter @kandev/web test -- --run <focused tests>`
|
||||
- `cd apps/web && pnpm e2e:run --host tests/chat/agent-message-comments.spec.ts --project=chromium`
|
||||
- `cd apps/web && pnpm e2e:run --host --no-build tests/chat/mobile-agent-message-comments.spec.ts --project=mobile-chrome`
|
||||
- `make fmt`
|
||||
- `make typecheck test lint`
|
||||
- `node --test scripts/validate-public-docs.test.mjs`
|
||||
- `node scripts/validate-public-docs.mjs`
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
id: agent-message-comments-01
|
||||
title: Comment foundation
|
||||
status: complete
|
||||
wave: 1
|
||||
depends_on: None
|
||||
plan: plan.md
|
||||
---
|
||||
|
||||
## Acceptance
|
||||
|
||||
- `AgentMessageComment` and `MessageTextAnchor` are part of the frontend union with type guards, sessionStorage persistence/hydration, and Markdown formatting.
|
||||
- Unit tests cover round-trip persistence/hydration, anchor normalization, eligible-message filtering, and multiline Markdown.
|
||||
- Existing comment types and formatting remain compatible.
|
||||
|
||||
## Files
|
||||
|
||||
- `apps/web/lib/state/slices/comments/types.ts`
|
||||
- `apps/web/lib/state/slices/comments/comments-store.ts`
|
||||
- `apps/web/lib/state/slices/comments/persistence.ts`
|
||||
- `apps/web/lib/state/slices/comments/format.ts`
|
||||
- `apps/web/lib/state/slices/comments/*.test.ts`
|
||||
- `apps/web/lib/chat/agent-message-comments.ts`
|
||||
|
||||
## Verification
|
||||
|
||||
- `cd apps && pnpm --filter @kandev/web test -- --run lib/state/slices/comments lib/chat/agent-message-comments.test.ts`
|
||||
|
||||
## Output
|
||||
|
||||
Implemented the comment union, sessionStorage-backed hydration, message-local anchors, Markdown formatting, and focused persistence/format/anchor tests.
|
||||
|
||||
## Output contract
|
||||
|
||||
Summarize model, helpers, tests, touched files, blockers, and follow-up risks.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
id: agent-message-comments-02
|
||||
title: Selection and overlay
|
||||
status: complete
|
||||
wave: 2
|
||||
depends_on: agent-message-comments-01
|
||||
plan: plan.md
|
||||
---
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Only eligible settled agent prose exposes selection actions; selection is message-local and cannot cross rows.
|
||||
- Plan-style accent highlights and comment badges restore from stored offsets when a virtualized message remounts, without global DOM anchors.
|
||||
- Selection first exposes the plan-style comment affordance. Desktop reuses the plan comment Popover; coarse-pointer/mobile uses an equivalent native Drawer with accessible Add/Run/edit/delete actions and safe-area/touch geometry.
|
||||
- Activating a pending highlight or badge reopens it for update or deletion.
|
||||
|
||||
## Files
|
||||
|
||||
- `apps/web/components/task/chat/messages/chat-message.tsx`
|
||||
- `apps/web/components/task/chat/messages/message-comment-surface.tsx`
|
||||
- `apps/web/lib/chat/agent-message-comments.ts`
|
||||
- focused component/unit tests
|
||||
|
||||
## Verification
|
||||
|
||||
- focused Vitest selection/highlight tests
|
||||
- desktop and mobile rendered checks
|
||||
|
||||
## Output
|
||||
|
||||
Implemented message-local selection restoration, plan-style affordance/highlight/badge behavior, shared desktop plan Popover, and coarse-pointer/mobile Drawer interactions with Add/Run/update/delete behavior.
|
||||
|
||||
## Output contract
|
||||
|
||||
Summarize selection eligibility, anchor/highlight behavior, overlay composition, tests, and risks.
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
id: agent-message-comments-03
|
||||
title: Chat wiring and delivery
|
||||
status: complete
|
||||
wave: 3
|
||||
depends_on: agent-message-comments-01, agent-message-comments-02
|
||||
plan: plan.md
|
||||
---
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Add persists pending context and exposes removable message-comment chips in Task Chat and Quick Chat composers.
|
||||
- Composer send includes and clears message comments only on success; failed sends preserve context. Existing passthrough review-comment behavior remains intact.
|
||||
- Run uses existing direct message and busy queue paths, removing the comment only after successful delivery.
|
||||
|
||||
## Files
|
||||
|
||||
- `apps/web/lib/types/context.ts`
|
||||
- `apps/web/components/task/chat-context-items.ts`
|
||||
- `apps/web/components/task/chat/context-items/*`
|
||||
- `apps/web/components/task/chat/use-chat-panel-state.ts`
|
||||
- `apps/web/components/task/chat/chat-input-area.tsx`
|
||||
- `apps/web/hooks/use-message-handler.ts`
|
||||
- `apps/web/hooks/domains/comments/use-run-comment.ts`
|
||||
- `apps/web/components/task/passthrough-chat-composer.tsx`
|
||||
- focused tests
|
||||
|
||||
## Verification
|
||||
|
||||
- focused composer/store/run tests
|
||||
- passthrough regression tests
|
||||
|
||||
## Output
|
||||
|
||||
Wired Task Chat and Quick Chat context chips, composer inclusion/cleanup, direct and queued Run delivery, and passthrough preservation.
|
||||
|
||||
## Output contract
|
||||
|
||||
Summarize Task Chat/Quick Chat/passthrough wiring, direct/queue behavior, tests, and risks.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
id: agent-message-comments-04
|
||||
title: E2E and verification
|
||||
status: complete
|
||||
wave: 4
|
||||
depends_on: agent-message-comments-03
|
||||
plan: plan.md
|
||||
---
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Render-cost/unit coverage proves message-comment state/highlight updates do not reparse unrelated Markdown rows.
|
||||
- Chromium E2E covers selecting settled prose, Add, composer inclusion, persistence/remount, and Run delivery.
|
||||
- `mobile-chrome` E2E covers Drawer actions, touch-sized controls, containment, and no document horizontal overflow.
|
||||
|
||||
## Files
|
||||
|
||||
- `apps/web/components/task/chat/__evals__/render-cost.test.tsx`
|
||||
- `apps/web/e2e/tests/chat/agent-message-comments.spec.ts`
|
||||
- `apps/web/e2e/tests/chat/mobile-agent-message-comments.spec.ts`
|
||||
- `docs/public/developer-tools.md`
|
||||
|
||||
## Verification
|
||||
|
||||
- `make fmt`
|
||||
- `make typecheck test lint`
|
||||
- targeted Chromium and mobile-chrome managed E2E
|
||||
- public-doc validators
|
||||
|
||||
## Output
|
||||
|
||||
Added render-cost coverage, focused component/unit tests, desktop Chromium E2E, mobile-chrome E2E, and public documentation.
|
||||
|
||||
## Output contract
|
||||
|
||||
Summarize tests/results, docs, review findings, unresolved risks, and any unrelated pre-existing failures.
|
||||
@@ -11,6 +11,12 @@ Kandev includes short-lived chat, reusable AI helpers, dictation, file and edito
|
||||
|
||||
Quick Chat is an agent conversation outside the board. Use it for repository orientation, experiments, and disposable questions that do not need workflow state, review gates, dependencies, or a delivery record.
|
||||
|
||||
### Comment on an agent reply
|
||||
|
||||
In Task Chat or Quick Chat, select text from a settled agent prose reply, then select the comment button that appears beside the selection. The editor works like plan comments: enter feedback and choose **Add** to keep it as pending context, or **Run** to send it immediately. Pending selections use the same inline highlight and comment badge as plans; select either one to update or delete the feedback. Pending message comments are kept for the current browser tab, appear as composer context chips, and are included in the next prompt as Markdown. If the agent is busy, **Run** queues the feedback for its next turn.
|
||||
|
||||
Inline comments are available only on ordinary settled prose. Streaming replies, tool/thinking/status output, plans, rich-block content, raw views, and user messages do not accept inline comments.
|
||||
|
||||
Select **Quick Chat** beside **New Task** in the expanded sidebar, or select its standalone row in the collapsed sidebar.
|
||||
|
||||
### Start a chat
|
||||
|
||||
@@ -120,6 +120,7 @@ Subscription quota tracking and per-agent cheap-model profile routing.
|
||||
| [settings-manual-save](ui/settings-manual-save.md) | shipped |
|
||||
| [mobile-task-navigation](ui/mobile-task-navigation.md) | shipped |
|
||||
| [task-layout-profiles](ui/task-layout-profiles.md) | draft |
|
||||
| [agent-message-comments](ui/agent-message-comments.md) | shipped |
|
||||
|
||||
## system-page/ — operational diagnostics & maintenance UI
|
||||
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user