Terminal User Interface (TUI)
Relevant source files
The following files were used as context for generating this wiki page:
The Terminal User Interface (TUI) in Noesis provides a conversational, text-based environment for interacting with the autonomous compounding system. Its primary purpose is to render read models of the agent's state, facilitate conversational dialogue between the user and the assistant, and expose expert controls for managing the system's learned adaptations. The TUI is designed to be ephemeral, consuming runtime data through a narrow port rather than owning durable state or policy.
Architecture-wise, the TUI is decoupled from the project's core logic (ledger, capabilities, and protected policy) to ensure that the interface remains a pure representation of the underlying system status. It leverages the @earendil-works/pi-tui library for terminal rendering, including complex elements like Markdown support, responsive layouts, and interactive components.
Sources: packages/tui/src/rendering.ts:1-24, AGENTS.md:16-18, plans/compounding-partnership-product-loop.html:1052-1060
Architecture and Design Principles
The TUI architecture adheres to strict boundary rules to maintain system integrity. It interacts with the rest of the Noesis ecosystem through a narrow runtime port, which prevents the UI from directly accessing or mutating internal storage components like the WorkspaceStore or ExperienceLedger.
Component-Based Rendering
The TUI uses a component-based approach where different parts of the screen (header, transcript, status bar, and input) are treated as separate rendering units. These components are reactive to the NoesisTuiState.
The diagram shows how the NoesisTuiState flows into specialized renderers within the TUI package to produce terminal output.
Sources: packages/tui/src/rendering.ts:468-520, packages/tui/test/architecture.test.ts:9-26
Layout and Responsiveness
The TUI implements a responsive layout system that adjusts based on terminal dimensions. It classifies the width into three categories: wide, normal, and narrow, and modifies the header and status field density accordingly.
| Layout Class | Width Threshold | Header Mode | Features Enabled |
|---|---|---|---|
| Wide | >= 120 columns | ASCII Wordmark | Full status fields, token counts, capability versions |
| Normal | >= 80 columns | Compact | Essential status (execution, model, context %) |
| Narrow | < 80 columns | None / Compact | Minimized status, elided model names |
Sources: packages/tui/src/rendering.ts:50-100, packages/tui/test/rendering.test.ts:250-265
Core Rendering Logic
The TUI utilizes advanced text processing to handle complex outputs, including Markdown, ANSI styling, and mathematical notation.
Rich Text and Markdown
The renderRichText function processes raw strings into a list of terminal-safe lines. It specifically handles:
- Markdown Handling: Uses
pi-tuito render headings, links, and code blocks with configurable color themes. - Math Delimiters: Detects and protects LaTeX-style math (e.g.,
$$ ... $$or\[ ... \]) from being mangled by Markdown parsers, rendering them in specialized "math blocks". - ANSI Sanitization: Neutralizes unauthorized model-provided ANSI escape sequences to prevent terminal corruption while applying its own theme-based styling.
Sources: packages/tui/src/rendering.ts:285-330, packages/tui/test/rendering.test.ts:125-160
The Transcript Renderer
The TranscriptRenderer is responsible for displaying the conversation history. It implements performance optimizations to handle long sessions:
- Virtualization: It only parses and renders semantic blocks that fall within the current viewport (defined by
transcriptRows). - Caching: It uses a
WeakMapcache to store rendered blocks, keyed by a combination of message content, terminal width, and color settings. This avoids redundant re-parsing of static history during streaming updates.
The sequence diagram illustrates the caching mechanism used to minimize rendering overhead during active dialogue.
Sources: packages/tui/src/rendering.ts:365-430, packages/tui/test/rendering.test.ts:310-330
User Experience and Controls
The TUI provides the user with high-level awareness of the agent's autonomous activities without cluttering the main conversation.
Status and Metadata
The bottom "chrome" of the TUI contains essential operational metadata, rendered via renderBottomChrome:
- Execution State: Displays the current status (IDLE, THINKING, STREAMING, TOOL, ERROR) with color-coded indicators.
- Context Usage: Shows the percentage and raw token count of the context window currently consumed.
- Model Info: Identifies the provider and model (e.g.,
openai/gpt-4o) currently active. - Capability Versions: In inspection panes, the TUI displays the exact versions of active capabilities pinned to the current turn.
Sources: packages/tui/src/rendering.ts:110-150, packages/tui/test/rendering.test.ts:340-355
Expert Commands
While the interface prioritizes a natural conversation, it supports "slash commands" for direct system intervention:
/why: Explains the active turn, including retrieved context and adaptation lineage./changes: Lists recent experiments and activations./revert: Restores the previous active capability revision./criteria: Inspects or manages learned user preferences.
Sources: plans/compounding-partnership-product-loop.html:1052-1070, AGENTS.md:12-15
Security and Architecture Constraints
The TUI is strictly isolated from the system's "Protected Control Plane."
- No Direct Mutation: The TUI can request operations (like approving a capability), but the actual mutation occurs in the runtime after receipt verification.
- No Durable State: As per
AGENTS.md, TUI components never own durable state. All information is derived from theNoesisTuiStateprovided by the runtime. - Forbidden Imports: Architecture tests ensure the TUI package does not import
@noesis/policy,@noesis/workspace, or@noesis/ledger.
// Example of an architecture test enforcing TUI boundaries
// Sources: [packages/tui/test/architecture.test.ts:9-25]
const forbiddenModules = [
"@noesis/capabilities",
"@noesis/ledger",
"@noesis/learning",
"@noesis/policy",
"@noesis/workspace",
] as const;
// Logic verifies that TUI source files do not contain imports from these modules.
Summary
The Noesis TUI serves as the primary observability and control layer for the autonomous system. By following a strict "read-model only" architecture and utilizing a high-performance, responsive rendering engine, it provides a stable interface for managing complex agent behaviors and compounding improvements. Its design ensures that while the agent's logic may evolve autonomously, the user remains in control through clear evidence-backed explanations and explicit intervention commands.