diff --git a/docs/features/coding_assistant.md b/docs/features/coding_assistant.md new file mode 100644 index 0000000..f5edab0 --- /dev/null +++ b/docs/features/coding_assistant.md @@ -0,0 +1,98 @@ +# Feature Reference: Coding Assistant Interface + +This document serves as the comprehensive reference for the **Coding Assistant** interface in the Cortex platform (`CodingAssistantPage.js`). It describes the UI structure, design philosophy, user journeys, and technical integration with the Agent Node Mesh. + +--- + +## 1. UI Overview & Layout Structure + +The Coding Assistant page is the centralized workspace for AI-assisted software development. It features a responsive flex layout combining session management, conversational AI, and distributed node orchestration within a single unified view. + +### A. Global Layout Array +- **Sidebar (`SessionSidebar.js`)**: Located on the left, handles session history, switching, and creating new conversations. +- **Main Workspace (`CodingAssistantPage.js`)**: Occupies the center/right area, framing the main conversation and control elements. + +### B. Workspace Header +- **Title Block**: Displays the "Coding Assistant" title and an at-a-glance mesh summary (e.g., `Mesh: 2 Online / 5 Total`). +- **Node Attachment Bar (M3/M6)**: + - Horizontally scrollable list of nodes accessible to the user. + - Color-coded badges with pulsing green status indicators for live nodes. + - Hovering over a node displays its current status (`IDLE`, `BUSY`) and attachment state (`Attached to Session`). + - **Quick Action Icons**: + - **Manage Mesh Nodes**: Opens the detailed Node Selector modal. + - **Toggle Execution Console**: Reveals/hides the bottom `MultiNodeConsole` (only visible when nodes are attached). + - **Session Engine (Gear)**: Opens LLM provider configurations. +- **Resource Monitors**: + - **Token Usage Bar**: Gradient progress bar (Indigo to Red) tracking context window saturation. + - **New Chat Button**: Instantly provisions a fresh session. +- **Configuration Warnings**: Highlights missing keys or LLM configuration requirements via tooltips. + +### C. Conversational Arena (`ChatArea.js` & `ChatWindow.js`) +- **Scrollable Chat Window**: Renders the conversation history between the user and the AI. +- **Rich Message Rendering (`ChatMessage`)**: + - **Markdown Support**: Full GitHub-flavored markdown rendering. + - **Collapsible Reasoning**: AI "thought processes" can be toggled via "Show Reasoning ▼" to reduce visual clutter. + - **Code Change Plan (`CodeChangePlan.js`)**: Formats systematic step-by-step implementation plans generated by the AI. + - **File diff viewer (`DiffViewer.js` & `FileList.js`)**: Allows clicking on modified files to view inline diffs of suggested code changes. + - **Utilities**: One-click copy, timestamp display, and playback tools (primarily leveraged if Voice Chat features overlap). +- **Sticky Input Bar**: Standard auto-resizing text area for sending instructions to the active LLM. + +### D. Multi-Node Execution Console (`MultiNodeConsole.js`) +- **Position**: Anchored at the bottom of the workspace (when toggled active). +- **Purpose**: A live WebSocket-powered gRPC stream multiplexer. +- **Layout**: Splits vertically for each attached node, displaying: + - Node Identity and Real-time Metrics (CPU, Memory, Active Workers) in the sub-header. + - Streaming event log (Task assignments, execution progress, errors, browser orchestration events, sync status). + - Auto-scrolling terminal window. + +--- + +## 2. Expanded Feature Modals + +### A. Mesh Node Selection Modal +- **Purpose**: Map raw compute nodes to the current chat session. +- **Initialization Strategy**: + - **Empty**: Boot up the execution context with a clean slate. + - **Sync from Server**: Clone the master "Ghost Mirror" codebase state down to the execution nodes. + - **Initialize from Node**: Use an existing local absolute path on the node (useful for massive pre-existing local repositories). +- **Attachment Controls**: List of nodes with one-click `ATTACH` / `DETACH` functionality. + +### B. Session Engine Overlay (LLM Config) +- **Purpose**: Switch the logical "Brain" powering the assistant on the fly. +- **Controls**: Dropdown selector parsing through registered providers and models available to the user based on their platform configuration. + +### C. Error Handling Modal +- **Purpose**: High-visibility attention grabber for critical context or backend errors that halt execution. + +--- + +## 3. Core Capabilities & User Journey + +### Journey: AI-Driven Multi-Node Orchestration +1. **Initialize**: User navigates to the Coding Assistant and starts a `/new` session. +2. **Attach Compute**: User clicks the Mesh Node Selector icon, selects a strategy (e.g., `Sync from Server`), and attaches an available (green) node like `test-node-1`. +3. **Monitor Execution**: The user instructs the AI: *"Run the backend unit tests."* +4. **Visibility**: The `MultiNodeConsole` opens automatically. The user sees the AI dispatching commands over the Execution Live Bus. +5. **Review Modifications**: If the AI patches a broken test, the AI replies with a `CodeChangePlan`. The user clicks the diffs in the `ChatWindow` to verify the code visually. +6. **Commit**: The files are automatically synced back upward via the node's local sync daemon. + +--- + +## 4. Source Code Mapping + +| Component | UI Purpose | Source Path | +| :--- | :--- | :--- | +| `CodingAssistantPage.js` | Main layout, state coordination, node linking | `ui/client-app/src/pages/CodingAssistantPage.js` | +| `ChatArea.js` | Layout wrapper for scroll behavior and text input | `ui/client-app/src/components/ChatArea.js` | +| `ChatWindow.js` | Complex message rendering, reasoning toggles, diff triggers | `ui/client-app/src/components/ChatWindow.js` | +| `MultiNodeConsole.js` | Bottom-anchored live WebSocket log stream | `ui/client-app/src/components/MultiNodeConsole.js` | +| `DiffViewer.js` | Inline code comparison (Before/After) | `ui/client-app/src/components/DiffViewer.js` | +| `apiService.js` | Backend hooks for `attachNodesToSession`, LLM fetching | `ui/client-app/src/services/apiService.js` | + +--- + +## 5. Architectural Principles + +- **Separation of Concerns**: The AI's conversational context/history is completely decoupled from the actual Node execution state. The UI simply acts as a bridge displaying both simultaneously. +- **Stateless Client Polling**: The React layer assumes the backend is the source of truth for node attachments. It polls `getSessionNodeStatus` every 5 seconds to ensure the top-bar badges reflect reality. +- **Responsive Degradation**: If no nodes are available, the interface degrades gracefully back into a standard LLM chat interface, abstracting away orchestration complexities from standard users.