docs: design activity log and CTE layout fixes

2026-07-14 22:33:30 +02:00
parent 2759076db9
commit 2da2df58ca
1 changed files with 152 additions and 0 deletions
@@ -0,0 +1,152 @@
 # Complete Activity Log and CTE Plan Layout Design
 ## Goal
 Restore the left Model activity panel as a complete chronological log for the current live turn,
 starting with the user's prompt in Phase 1, while keeping tool details sanitized. Improve the
 Phase 6 CTE plan form so every CTE has reliable internal padding, clear hierarchy, responsive
 wrapping, and a dense but readable review layout.
 ## Confirmed Root Causes
 ### Empty activity panel
 Commit `c7474f3` changed `ModelActivityPanel` from the assistant transcript to the dedicated
 `activity` array populated only by Pi `thinking_delta` events. That made reasoning distinct from
 final assistant text, but it also made the panel empty for models that do not emit reasoning.
 The live local Qwen model declares `reasoning: false`, so no `thinking_delta` is expected.
 ### Missing CTE padding
 The project uses Tailwind CSS 3.4, while the shared `Card` primitive uses Tailwind 4 syntax such as
 `px-(--card-spacing)` and `--spacing(4)`. The build emits an unusable custom-property value and no
 working horizontal or vertical padding declarations for `CardHeader` and `CardContent`. The CTE
 viewer's valid child gaps remain, but its sections sit against the outer card edges.
 ## Activity Timeline Contract
 The frontend store owns one in-memory chronological activity timeline for the current live
 session. It is not persisted and is cleared by the existing session reset behavior.
 Each timeline entry has a stable semantic kind and display-safe fields:
 - `prompt`: user question, gate choice, or steering text recorded locally;
 - `thinking`: model reasoning chunks when the provider emits them;
 - `assistant`: visible assistant text chunks;
 - `tool`: sanitized tool lifecycle with tool name, correlation id, and
  `running | completed | failed` status;
 - `gate`: reviewer request and phase metadata;
 - `status`: backend informational, warning, or sanitized error text;
 - `lifecycle`: model turn start/end markers.
 The current phase is captured on each entry when known. The new-question submit path sets Phase 1
 and records the question before awaiting session creation, so the first timeline row is always
 attributable to F1. Gate choices and steering text are recorded only after their requests succeed,
 preserving the existing retry semantics. Resume starts a fresh timeline at the resume action
 because historical chat/activity is not persisted.
 Streaming `thinking` and `assistant` chunks coalesce only with the immediately preceding entry of
 the same kind. Tool completion updates the matching running entry by correlation id instead of
 creating a disconnected duplicate. All other events append in arrival order.
 ## Backend Event Mapping and Sanitization
 `SessionBridge` continues to map reasoning and assistant text separately. It additionally maps Pi
 `tool_execution_start` and `tool_execution_end` to a dedicated client activity event containing
 only:
 - tool call id;
 - tool name;
 - lifecycle status.
 Tool arguments, partial results, final results, command output, request bodies, credentials, paths
 derived from results, and raw exception text must never be forwarded. Existing sanitized provider
 error behavior remains unchanged. Tool update events are ignored because their payload is raw
 partial output and the running row already communicates progress.
 The existing `ui_request`, `info`, `agent_start`, and `agent_end` events remain authoritative and
 are also projected into timeline rows by the frontend store.
 ## Model Activity Panel
 The panel renders the full timeline rather than a reasoning-only tail. Opening or closing it does
 not alter store state. It uses the existing scrollable panel and automatically follows the newest
 entry while the user remains near the bottom; manual upward scrolling is not overridden.
 Rows use restrained product-UI styling:
 - phase and kind labels form the compact metadata layer;
 - prompt and assistant rows use normal body text;
 - thinking text remains visually secondary;
 - tool rows expose name and status without expandable raw details;
 - warnings and errors use existing semantic colors.
 The central status component keeps its compact assistant-text tail and is not replaced by the full
 timeline.
 ## CTE Plan Layout
 ### Card primitive compatibility
 Replace the Tailwind 4-only spacing syntax in the shared `Card` primitive with Tailwind 3-compatible
 utilities. Default cards use the existing 4-point scale at 16 px; the small variant uses 12 px.
 Header, content, footer, parent gap, and vertical padding must all compile to concrete declarations.
 The CTE viewer is currently the only consumer, limiting regression scope.
 ### Information hierarchy
 Question, strategy, and execution order form one compact overview group. Labels identify their
 roles without decorative color. The overview uses tight 8–12 px internal spacing and a 24 px gap
 before the ordered CTE sequence.
 Each CTE remains one ordered outer container because the boundary has semantic value. It uses a
 border without an additional decorative shadow inside the already elevated gate. The ordinal badge
 and CTE name lead the header; the name is a semantic heading. Purpose remains subordinate.
 ### Internal rhythm
 - Card edge padding: 16 px by default, 20 px when the available width permits it.
 - Related labels, values, and chips: 4–8 px.
 - Rows and closely related blocks: 12–16 px.
 - Major body groups: 20–24 px.
 Tables and filters render as padded rows separated by dividers within one boundary, not as nested
 shadowed cards. Rationale becomes a final plain section separated with a top divider; the prohibited
 colored side stripe is removed. Primary color remains reserved for state/order emphasis.
 Long CTE names, table names, columns, filter values, and chips wrap within their containers. Filter
 metadata becomes multi-column only at a width where all fields remain readable; otherwise it stays
 stacked. Shared gate buttons, artifact contracts, colors, and non-CTE viewers are out of scope.
 ## Accessibility and Responsive Behavior
 - The CTE name uses heading semantics in document order.
 - Timeline rows include readable text labels and never rely on color alone for status.
 - Tool status changes remain understandable without animation.
 - The panel and CTE form preserve keyboard scrolling and existing focus behavior.
 - No new interactive control is introduced by the CTE viewer.
 ## Testing and Verification
 Tests are written before production changes and must prove:
 - the F1 prompt is the first timeline entry before session creation completes;
 - non-reasoning models still produce prompt, assistant, tool, gate, and lifecycle rows;
 - thinking/assistant chunks coalesce without losing chronological ordering;
 - tool start/end update one sanitized entry and raw args/results never cross the bridge;
 - opening and closing the panel preserves the timeline;
 - automatic following stops while the user has scrolled away from the bottom;
 - CTE cards compile/use explicit padding classes and preserve wrapping/section structure;
 - filter rows, rationale divider, semantic heading, and responsive grouping render as designed.
 Run focused backend/frontend tests, full suites, TypeScript gates, production builds, the Impeccable
 layout detector, and `git diff --check`. Build and force-recreate `core` and `frontend`, then verify
 core health, the frontend asset update, and a live session whose Phase 1 panel shows prompt plus
 subsequent sanitized activity.
 ## Out of Scope
 - Persisting or replaying historical chat/activity across processes or browser reloads.
 - Showing raw tool arguments, results, partial output, commands, or exception details.
 - Changing model thinking configuration or provider definitions.
 - Redesigning shared reviewer controls or non-CTE artifact viewers.