Session Picker & State Handlers
Relevant source files
The following files were used as context for generating this wiki page:
The Session Picker and associated state handlers constitute the core interaction layer of the Noesis Terminal User Interface (TUI). This system manages the transition between distinct work sessions, handles volatile UI state transitions, and provides sanitized input mechanisms to ensure terminal stability during complex asynchronous operations.
The architecture emphasizes a clean separation between ephemeral TUI state and the authoritative operational state stored in SQLite. While WorkspaceStore manages durable persistence, these handlers ensure that user interactions—such as selecting a session or editing a message—remain responsive and safe from malformed terminal escape sequences.
Sources: plans/noesis-autonomous-compounding-implementation-plan.html, packages/tui/src/state.ts:1-20
TUI State Management
The TUI operates using an ephemeral state model that tracks the current view, active session, and ongoing execution status. This state is reconstructed upon restart from runtime read models and does not hold durable policy.
State Data Structure
The TuiState interface captures the essential metrics and objects required for rendering the interface.
| Field | Type | Description |
|---|---|---|
mode | Mode | Current UI mode (e.g., chat, session-picker). |
sessionId | string | ID of the active work session. |
messages | Message[] | Local cache of session transcript messages. |
execution | ExecutionStatus | Tracks if the agent is idle, streaming, or thinking. |
error | string | null | Stores transient error messages for display. |
Sources: packages/tui/src/state.ts:25-60, packages/tui/test/rendering.test.ts:220-235
State Transitions
State handlers process interactions such as switching to the session picker or updating the transcript during a streaming response.
The flow shows how user actions trigger state updates, leading to mode changes and transcript reconstructions.
Sources: packages/tui/src/state.ts:80-110, packages/tui/test/rendering.test.ts:285-300
Session Picker Architecture
The Session Picker is a specialized UI component that allows users to navigate the history of sessions persisted in the WorkspaceStore. It retrieves session metadata, including IDs, timestamps, and brief excerpts, to present a searchable list.
Component Logic
The SessionPicker component implements a list-based navigation interface. It handles keyboard events (arrows, Enter, Escape) to select a session or return to the active chat.
- Data Retrieval: Fetches a summary of available sessions from the runtime port.
- Filtering: Provides real-time filtering of session IDs and descriptions based on user input.
- Selection: On confirmation, updates the
TuiState.sessionIdand triggers a full session re-initialization.
Sources: packages/tui/src/session-picker.ts:1-50, packages/tui/test/architecture.test.ts:15-30
Safe Editor and Input Handling
To prevent terminal instability, Noesis employs a SafeEditor wrapper around the base TUI editor. This handler sanitizes incoming data, specifically targeting malformed ANSI escape sequences and malicious bracketed-paste payloads.
Sanitization Strategy
The SafeEditor neutralizes dangerous control characters and ANSI sequences that could trigger unintended terminal actions (e.g., clearing the screen via \u001b[2J).
This diagram illustrates the interception and sanitization of raw terminal input before it reaches the internal text buffer.
Sources: packages/tui/src/safe-editor.ts:10-45.%0A%0A%60%60%60mermaid%0AsequenceDiagram%0A%20%20%20%20participant%20Terminal%20as%20Terminal%20Driver%0A%20%20%20%20participant%20Editor%20as%20SafeEditor%0A%20%20%20%20participant%20Buffer%20as%20TUI%20Text%20Buffer%0A%20%20%20%20Terminal-%3E%3EEditor%3A%20handleInput(rawBytes)%0A%20%20%20%20Note%20over%20Editor%3A%20Check%20for%20Escape%20Sequences%0A%20%20%20%20Editor-%3E%3EEditor%3A%20sanitizeEditorText(bytes)%0A%20%20%20%20Note%20over%20Editor%3A%20Strip%20C0/C1%20Controls%0A%20%20%20%20Editor-%3E%3EBuffer%3A%20update(sanitizedText)%0A%20%20%20%20Buffer--%3E%3EEditor%3A%20confirmation%0A%60%60%60%0AThis%20diagram%20illustrates%20the%20interception%20and%20sanitization%20of%20raw%20terminal%20input%20before%20it%20reaches%20the%20internal%20text%20buffer.%0ASources%3A%20%5Bpackages/tui/src/safe-editor.ts%3A10-45), packages/tui/test/rendering.test.ts:40-80
Key Handlers
The editor maintains specific bindings for terminal-specific behaviors:
- Grapheme Deletion: Preserves Unicode grapheme cluster deletion (e.g., complex emojis).
- Bracketed Paste: Detects start/end markers (
\u001b[200~to\u001b[201~) and treats the intervening content as a single sanitized block, preventing "paste-jacking." - Escape Ambiguity: Implements a timer-based settlement to distinguish between a standalone
Escapekey and the start of a functional escape sequence.
Sources: packages/tui/src/safe-editor.ts:50-95%20and%20treats%20the%20intervening%20content%20as%20a%20single%20sanitized%20block%2C%20preventing%20%22paste-jacking.%22%0A*%20%20%20Escape%20Ambiguity%3A%20Implements%20a%20timer-based%20settlement%20to%20distinguish%20between%20a%20standalone%20%60Escape%60%20key%20and%20the%20start%20of%20a%20functional%20escape%20sequence.%0A%0ASources%3A%20%5Bpackages/tui/src/safe-editor.ts%3A50-95), packages/tui/test/rendering.test.ts:90-130
Implementation Constraints
Architecture tests ensure that TUI handlers remain strictly separated from protected system internals.
| Constraint | Enforcement Method | Source File |
|---|---|---|
| No Ledger Access | TUI cannot import @noesis/ledger. | packages/tui/test/architecture.test.ts:10 |
| No Workspace Access | TUI cannot directly call WorkspaceStore. | packages/tui/test/architecture.test.ts:12 |
| Port-based Interaction | Interactions must use NoesisTuiRuntime port. | packages/tui/test/architecture.test.ts:25 |
| Code Size Limits | TUI modules must remain under 800 lines. | packages/tui/test/architecture.test.ts:42 |
Sources: packages/tui/test/architecture.test.ts:1-50
Conclusion
The Session Picker and State Handlers provide a robust, sanitized interface for interacting with the Noesis runtime. By isolating ephemeral UI state from the authoritative SQLite data and implementing strict input sanitization, the system ensures that complex historical navigation and text editing remain stable within the constraints of a terminal environment.