# Feature Reference: Swarm Control Interface

This document serves as the comprehensive reference for the **Swarm Control** interface in the Cortex platform (`SwarmControlPage.js`). It describes the UI structure, terminal-centric design, and the "AI Observation" workflow.

---

## 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)**: 
  - **Compact Display**: Instead of listing all accessible nodes, the UI displays a compact visualization of currently *attached* nodes (e.g., overlapping indicators or a single summary pill). 
  - **File Sync Indicator**: If nodes are attached and a sync strategy is active (i.e., not 'empty'), an icon indicates that file sync is enabled. Hovering over this indicator reveals a tooltip with the exact mounting source (e.g., 'Server Sync' or 'Local Node Path: /workspace').
  - **Quick Action Icons**:
    - **Manage Mesh Nodes**: Opens the detailed Node Selector modal to attach/detach compute resources.
    - **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.
  - **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. Swarm Execution Terminal (`MultiNodeConsole.js`)
- **Position**: Anchored at the bottom of the workspace (when toggled active).
- **Purpose**: A real-time, terminal-centric viewport for monitoring distributed agent execution.
- **Xterm.js Integration**: Replaces legacy log lists with a high-performance terminal that renders ANSI colors and raw PTY output.
- **Read-Only Observation Mode**: The terminal is strictly read-only for users to preserve the integrity of the AI's execution context.
- **AI Context Banner**: Displays a prominent notice: *"Terminal Notice: This viewport is surfaced to AI. Leaving it empty preserves context integrity."*
- **Layout**: Splits vertically for each attached node, displaying:
  - **Live Hardware Header**: Real-time stats for CPU, Memory, and Active Workers.
  - **Command Transparency**: Displays the actual shell commands executed by the AI (e.g., `$ python test.py`).
  - **Auto-Scrolling**: High-velocity output handling with automatic scroll-to-bottom.

---

## 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**: Checkbox list of nodes to select or deselect.
- **Save & Sync Workflow**: Changes made in the modal are held in a draft state and only applied when the user explicitly clicks the **Save & Sync** button. Clicking **Cancel** instantly reverts the selections to the actual truth from the server.

### 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 Swarm Control page and starts a `/new` session.
2. **Attach Compute**: User attaches available nodes (e.g., `test-node-1`) with a chosen sync strategy.
3. **Observation Pulse**: The user instructs the AI: *"Analyze the logs in /var/log/syslog on all nodes."*
4. **Visibility**: The `Swarm Execution Terminal` slides up automatically. The user sees raw terminal output streaming in real-time.
5. **AI "Sight"**: The AI automatically reads the terminal history (via `GET /api/v1/nodes/{id}/terminal`) to observe results, even if they return non-zero exit codes.
6. **Stateful Interaction**: The AI uses the terminal's PTY session to maintain state (e.g., `cd` and environment variables) across multiple chat turns.
 
---

## 4. Source Code Mapping

| Component | UI Purpose | Source Path |
| :--- | :--- | :--- |
| `CodingAssistantPage.js` | Main layout, state coordination, node linking | `frontend/src/pages/CodingAssistantPage.js` |
| `ChatArea.js` | Layout wrapper for scroll behavior and text input | `frontend/src/components/ChatArea.js` |
| `ChatWindow.js` | Complex message rendering, reasoning toggles | `frontend/src/components/ChatWindow.js` |
| `MultiNodeConsole.js` | Bottom-anchored live WebSocket log stream | `frontend/src/components/MultiNodeConsole.js` |
| `apiService.js` | Backend hooks for `attachNodesToSession`, LLM fetching | `frontend/src/services/apiService.js` |

---

## 5. Architectural Principles

- **Terminal-First Observability**: The node execution interface is designed to mirror a real developer's console. This provides the AI with "eyes" on the raw system state and gives users confidence by showing exactly what commands are hitting their infrastructure.
- **Context Integrity**: By enforcing read-only terminals in the UI, we ensure that the terminal state seen by the AI (via the backend history buffer) always matches what the user sees in the viewport.
- **Stateless Client Polling**: The React layer assumes the backend is the authoritative source of truth for node attachments. It polls `getSessionNodeStatus` every 5 seconds to ensure the top-bar badges reflect reality. 
- **Multiplexed Resilience**: The WebSocket connection is multiplexed and self-healing, using a `wasIntentional` closing flag and content-based dependency tracking to prevent reconnection loops during rapid UI updates.

---

## 6. Advanced Mesh File Operations (M6+)

To support high-performance distributed refactoring and state management, the Swarm Control interface leverages an enhanced **Mesh File Explorer** capability.

### A. Atomic Mesh Operations
- **Atomic Move/Rename**: Enables restructuring the workspace without the overhead of data re-transfer. This triggers a single `MOVE` event across all synchronization nodes, ensuring consistency.
- **Mesh Copy**: Allows for rapid duplication of files or directories directly within the decentralized mirror, bypassing the need for AI-side buffering.
- **High-Speed Stat**: Provides instant access to file metadata (size, mod-time, existence) across the mesh through the Hub's local record, significantly reducing turn latency and token usage.

### B. Efficiency Patterns
- **Sync Locking**: Integrated safety mechanism to disable user-side watchers during complex AI-driven multi-file refactors, preventing race conditions.
- **Reconciliation Protocol**: Automated drift detection and hash-based reconciliation to ensure all nodes in the swarm maintain an identical "Ghost Mirror" state.
