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

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.