fix: continue paginating transcript history (#3174)
This commit is contained in:
@@ -0,0 +1,155 @@
|
||||
---
|
||||
created: 2026-08-30
|
||||
status: implemented
|
||||
requirements:
|
||||
- REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001
|
||||
system_design:
|
||||
- ../../specs/ui/system-design/task-prompt-transcript-visibility.md
|
||||
legacy_specs: []
|
||||
---
|
||||
|
||||
# Implementation plan: Continuous conversation history pagination
|
||||
|
||||
## Overview
|
||||
|
||||
Make the transcript distinguish initialized history from default empty state,
|
||||
then use that state to suppress the task-description fallback until the true
|
||||
conversation start is reached. After that boundary is trustworthy, replace
|
||||
visible-row identity pagination stops with committed sentinel geometry and
|
||||
show the manual loader only for recoverable failures.
|
||||
|
||||
## Scope
|
||||
|
||||
### In scope
|
||||
|
||||
- Record whether authoritative message pagination metadata initialized.
|
||||
- Gate the synthetic task description on initialized, exhausted history.
|
||||
- Continue upward pagination while the committed sentinel remains in preload.
|
||||
- Keep prompt `#1` as the visible start.
|
||||
- Show the explicit older-page control only after error or no progress.
|
||||
- Preserve scroll anchors and raw search pagination.
|
||||
- Prove the same outcome on desktop and mobile with tool-heavy history.
|
||||
|
||||
### Out of scope
|
||||
|
||||
- Backend queries, cursor fields, persistence, or message ordering.
|
||||
- Eagerly loading history when a task opens.
|
||||
- Rendering internal rows before prompt `#1`.
|
||||
- Changing prompt-history panel behavior beyond shared state compatibility.
|
||||
- New user-facing copy or a new mobile composition.
|
||||
|
||||
## Confirmed root cause
|
||||
|
||||
`shouldShowTaskDescriptionFallback` checks only the currently loaded visible
|
||||
rows. A bounded newest window containing no user row therefore synthesizes the
|
||||
task description while raw `has_more` is still true.
|
||||
|
||||
The native transcript stops a load cycle whenever an older page changes the
|
||||
oldest visible boundary. Its retry path requires `scrollTop` to decrease, which
|
||||
cannot happen while the reader is pinned at the top. The always-visible manual
|
||||
loader becomes the only reliable continuation.
|
||||
|
||||
The reported running session placed the latest user prompt behind 516 newer
|
||||
rows. The initial 100-row window plus 20-row older pages required 21 requests,
|
||||
which made both defects visible.
|
||||
|
||||
## Technical approach
|
||||
|
||||
### Trustworthy transcript start
|
||||
|
||||
- Add an initialization bit to per-session message metadata and its merge,
|
||||
hydration, default, reconciliation, and purge paths.
|
||||
- Expose initialized and raw-history state from `useSessionMessages`.
|
||||
- Pass an explicit history-start condition into `useProcessedMessages`.
|
||||
- Require initialized, exhausted history before synthesizing the task
|
||||
description when no stored user prompt is visible.
|
||||
- Keep prompt ordinals and the visible `hasMore` boundary unchanged.
|
||||
|
||||
### Geometry-driven pagination and recovery
|
||||
|
||||
- Re-evaluate the sentinel against the scroll root and configured preload
|
||||
margin after page commit and prepend restoration.
|
||||
- Continue positive loads while current geometry remains eligible, regardless
|
||||
of whether a standalone boundary key changed.
|
||||
- Retain boundary keys for scroll anchoring and diagnostics, not continuation.
|
||||
- Track a transcript-local recovery state for rejected or zero-progress loads.
|
||||
- Render the existing localized older-page button only in recovery state and
|
||||
clear that state after progress, exhaustion, prompt `#1`, or session change.
|
||||
- Give the recovery control a coarse-pointer 44-pixel hit area while retaining
|
||||
existing desktop density.
|
||||
|
||||
## Tests
|
||||
|
||||
| Acceptance criteria | Evidence |
|
||||
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
||||
| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.1` to `.4` | `use-processed-messages-fallback.test.ts`, session slice/fetch tests |
|
||||
| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.5` to `.8` | `use-lazy-load-sentinel.test.ts`, `message-list-native.test.tsx`, `message-list-shared.test.tsx` |
|
||||
| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.9` | Existing native prepend-anchor unit and browser assertions |
|
||||
| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.10` | Existing bounded-opening browser request watcher |
|
||||
| `AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.12` | Existing inactive-session reconciliation coverage |
|
||||
|
||||
The TDD regression starts with the current tool-heavy case: initialized
|
||||
history has `hasMore: true`, contains agent/tool rows, and has no loaded user
|
||||
row. The expected synthetic fallback count is zero, which fails against the
|
||||
current implementation.
|
||||
|
||||
## E2E tests
|
||||
|
||||
- Desktop Chromium: update
|
||||
`apps/web/e2e/tests/chat/message-pagination.spec.ts` to prove one upward
|
||||
navigation crosses more than twenty tool-heavy pages, reveals the stored
|
||||
latest prompt, and never shows the task-description fallback or normal retry
|
||||
control.
|
||||
- Mobile Chrome: update
|
||||
`apps/web/e2e/tests/chat/mobile-message-pagination.spec.ts` with the same user
|
||||
outcome in the full-height mobile Chat surface.
|
||||
- Shared seed: extend
|
||||
`apps/web/e2e/tests/chat/message-pagination-helpers.ts` with an efficient
|
||||
long-history fixture and retain prompt-`#1`, hidden pre-prompt, and anchor
|
||||
scenarios.
|
||||
|
||||
## Mobile design contract
|
||||
|
||||
- Desktop outcome: continuous upward history loading reaches the stored prompt
|
||||
without a misleading synthetic prompt or routine manual loader.
|
||||
- Mobile entry point: the existing Chat tab in the full-height task layout.
|
||||
- Nearest exemplar: `apps/web/components/task/task-layout.tsx` and the current
|
||||
mobile pagination spec.
|
||||
- Hierarchy and surface: no composition change; the transcript remains the
|
||||
single vertical scroll owner.
|
||||
- Shared logic: desktop and mobile use the same store, hooks, cursor
|
||||
coordinator, sentinel, and recovery state.
|
||||
- Mobile-specific detail: the recovery control keeps a 44-pixel coarse-pointer
|
||||
hit area.
|
||||
- Mobile proof: the `mobile-chrome` flow reaches the stored prompt with one
|
||||
upward navigation and exercises recovery without horizontal or nested
|
||||
scrolling.
|
||||
|
||||
## Work orders
|
||||
|
||||
- [x] [Task 01: Establish the true transcript start](task-01-establish-transcript-start.md) (`done`)
|
||||
- [x] [Task 02: Continue pagination through the preload region](task-02-continue-preload-pagination.md) (`done`)
|
||||
|
||||
## Verification results
|
||||
|
||||
- Focused Task 01 Vitest suite: passed (5 files, 87 tests).
|
||||
- Focused Task 02 Vitest suite: passed (4 files, 115 tests).
|
||||
- `pnpm run typecheck`: passed.
|
||||
- `make build-web`: passed; Vite emitted existing chunk-size and dynamic-import
|
||||
warnings only.
|
||||
- Desktop Chromium pagination: passed (6 tests).
|
||||
- Mobile Chrome pagination: passed (6 tests).
|
||||
- `git diff --check`: passed.
|
||||
|
||||
## Risks
|
||||
|
||||
- Default `hasMore: false` must not be mistaken for an authoritative exhausted
|
||||
response before history initializes.
|
||||
- Boot hydration, WebSocket-only rows, refetch reconciliation, and deletion
|
||||
must not leave stale initialization metadata.
|
||||
- Geometry checks must use committed layout and current scroll-root bounds so
|
||||
stale observer entries cannot cascade through off-screen history.
|
||||
- A zero-result response and a real request error currently both surface as no
|
||||
progress; both require recovery without an automatic retry loop.
|
||||
- The long-history browser seed must remain deterministic and fast enough for
|
||||
desktop and mobile projects.
|
||||
+108
@@ -0,0 +1,108 @@
|
||||
---
|
||||
id: "01-establish-transcript-start"
|
||||
title: "Establish the true transcript start"
|
||||
status: done
|
||||
wave: 1
|
||||
depends_on: []
|
||||
plan: "plan.md"
|
||||
requirements:
|
||||
- REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001
|
||||
acceptance_criteria:
|
||||
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.1
|
||||
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.2
|
||||
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.3
|
||||
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.4
|
||||
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.10
|
||||
system_design:
|
||||
- ../../specs/ui/system-design/task-prompt-transcript-visibility.md
|
||||
---
|
||||
|
||||
# Task 01: Establish the true transcript start
|
||||
|
||||
## Summary
|
||||
|
||||
Record when session message history has authoritative pagination metadata and
|
||||
use that state to prevent a bounded tool-only window from synthesizing the task
|
||||
description. Preserve bounded opening and prompt-`#1` behavior.
|
||||
|
||||
## In scope
|
||||
|
||||
- Add and maintain per-session message-history initialization state.
|
||||
- Expose initialized and raw-history state through the session hook.
|
||||
- Gate task-description fallback on initialized, exhausted history.
|
||||
- Preserve stored user prompts as authoritative.
|
||||
- Add the failing tool-only-window regression before implementation.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Sentinel continuation and retry-control behavior.
|
||||
- Backend message APIs or persistence.
|
||||
- Eager history loading.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- An initialized window with older history and no user row renders no synthetic
|
||||
task description.
|
||||
- Exhausted legacy history with no user row renders one non-empty fallback.
|
||||
- Uninitialized, refetching, prompt-`#1`, and empty-description cases do not
|
||||
produce a misleading or duplicate fallback.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
cd apps/web
|
||||
pnpm exec vitest run \
|
||||
hooks/use-processed-messages-fallback.test.ts \
|
||||
hooks/domains/session/use-session-messages.test.ts \
|
||||
hooks/domains/session/use-session-message-fetch.test.ts \
|
||||
lib/state/slices/session/session-slice.merge-messages.test.ts \
|
||||
components/task/chat/message-list-shared.test.tsx
|
||||
pnpm run typecheck
|
||||
```
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/web/lib/state/slices/session/types.ts`
|
||||
- `apps/web/lib/state/slices/session/session-slice.ts`
|
||||
- `apps/web/lib/state/slices/session/session-slice.merge-messages.test.ts`
|
||||
- `apps/web/lib/state/hydration/merge-strategies.ts`
|
||||
- `apps/web/hooks/domains/session/use-session-messages.ts`
|
||||
- `apps/web/hooks/domains/session/use-session-message-fetch.test.ts`
|
||||
- `apps/web/components/task/chat/use-chat-panel-state.ts`
|
||||
- `apps/web/hooks/use-processed-messages.ts`
|
||||
- `apps/web/hooks/use-processed-messages-fallback.test.ts`
|
||||
- `apps/web/components/task/chat/message-list-shared.test.tsx`
|
||||
|
||||
## Dependencies
|
||||
|
||||
None.
|
||||
|
||||
## Risks
|
||||
|
||||
- Boot-hydrated and client-fetched sessions must set the same initialization
|
||||
state.
|
||||
- Live rows arriving before the newest snapshot must not claim that history is
|
||||
initialized or exhausted.
|
||||
- Purged sessions must not retain metadata that affects a later session.
|
||||
|
||||
## Parallelism
|
||||
|
||||
`sequential`
|
||||
|
||||
## Inputs
|
||||
|
||||
- `REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001` acceptance criteria `.1` to
|
||||
`.4` and `.10`.
|
||||
- History state and opening boundary sections of the system design.
|
||||
- Existing message-window reconciliation and processed-message fallback tests.
|
||||
|
||||
## Results
|
||||
|
||||
- Added per-session `historyInitialized` metadata with safe defaults, live-row
|
||||
isolation, newest-window fetch/boot hydration, and purge-compatible state.
|
||||
- Gated the task-description fallback on initialized, exhausted history while
|
||||
preserving stored user prompts and the prompt-`#1` visible boundary.
|
||||
- Added regressions for older history, uninitialized history, live inserts, and
|
||||
authoritative fetch metadata.
|
||||
- The focused Task 01 Vitest suite passed (5 files, 87 tests).
|
||||
- `pnpm run typecheck` passed.
|
||||
+133
@@ -0,0 +1,133 @@
|
||||
---
|
||||
id: "02-continue-preload-pagination"
|
||||
title: "Continue pagination through the preload region"
|
||||
status: done
|
||||
wave: 2
|
||||
depends_on:
|
||||
- "01-establish-transcript-start"
|
||||
plan: "plan.md"
|
||||
requirements:
|
||||
- REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001
|
||||
acceptance_criteria:
|
||||
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.5
|
||||
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.6
|
||||
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.7
|
||||
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.8
|
||||
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.9
|
||||
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.11
|
||||
- AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.12
|
||||
system_design:
|
||||
- ../../specs/ui/system-design/task-prompt-transcript-visibility.md
|
||||
---
|
||||
|
||||
# Task 02: Continue pagination through the preload region
|
||||
|
||||
## Summary
|
||||
|
||||
Make positive older-page loads continue from committed sentinel geometry
|
||||
instead of visible-row identity. Show the existing loader only for recoverable
|
||||
error or no-progress state, then prove the combined flow on desktop and mobile.
|
||||
|
||||
## In scope
|
||||
|
||||
- Evaluate current sentinel geometry after layout and scroll restoration.
|
||||
- Continue while the sentinel remains inside the configured preload region.
|
||||
- Retain prompt `#1`, exhaustion, stale-session, and no-progress stops.
|
||||
- Track recovery state and expose a managed retry action.
|
||||
- Hide the manual loader during normal pagination.
|
||||
- Preserve prepend anchoring and raw search backfill.
|
||||
- Add desktop and mobile long-history regressions.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Changes to initial history-fetch size or older-page size.
|
||||
- Backend cursors or message persistence.
|
||||
- A new mobile surface or new localized copy.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- One upward navigation crosses short standalone and collapsed pages while the
|
||||
sentinel remains in preload, then stops when current geometry leaves it.
|
||||
- Successful pagination never exposes the manual loader; failure or no progress
|
||||
exposes one retry control and a successful retry clears it.
|
||||
- Desktop and mobile reach a stored prompt more than twenty older pages away
|
||||
without a click while retaining stable scroll position.
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
cd apps/web
|
||||
pnpm exec vitest run \
|
||||
hooks/use-lazy-load-sentinel.test.ts \
|
||||
hooks/use-lazy-load-messages.test.ts \
|
||||
components/task/chat/message-list-native.test.tsx \
|
||||
components/task/chat/message-list-shared.test.tsx
|
||||
pnpm run typecheck
|
||||
```
|
||||
|
||||
```bash
|
||||
make build-web
|
||||
cd apps/web
|
||||
pnpm e2e:run --host --no-build --project chromium -- \
|
||||
tests/chat/message-pagination.spec.ts
|
||||
pnpm e2e:run --host --no-build --project mobile-chrome -- \
|
||||
tests/chat/mobile-message-pagination.spec.ts
|
||||
```
|
||||
|
||||
## Files likely touched
|
||||
|
||||
- `apps/web/hooks/use-lazy-load-sentinel.ts`
|
||||
- `apps/web/hooks/use-lazy-load-sentinel.test.ts`
|
||||
- `apps/web/components/task/chat/message-list-native-scroll.ts`
|
||||
- `apps/web/components/task/chat/message-list-native.tsx`
|
||||
- `apps/web/components/task/chat/message-list-native.test.tsx`
|
||||
- `apps/web/components/task/chat/message-list-shared.tsx`
|
||||
- `apps/web/components/task/chat/message-list-shared.test.tsx`
|
||||
- `apps/web/e2e/tests/chat/message-pagination-helpers.ts`
|
||||
- `apps/web/e2e/tests/chat/message-pagination.spec.ts`
|
||||
- `apps/web/e2e/tests/chat/mobile-message-pagination.spec.ts`
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Task 01 must provide authoritative transcript-start state before the combined
|
||||
browser flow changes fallback expectations.
|
||||
|
||||
## Risks
|
||||
|
||||
- Geometry must be measured after prepend restoration, not from a stale
|
||||
IntersectionObserver sample.
|
||||
- Recovery retries must not loop automatically on the same failed cursor.
|
||||
- The recovery control needs a 44-pixel coarse-pointer target without changing
|
||||
fine-pointer desktop density.
|
||||
- Long-history fixtures must not make focused E2E runs flaky or exceed their
|
||||
existing timeout budget.
|
||||
|
||||
## Parallelism
|
||||
|
||||
`sequential`
|
||||
|
||||
## Inputs
|
||||
|
||||
- `REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001` acceptance criteria `.5` to
|
||||
`.9`, `.11`, and `.12`.
|
||||
- Upward pagination, failure and recovery, and responsive sections of the
|
||||
system design.
|
||||
- Existing lazy-sentinel, native-scroll, desktop, and mobile pagination tests.
|
||||
|
||||
## Results
|
||||
|
||||
- Replaced visible-boundary continuation with committed sentinel/root geometry,
|
||||
retaining boundary keys for anchoring and diagnostics.
|
||||
- Added transcript-local recovery state and an explicit retry path for rejected
|
||||
or zero-progress requests; routine successful pagination stays button-free.
|
||||
- Added committed-geometry continuation and session-epoch guards so stale
|
||||
observer entries and prior-session settlements cannot stop or alter the
|
||||
current transcript.
|
||||
- Preserved the desktop fine-pointer density and added a coarse-pointer
|
||||
minimum 44-pixel recovery target.
|
||||
- Added long-history and short-boundary fixtures plus matching desktop/mobile
|
||||
browser regressions.
|
||||
- The focused Task 02 Vitest suite passed (4 files, 115 tests).
|
||||
- `pnpm run typecheck` and `make build-web` passed.
|
||||
- Chromium pagination passed (6 tests); mobile Chrome pagination passed (6
|
||||
tests).
|
||||
@@ -5,126 +5,50 @@ created: 2026-08-22
|
||||
owners:
|
||||
- kandev
|
||||
---
|
||||
# Task transcript history visibility Requirements
|
||||
|
||||
# Task transcript history visibility requirements
|
||||
|
||||
## Overview
|
||||
|
||||
The transcript can lose the original task prompt after a reload. Long activity groups can also make older history difficult to reach. An older page can add tool events only inside an existing collapsed row. The user then sees no new entry and must select **Load older messages** again.
|
||||
Task transcripts open on a bounded newest window and load older history as the
|
||||
user navigates upward. A bounded window is not the start of the conversation.
|
||||
The transcript must not substitute the task description for an unloaded user
|
||||
prompt, and upward navigation must not require routine use of a manual loader.
|
||||
|
||||
## Terms
|
||||
|
||||
- **Visible start:** The first stored user prompt, normally prompt `#1`.
|
||||
- **Task-description fallback:** A synthetic user row used only for legacy
|
||||
history that contains no stored user prompt.
|
||||
- **Preload region:** The area near the oldest loaded edge where upward
|
||||
pagination can continue without another user action.
|
||||
|
||||
## Requirements
|
||||
|
||||
### REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001: Task transcript history visibility
|
||||
|
||||
**Intent:** The transcript can lose the original task prompt after a reload. Long activity groups can also make older history difficult to reach. An older page can add tool events only inside an existing collapsed row. The user then sees no new entry and must select **Load older messages** again.
|
||||
**Intent:** Users can navigate continuously from the newest response to the
|
||||
first prompt without mistaking a bounded history window for the conversation
|
||||
start.
|
||||
|
||||
#### Acceptance criteria
|
||||
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.1:** When visible session history has no user-authored message, show the task description as the first user prompt.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.2:** Keep the task description visible while agent or environment messages load.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.3:** Treat a visible, stored user message as authoritative. Do not also show the task-description fallback in this case.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.4:** When the user scrolls to the oldest loaded point, load older history without a separate button action.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.5:** Continue automatic loading while older pages only extend a collapsed activity row.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.6:** Do not require another user action before a new standalone transcript entry appears.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.7:** Stop automatic loading in these cases:
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.8:** Older content moves the load boundary above the preload region.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.9:** When the first user prompt of a session is loaded, the transcript shall not show an older-page control.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.10:** When a previously opened session is revisited after more than one message page was persisted while it was inactive, the transcript shall reconcile to a contiguous newest window and upward pagination shall reach every persisted user prompt without gaps or duplicate rows.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.1:** When older session history remains and the loaded window contains no user-authored message, the transcript shall not show the task description as a user prompt.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.2:** The transcript shall show each stored user prompt at its chronological position after that prompt is loaded.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.3:** When prompt `#1` is loaded, the transcript shall treat it as the visible start and shall not expose older internal rows through transcript pagination or an older-page control.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.4:** When persisted history is exhausted without a stored user prompt, the transcript shall show a non-empty task description as the first user prompt and shall not add an empty fallback.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.5:** When the user reaches the oldest loaded edge, the transcript shall load older history without a separate button action.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.6:** After an older page commits, the transcript shall continue loading while the oldest-page sentinel remains in the preload region, whether the page extends a collapsed activity group or adds a standalone row.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.7:** Automatic older-history loading shall stop when the sentinel leaves the preload region, prompt `#1` is loaded, persisted history is exhausted, or a request fails to make progress.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.8:** When an older-page request fails or makes no progress while older history remains, the transcript shall show a retry control. Routine successful pagination shall not show this control.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.9:** The transcript shall keep the reader's current visual position stable while older content is inserted.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.10:** Opening a task shall request only the bounded newest window until the user navigates upward.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.11:** Desktop and mobile transcripts shall provide the same history boundary, continuous upward loading, recovery, and scroll-position behavior.
|
||||
- **AC-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001.12:** When a previously opened session is revisited after more than one message page was persisted while it was inactive, the transcript shall reconcile to a contiguous newest window and upward pagination shall reach every persisted user prompt without gaps or duplicate rows.
|
||||
|
||||
## Migrated source detail
|
||||
## Exclusions
|
||||
|
||||
## Why
|
||||
|
||||
The transcript can lose the original task prompt after a reload. Long activity
|
||||
groups can also make older history difficult to reach. An older page can add
|
||||
tool events only inside an existing collapsed row. The user then sees no new
|
||||
entry and must select **Load older messages** again.
|
||||
|
||||
Users need continuous upward navigation from the latest response to the first
|
||||
prompt. This requirement includes sessions with more than 100 tool events.
|
||||
|
||||
## What
|
||||
|
||||
- When visible session history has no user-authored message, show the task
|
||||
description as the first user prompt.
|
||||
- Keep the task description visible while agent or environment messages load.
|
||||
- Treat a visible, stored user message as authoritative. Do not also show the
|
||||
task-description fallback in this case.
|
||||
- When the user scrolls to the oldest loaded point, load older history without
|
||||
a separate button action.
|
||||
- Continue automatic loading while older pages only extend a collapsed activity
|
||||
row.
|
||||
- Do not require another user action before a new standalone transcript entry
|
||||
appears.
|
||||
- Stop automatic loading in these cases:
|
||||
- Older content moves the load boundary above the preload region.
|
||||
- The session start is reached.
|
||||
- A request makes no progress.
|
||||
- Keep the current reading position stable as older content appears above it.
|
||||
- Keep the explicit load action as a fallback for an error or a no-progress
|
||||
response.
|
||||
- Show the first prompt at the start after all older history is loaded.
|
||||
- Apply the same transcript rule on desktop and mobile.
|
||||
- Reconcile a revisited session to one contiguous newest window before older
|
||||
pagination resumes. Stale cached rows must not create an unreachable gap.
|
||||
|
||||
## Scenarios
|
||||
|
||||
### Agent-only history
|
||||
|
||||
- **GIVEN** a task has a description and visible agent or environment messages.
|
||||
- **GIVEN** the session has no visible user message.
|
||||
- **WHEN** the transcript loads or reloads.
|
||||
- **THEN** the task description remains the first message.
|
||||
- **THEN** the other visible messages follow it.
|
||||
|
||||
### Stored user prompt
|
||||
|
||||
- **GIVEN** a task has a description and a visible stored user message.
|
||||
- **WHEN** the transcript loads.
|
||||
- **THEN** the stored user message represents the prompt.
|
||||
- **THEN** the transcript does not show a duplicate task-description fallback.
|
||||
|
||||
### Empty task description
|
||||
|
||||
- **GIVEN** a task has no description and has agent-only history.
|
||||
- **WHEN** the transcript loads.
|
||||
- **THEN** the transcript does not add an empty fallback message.
|
||||
|
||||
### Collapsed activity spans older pages
|
||||
|
||||
- **GIVEN** a transcript has more than 100 tool events in one collapsed activity
|
||||
row.
|
||||
- **GIVEN** older pages contain no standalone transcript entry.
|
||||
- **WHEN** the user scrolls to the oldest loaded point.
|
||||
- **THEN** the transcript loads additional pages without repeated button
|
||||
actions.
|
||||
- **THEN** the current reading position remains stable.
|
||||
|
||||
### First prompt after complete pagination
|
||||
|
||||
- **GIVEN** the first prompt is older than the initial message window.
|
||||
- **WHEN** the user continues to scroll upward until the session start.
|
||||
- **THEN** the first prompt is visible at the start of the transcript.
|
||||
- **THEN** no older-page control remains.
|
||||
|
||||
### Revisit after inactive-session activity
|
||||
|
||||
- **GIVEN** a session was opened and its older rows remain cached.
|
||||
- **GIVEN** more than one newest-page window is persisted while that session is
|
||||
inactive.
|
||||
- **WHEN** the user revisits the session and navigates upward.
|
||||
- **THEN** the transcript exposes every persisted user prompt in chronological
|
||||
order without a skipped middle range or duplicate row.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Backfill or repair missing message records in the database.
|
||||
- Change message persistence, API contracts, or transcript ordering.
|
||||
- Expand activity groups by default.
|
||||
- Remove the explicit older-page fallback action.
|
||||
- Load the complete transcript before the user navigates upward.
|
||||
|
||||
## Implementation plan
|
||||
|
||||
- [Hide redundant older-message controls](../../../plans/hide-redundant-older-messages-control/plan.md)
|
||||
- [Reconcile inactive-session transcript windows](../../../plans/inactive-session-transcript-reconciliation/plan.md)
|
||||
- Backfill or repair of missing persisted message records.
|
||||
- Changes to backend message ordering or cursor contracts.
|
||||
- Loading the complete transcript before the user navigates upward.
|
||||
- Rendering internal rows that precede stored prompt `#1`.
|
||||
|
||||
@@ -8,161 +8,162 @@ owners:
|
||||
- kandev
|
||||
---
|
||||
|
||||
# Task Transcript History Visibility System Design
|
||||
# Task transcript history visibility system design
|
||||
|
||||
## Purpose and boundaries
|
||||
|
||||
This design defines the visible start of a task transcript. The first user prompt is the visible start, even when internal rows exist before it.
|
||||
This design defines how the task transcript distinguishes a bounded newest
|
||||
window from the visible conversation start. It keeps task opening bounded,
|
||||
loads older history only after upward navigation, and preserves prompt `#1` as
|
||||
the visible start even when older internal rows remain on the backend.
|
||||
|
||||
The design changes no backend query, message order, persistence rule, or API field. It uses the existing `prompt_index` message field.
|
||||
The design changes no backend query, persistence rule, message order, or API
|
||||
field. It uses existing cursor metadata and the existing `prompt_index` field.
|
||||
|
||||
## Requirement mapping
|
||||
|
||||
| Requirement | Design section |
|
||||
| --- | --- |
|
||||
| `REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001` | [Opening boundary](#opening-boundary), [Latest-window reconciliation](#latest-window-reconciliation), [Pagination boundary](#pagination-boundary), [Failure and compatibility](#failure-and-compatibility) |
|
||||
| Requirement | Design sections |
|
||||
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `REQ-UI-TASK-PROMPT-TRANSCRIPT-VISIBILITY-001` | [History state](#history-state), [Opening boundary](#opening-boundary), [Upward pagination](#upward-pagination), [Failure and recovery](#failure-and-recovery), [Responsive behavior](#responsive-behavior) |
|
||||
|
||||
## Components and responsibilities
|
||||
|
||||
- `useLazyLoadMessages` owns the visible pagination boundary for transcript consumers.
|
||||
- The session message fetch owns one bounded initial request for the newest message window.
|
||||
- `messages.metaBySession[sessionId].hasMore` keeps the raw backend `has_more` value.
|
||||
- `messages.metaBySession[sessionId].oldestCursor` names the oldest row in the
|
||||
contiguous loaded window, never an older row separated from the newest
|
||||
snapshot by an unloaded gap.
|
||||
- `messages.bySession[sessionId]` supplies the loaded messages and their prompt ordinals.
|
||||
- The native transcript and Prompt History panel consume the shared hook result.
|
||||
- The native transcript owns the upward-navigation intent and the visible top-boundary key.
|
||||
- The session message fetch owns one bounded newest-window request and records
|
||||
when authoritative pagination metadata has initialized.
|
||||
- `messages.metaBySession[sessionId]` owns raw `hasMore`, `oldestCursor`,
|
||||
initial/refetch loading, older-page loading, and history initialization.
|
||||
- `useSessionMessages` exposes the raw history state to chat composition.
|
||||
- `useProcessedMessages` filters and groups stored messages. It may synthesize
|
||||
the task-description fallback only after the session start is known.
|
||||
- `useLazyLoadMessages` owns the prompt-`#1` visible boundary and older-page
|
||||
requests. It keeps raw pagination available to explicit recovery consumers.
|
||||
- The native transcript owns upward intent, committed sentinel geometry,
|
||||
scroll restoration, and retry-control visibility.
|
||||
- `useLazyLoadSentinel` owns observer lifecycle and request serialization.
|
||||
- Transcript navigation uses only the messages that the transcript already loaded.
|
||||
- The hook also exposes an explicit raw-pagination loader for direct recovery consumers, such as session search.
|
||||
- `requestOlderMessages` keeps request coordination and raw cursor metadata unchanged.
|
||||
|
||||
The Prompt History panel already uses prompt `#1` as its terminal boundary. The transcript uses the same boundary through the shared hook.
|
||||
## History state
|
||||
|
||||
The frontend distinguishes these facts:
|
||||
|
||||
- **History initialized:** An authoritative newest-window response or boot
|
||||
payload supplied pagination metadata for the session.
|
||||
- **Raw history remains:** The backend reported `has_more: true`.
|
||||
- **Visible start loaded:** A loaded user message has `prompt_index === 1`.
|
||||
- **History exhausted:** History is initialized and raw history does not remain.
|
||||
|
||||
Default store values are not proof that history is exhausted. The session
|
||||
message metadata therefore records initialization separately from `hasMore`.
|
||||
Session deletion purges this state with the rest of the session transcript.
|
||||
|
||||
The task-description fallback is eligible only when all of these conditions
|
||||
are true:
|
||||
|
||||
1. History is initialized.
|
||||
2. Raw history is exhausted.
|
||||
3. No visible stored user message exists.
|
||||
4. The task description is non-empty.
|
||||
|
||||
A tool-only newest window with `has_more: true` does not satisfy this contract.
|
||||
It renders only the stored rows in that window until the user navigates upward.
|
||||
|
||||
## Opening boundary
|
||||
|
||||
The session message fetch requests only the newest bounded window when a task opens. A tool-only window does not start an automatic backfill.
|
||||
The session message fetch requests only the newest bounded window when a task
|
||||
opens. It does not paginate backward to locate a prompt. A live WebSocket row
|
||||
can join that contiguous newest window through the existing reconciliation
|
||||
rules.
|
||||
|
||||
`TaskChatPanel` does not load older pages to find the last prompt. The last-prompt action becomes available after the prompt enters the loaded window.
|
||||
The latest-window reconciliation contract remains unchanged:
|
||||
|
||||
If the newest window has no user message, the transcript shows the task-description fallback. Upward navigation then loads older pages through visible pagination.
|
||||
- An overlapping fetched suffix joins the cached contiguous window.
|
||||
- A disjoint cached prefix is removed before the fetched suffix becomes the
|
||||
new authoritative window.
|
||||
- The oldest cursor always names the oldest row in the contiguous window.
|
||||
|
||||
## Latest-window reconciliation
|
||||
The absence of a user row in the newest window neither starts background
|
||||
pagination nor authorizes the task-description fallback.
|
||||
|
||||
The frontend represents each session transcript as one contiguous loaded
|
||||
window. A latest-message fetch reconciles its bounded newest suffix with the
|
||||
rows already cached for that session:
|
||||
## Visible pagination boundary
|
||||
|
||||
- If the fetched suffix overlaps the cached window, deduplicate and retain the
|
||||
complete joined window. The oldest cursor remains the oldest row in that
|
||||
joined window.
|
||||
- If the fetched suffix does not overlap the cached window, the older cached
|
||||
rows cannot be joined under one pagination cursor. Replace that disjoint
|
||||
cache with the fetched suffix. Retain only live rows that arrived after the
|
||||
fetch started and therefore follow the response snapshot.
|
||||
- Set the oldest cursor from the actual contiguous boundary. A disjoint cached
|
||||
row must never become the cursor for the newest fetched suffix.
|
||||
Transcript pagination remains available while raw history remains and loaded
|
||||
messages do not contain user prompt `#1`. Loading prompt `#1` immediately
|
||||
removes the transcript sentinel and retry control, even if raw backend history
|
||||
contains internal rows before that prompt.
|
||||
|
||||
The dropped browser cache is not data loss. Persisted messages remain
|
||||
authoritative and are loaded again through normal upward pagination. This rule
|
||||
also preserves the bounded opening behavior: revisiting a session does not
|
||||
subscribe to inactive siblings or eagerly load its complete transcript.
|
||||
Payloads without prompt ordinals use raw exhaustion as the compatibility
|
||||
boundary. Session search can continue through the explicit raw loader when a
|
||||
backend search hit precedes the visible transcript start.
|
||||
|
||||
## Pagination boundary
|
||||
## Upward pagination
|
||||
|
||||
The frontend derives a visible `hasMore` value from two inputs:
|
||||
The transcript starts a load cycle when the user reaches the oldest loaded
|
||||
edge. Before each request it captures a stable rendered-row anchor. After the
|
||||
page commits, scroll restoration keeps that anchor at the same visual position.
|
||||
|
||||
1. The raw backend value is true.
|
||||
2. No loaded user message has `prompt_index` equal to `1`.
|
||||
Continuation uses committed sentinel geometry, not the identity of the oldest
|
||||
standalone row:
|
||||
|
||||
If both conditions are true, transcript consumers can request another page. If prompt `#1` is loaded, the shared hook reports no visible older history.
|
||||
1. Re-evaluate the sentinel against the transcript's preload region after
|
||||
React layout and scroll restoration commit.
|
||||
2. Continue when the sentinel remains in that region and visible pagination
|
||||
still has more history.
|
||||
3. Stop when inserted content moves the sentinel outside the region. A later
|
||||
upward reach starts the next cycle through the normal observer path.
|
||||
4. Stop at prompt `#1`, raw exhaustion, a stale session, or no progress.
|
||||
|
||||
The hook applies this rule to its reactive return value. It also applies the rule after each joined or completed request.
|
||||
This rule crosses both collapsed activity pages and short standalone pages. It
|
||||
also avoids cascading through content that has already moved above the user's
|
||||
current preload region. A stale IntersectionObserver entry is not sufficient
|
||||
to continue; the decision uses geometry from the current sentinel and current
|
||||
scroll root after commit.
|
||||
|
||||
This immediate update stops one multi-page load operation at prompt `#1`. It prevents an extra request for pre-prompt internal rows.
|
||||
## Failure and recovery
|
||||
|
||||
The store keeps the raw backend value. Direct recovery code can use the hook's explicit raw-pagination loader when its contract requires the complete message stream. Session search uses this path because backend search can return a hit from before prompt `#1`. Transcript rendering and navigation continue to use visible pagination, so this recovery path does not restore the older-page control.
|
||||
A rejected request or a zero-row response with visible history still remaining
|
||||
sets a transcript-local recovery state. While that state is active, the normal
|
||||
automatic cycle is disarmed and the explicit older-page retry control is
|
||||
visible. A successful retry clears recovery state and resumes the geometry
|
||||
rule. Session changes, prompt `#1`, and raw exhaustion also clear it.
|
||||
|
||||
## Upward load cycle
|
||||
|
||||
An upward user action starts one transcript load cycle. The cycle starts when the reader reaches the oldest loaded boundary.
|
||||
|
||||
The transcript records the oldest standalone message key before each request. This key excludes the task-description fallback, transient status rows, and collapsed activity-group keys that can change when older tools join the group.
|
||||
|
||||
After React commits the prepended page, the transcript compares the current key with the recorded key:
|
||||
|
||||
- If the key changes, the page added a new visible top entry. The cycle stops until the reader reaches the new boundary.
|
||||
- If the key does not change, the page only extended the current collapsed activity group. The cycle can request the next page.
|
||||
- If the request fails, returns no rows, reaches prompt `#1`, or exhausts raw history, the cycle stops.
|
||||
|
||||
The shared sentinel must not continue from a stale intersection value. A completed request must use the committed render boundary before it starts another request.
|
||||
|
||||
Scroll restoration remains part of the same cycle. The transcript restores one stable row after each prepend. The restoration does not create new upward-navigation intent.
|
||||
|
||||
## Control flow
|
||||
|
||||
1. The initial message request stores one newest suffix and raw pagination metadata.
|
||||
2. The fetch reconciles that suffix with any cached rows as one contiguous
|
||||
window and records its true oldest cursor.
|
||||
3. The shared hook reports visible older history while prompt `#1` is absent.
|
||||
4. The user reaches the oldest loaded point.
|
||||
5. An older-page request prepends messages through the existing coordinator.
|
||||
6. The native transcript preserves a stable message-row position across the complete request.
|
||||
7. The transcript compares the committed visible top boundary with the request baseline.
|
||||
8. If the boundary changed, the current load cycle stops.
|
||||
9. If only a collapsed activity group changed, the same cycle can request another page.
|
||||
10. If the page contains prompt `#1`, the shared hook changes its visible value to false.
|
||||
11. The transcript removes its sentinel, loading state, and older-page control.
|
||||
12. Explicit reverse search uses raw pagination when it must backfill a backend search hit.
|
||||
|
||||
## Failure and compatibility
|
||||
|
||||
If a request fails before prompt `#1` is known, the explicit older-page control remains available. A zero-result response keeps the existing retry behavior.
|
||||
|
||||
If a latest fetch is disjoint from a stale cache, the UI temporarily stops
|
||||
rendering the stale prefix rather than presenting a false contiguous window.
|
||||
The older-page control remains available from the fetched suffix and reloads
|
||||
that durable history from the correct cursor.
|
||||
|
||||
An initial tool-only window completes without an older-page request. The task-description fallback remains visible until upward pagination loads a stored user prompt.
|
||||
|
||||
Older payloads can omit `prompt_index`. In this case, the shared hook uses raw `has_more` exhaustion as the compatibility fallback.
|
||||
Routine successful pagination does not render the retry control. The control
|
||||
keeps the existing localized label and has a coarse-pointer hit area of at
|
||||
least 44 pixels without increasing fine-pointer desktop density.
|
||||
|
||||
## Observability
|
||||
|
||||
The `messages:pagination` debug namespace records one start event and one settle event for each older-page request.
|
||||
|
||||
The events include the session ID, trigger, page count, visible boundary keys, scroll geometry, and the continuation reason. The events do not include message content.
|
||||
|
||||
The settle reason distinguishes collapsed-group continuation from visible-boundary stop, exhaustion, no progress, and request error.
|
||||
The `messages:pagination` namespace records page start and settle events
|
||||
without message content. Settle events include the session, trigger, count,
|
||||
raw and visible boundaries, committed sentinel geometry, continuation, and
|
||||
stop reason. Recovery entry and exit use distinct reasons so a real request
|
||||
failure is distinguishable from leaving the preload region.
|
||||
|
||||
## Responsive behavior
|
||||
|
||||
Desktop and mobile use the same native transcript and one vertical scroll owner. This change adds no mobile surface, control, or touch behavior.
|
||||
Desktop and mobile continue to use the existing full-height task Chat surface,
|
||||
shared store, shared hooks, and one vertical transcript scroll owner. No new
|
||||
mobile composition or navigation is introduced. The recovery button uses the
|
||||
same placement on both surfaces with a coarse-pointer touch target.
|
||||
|
||||
The existing full-height mobile task layout remains the nearest mobile exemplar. The mobile pagination scenario proves the same load-cycle boundary.
|
||||
The nearest mobile exemplar is `apps/web/components/task/task-layout.tsx` and
|
||||
the existing `mobile-message-pagination.spec.ts` flow. The mobile scenario
|
||||
must prove the same continuous loading, true-start fallback, recovery, and
|
||||
anchor behavior as desktop.
|
||||
|
||||
## Test boundaries
|
||||
|
||||
- A hook test covers raw `has_more: true` with loaded prompt `#1`.
|
||||
- A hook test covers the compatibility path when the ordinal is absent.
|
||||
- A hook test proves that a multi-page load stops when a response adds prompt `#1`.
|
||||
- Hook and drain tests prove that explicit search backfill can continue through the raw boundary.
|
||||
- Desktop and mobile browser tests seed hidden pre-prompt rows and prove that no older-page control remains.
|
||||
- Desktop and mobile browser tests prove that task opening makes no request with an older-page cursor.
|
||||
- A message-fetch test proves that a tool-only initial window completes without automatic backfill.
|
||||
- Latest-window reconciliation tests cover overlapping windows, a disjoint
|
||||
stale cache, and live rows received while the fetch is in flight.
|
||||
- A same-task sibling-session browser test caches an older receiver window,
|
||||
persists a peer prompt plus more than one page while the receiver is
|
||||
inactive, revisits it, and reaches the attributed prompt through upward
|
||||
pagination.
|
||||
- Separate desktop and mobile browser tests preserve the prepend anchor while loading older pages.
|
||||
- Desktop and mobile browser tests prove that one upward action loads only one page when that page adds visible entries.
|
||||
- A collapsed-activity browser scenario proves that the same load cycle continues until a new visible top entry appears.
|
||||
- Sentinel unit tests prove that stale intersection state cannot start a second visible-page request.
|
||||
|
||||
## Related design
|
||||
|
||||
- [Prompt History Panel](prompt-history-panel.md) defines the `prompt_index` contract and its compatibility behavior.
|
||||
- Processed-message tests cover an uninitialized window, a tool-only window
|
||||
with older history, exhausted legacy history, an empty description, and a
|
||||
loaded stored prompt.
|
||||
- Session-state tests cover initialization through boot hydration, newest
|
||||
fetch, purge, and refetch without inferring exhaustion from defaults.
|
||||
- Sentinel tests cover committed in-region continuation, out-of-region stop,
|
||||
stale observer entries, no-progress recovery, successful retry, and session
|
||||
reset.
|
||||
- Native transcript tests cover recovery-control visibility and prepend anchor
|
||||
preservation.
|
||||
- Desktop and mobile browser tests seed more than twenty older pages between
|
||||
the newest window and the latest user prompt. They prove that no synthetic
|
||||
initial prompt or routine retry control appears and that one upward
|
||||
navigation reaches the stored prompt without a click.
|
||||
- Existing prompt-`#1`, hidden pre-prompt, and inactive-session reconciliation
|
||||
scenarios remain covered.
|
||||
|
||||
Reference in New Issue
Block a user