docs: design model activity signal filter

2026-07-15 03:10:10 +02:00
parent ffef01eb0a
commit eef4cf0f50
1 changed files with 108 additions and 0 deletions
@@ -0,0 +1,108 @@
 # Model Activity Signal Filter Design
 **Date:** 2026-07-15
 ## Goal
 Keep the left **Model activity** panel useful without exposing low-level execution chatter. The
 panel must show the user's prompt, genuine model reasoning when the provider emits it, meaningful
 status messages, and reviewer gates. It must not show assistant narration, tool lifecycle rows, or
 turn lifecycle rows.
 ## Current behavior and root cause
 `sessionStore` intentionally builds a complete chronological `activityLog` containing prompt,
 thinking, assistant, tool, gate, status, and lifecycle entries. `ModelActivityPanel` currently
 renders every entry in that array. As a result, a non-reasoning model can fill the panel with rows
 such as `tool / completed / bash`, `lifecycle / Turn end`, and assistant narration such as
 "Let me try...".
 Those events are useful to workflow state, replay, the central transcript, and diagnostics, but
 they are not all suitable for the user-facing activity panel.
 ## Visibility contract
 The panel uses an explicit allowlist:
 | Activity kind | Visible | Purpose |
 | --- | --- | --- |
 | `prompt` | Yes | Shows the question or reviewer input that started the work. |
 | `thinking` | Yes | Shows genuine reasoning/COT when the configured provider emits it. |
 | `status` | Yes | Shows meaningful informational, warning, and error milestones. |
 | `gate` | Yes | Shows that the workflow reached a reviewer decision point. |
 | `assistant` | No | Avoids exposing operational narration; user-facing assistant text remains in the central transcript. |
 | `tool` | No | Avoids repetitive implementation details such as `bash completed`. |
 | `lifecycle` | No | Avoids transport/turn noise such as `Turn end`. |
 This is a strict kind-based contract. The UI must not guess whether a particular assistant sentence
 is "internal" or "final" by matching text. Such heuristics would be language-dependent and brittle.
 ## Architecture and data flow
 The filter belongs at the rendering boundary in `ModelActivityPanel`:
 1. `SessionBridge` continues to sanitize and emit tool/system events.
 2. `sessionStore` continues to fold every event into the complete in-memory `activityLog` and to
   update transcript, current phase, pending gate, and agent-active state exactly as today.
 3. `ModelActivityPanel` derives `visibleActivity` from the allowlisted kinds and renders only that
   projection.
 Keeping ingestion unchanged preserves the existing SSE/replay, tool correlation, end-of-turn,
 resume, and diagnostic contracts. It also keeps the central transcript independent: hiding an
 `assistant` entry from the left panel does not remove it from `transcript`.
 The visibility predicate should be a small exported pure function or a named exported kind set so
 the contract can be tested directly without duplicating conditions in test code.
 ## Interaction details
 - The empty state is based on `visibleActivity.length`, not the raw log length. If only hidden
  events have arrived, the panel displays `No activity yet.` instead of a visually empty viewport.
 - Automatic bottom-following reacts only when the visible tail changes. The effect must depend on
  the identity of the last visible entry (and the visible count), not merely on a newly allocated
  filtered array. Hidden tool, assistant, or lifecycle events therefore cannot move a reader's
  scroll position, while appended or streamed visible entries still follow correctly.
 - Phase, level, Markdown rendering, accessibility labels, close behavior, and the 48 px
  near-bottom threshold remain unchanged for visible rows.
 - No new toggle, preference, expansion control, or raw-details view is introduced.
 ## Error and edge-case behavior
 - Unknown future activity kinds are hidden by default because they are not allowlisted.
 - Warning and error status rows remain visible and retain their textual severity labels.
 - A provider that emits no `thinking` still shows prompt/status/gate milestones; the panel does not
  synthesize reasoning from assistant narration or tool names.
 - Closing and reopening the panel does not mutate the underlying complete log or the visible
  projection.
 ## Testing
 Frontend tests must prove:
 1. A mixed F1 sequence renders prompt, thinking, status, and gate rows but does not render
   assistant narration, tool names/statuses, or lifecycle text.
 2. A hidden-only sequence produces the `No activity yet.` state.
 3. Assistant output still exists in the central transcript/store after being excluded from the
   activity panel.
 4. Hidden-only updates do not trigger bottom-follow scrolling; visible updates retain the existing
   near-bottom behavior.
 5. Warning/error labels, Markdown, closing/reopening, and the complete store fold remain covered by
   the existing regression suite.
 The implementation follows RED/GREEN TDD and runs the focused panel/store tests, the complete
 frontend suite, TypeScript, the production build, and `git diff --check`.
 ## Deployment
 Only the frontend is expected to change. Rebuild and force-recreate the frontend container, then
 restart only `omics_portal-web-1` if the Vite entry hash changes. Verify the running asset, container
 state, and a live Qwen no-COT session showing prompt/status/gate information without assistant,
 tool, or lifecycle rows.
 ## Out of scope
 - Changing backend event emission or the sanitization boundary.
 - Removing entries from `activityLog`.
 - Reclassifying assistant text through content heuristics or an LLM.
 - Changing the central transcript or workflow state machine.
 - Redesigning the panel layout beyond the visibility and empty/scroll behavior described above.