mirror of
https://github.com/openai/codex.git
synced 2026-05-03 21:01:55 +03:00
12779c7c07
### Problem Ctrl+T transcript overlay can omit in-flight coalesced tool calls because it renders only committed transcript cells while the main viewport can render the current in-flight ChatWidget.active_cell immediately. ### Mental model The UI has both committed transcript cells (finalized HistoryCell entries) and an in-flight active cell that can mutate in place while streaming, often representing a coalesced exec/tool group. The transcript overlay renders committed cells plus a render-only live tail derived from the current active cell. The live tail is cached and only recomputed when its cache key changes, which is derived from terminal width (wrapping), active-cell revision (in-place mutations), stream continuation (spacing), and animation tick (time-based visuals). ### Non-goals This does not change coalescing rules, flush boundaries, or when active cells become committed. It does not change tool-call semantics or transcript persistence; it is a rendering-only improvement for the overlay. ### Tradeoffs This adds cache invalidation complexity: correctness depends on bumping an active-cell revision (and/or providing an animation tick) when the active cell mutates in place. The mechanism is implemented in both codex-tui and codex-tui2, which keeps behavior consistent but risks drift if future changes are not applied in lockstep. ### Architecture App special-cases transcript overlay draws to sync a live tail from ChatWidget into TranscriptOverlay. TranscriptOverlay remains the owner of committed transcript cells; the live tail is an optional appended renderable. HistoryCell::transcript_animation_tick() allows time-dependent transcript output (spinner/shimmer) to invalidate the cached tail without requiring data mutation. ### Observability Manual verification is to open Ctrl+T while an exploring/coalesced active cell is still in-flight and confirm the overlay includes the same in-flight tool-call group the main viewport shows. The overlay is kept in sync by App passing an active-cell key and transcript lines into TranscriptOverlay::sync_live_tail; the key must change when the active cell mutates or animates. ### Tests Snapshot tests validate that the transcript overlay renders a live tail appended after committed cells and that identical keys short-circuit recomputation. Unit tests validate that active-cell revision bumps occur on specific in-place mutations (e.g. unified exec wait cell command display becoming known late) so cached tails are invalidated. ## Documentation patches (module, type, function) ### Module-level docs (invariants + mechanisms) - codex-rs/tui/src/app_backtrack.rs:1 - codex-rs/tui/src/chatwidget.rs:1 - codex-rs/tui/src/pager_overlay.rs:1 - codex-rs/tui/src/history_cell.rs:1 - codex-rs/tui2/src/app_backtrack.rs:1 - codex-rs/tui2/src/chatwidget.rs:1 - codex-rs/tui2/src/pager_overlay.rs:1 - codex-rs/tui2/src/history_cell.rs:1 ### Type-level docs (cache key + invariants) - codex-rs/tui/src/chatwidget.rs (ChatWidget.active_cell_revision, ActiveCellTranscriptKey) - codex-rs/tui/src/pager_overlay.rs (TranscriptOverlay live tail storage model) - codex-rs/tui/src/history_cell.rs (HistoryCell::transcript_animation_tick, UnifiedExecWaitCell::update_command_display) - Mirrored in codex-rs/tui2/src/chatwidget.rs, codex-rs/tui2/src/pager_overlay.rs, codex-rs/tui2/src/history_cell.rs ### Function-level docs (why/when/guarantees/pitfalls) - codex-rs/tui/src/app_backtrack.rs (overlay_forward_event) - codex-rs/tui/src/chatwidget.rs (active_cell_transcript_key, active_cell_transcript_lines) - codex-rs/tui/src/pager_overlay.rs (sync_live_tail, take_live_tail_renderable) - codex-rs/tui/src/history_cell.rs (transcript_animation_tick, UnifiedExecWaitCell::update_command_display) - Mirrored in codex-rs/tui2 equivalents where present ### Validation performed - cd codex-rs && just fmt - cd codex-rs && cargo test -p codex-tui - cd codex-rs && cargo test -p codex-tui2 ## Design inconsistencies / risks - Cache invalidation is a distributed responsibility: any future in-place active cell transcript mutation that forgets to bump active_cell_revision (or expose an animation tick) can leave the transcript overlay live tail out of sync with the main viewport. - TranscriptOverlay tail handling assumes a structural invariant that the live tail, when present, is exactly one trailing renderable after the committed cell renderables; if renderable construction changes in a way that violates that assumption, tail insertion/removal logic becomes incorrect. - codex-tui and codex-tui2 duplicate the live-tail mechanism; the documentation is aligned, but the implementation can still drift unless changes continue to be applied in lockstep.