# Feature Reference: Agent Node Mesh

This document serves as the comprehensive reference for the **Agent Node Mesh** UI in the Cortex platform. It describes the UI structure, design philosophy, user journeys, and technical implementation details to ensure functional stability during future iterations.

---

## 1. UI Overview & Layout Structure

The Agent Node Mesh page (`NodesPage.js`) is the central control plane for managing distributed execution environments. It follows a vertical stack layout with collapsible functional modules.

### A. Dashboard Header (Top)
- **Position**: Fixed at the top of the main content area.
- **Title**: `Agent Node Mesh` with a rocket icon (🚀).
- **Description**: Contextual message based on user role (Admin vs. User).
- **Global Actions**:
    - **Refresh List**: Triggers a full REST fetch of node registry and group access.
    - **Register Node (Admin Only)**: Opens a modal to create new node slugs and generate invite tokens.

### B. Node Management Card (Repeatable Component)
Each registered node is represented by a high-density management card.

#### 1. Identity, Live Pulse, & Hardware Metadata
- **Pulsing Indicator**: A real-time status light.
    - `bg-green-500`: Node is active and heartbeating via gRPC.
    - `bg-gray-400`: Node is offline or stale.
- **Status Text**: Dynamic label (`online`, `busy`, `idle`, `offline`) derived from gRPC mesh status.
- **Node Name (Hover Trigger)**: Primary display name with a dotted underline.
    - **Hover Tooltip**: Reveals a rich popup containing the Node ID, Description, registered owner, and live **Hardware Capabilities** (GPU presence and type, Operating System, and CPU Architecture). Uses dynamic color-coded badges to easily identify OS and GPU hardware.
- **Responsive Layout**: On mobile, the identity elements stack independently for clarity.

#### 2. Live Health Metrics
- **CPU Meter**: Gradient bar (Indigo-Blue) showing total host load. 
    - **Hover Tooltip**: Displays Core count, Current Frequency (GHz), Per-core utilization distribution, and Load Averages (1/5/15 min).
- **RAM Meter**: Gradient bar (Pink-Rose) showing memory utilization. 
    - **Hover Tooltip**: Displays exact GB Used, Available capacity, and Total system memory.
- **Dynamic Visibility**: Meters only appear when the node is **online**. If offline, a stable space of `140px` is reserved to prevent UI shifting.
- **Responsive Placement**: On desktop screens, metrics align inline in the top row. On mobile screens, they flow to a new line immediately below the node identity.
- **UI Interaction**: Tooltips pop **downwards** (`top-full`) to ensure they are never clipped by the header navigation bar.
- **Philosophy**: Instant "at-a-glance" deep health check without needing to open secondary dashboards.

#### 3. State Control Toggle
- **Active/Disabled Pill**: A compact, tactile button.
    - **Active (Indigo)**: Node is allowed to accept tasks and sync files. Shown as a filled pill (`● Active`).
    - **Disabled (Ghost)**: Node restricted from synchronization and command execution. Shown as an outlined pill (`○ Disabled`).

#### 4. Action Toolbar (Responsive)
- **Layout**: Flexible action bar that aligns right on desktops, and collapses into a tight bottom row with scaled-down padding on mobile devices for touch targets.
- **Terminal Button (Indigo)**: Expands the PTY-based console.
- **File Navigator Button (Amber)**: Expands the directory explorer.
- **Settings & Details Button (Gray)**: Expands the administrative configuration panel.
- **Deregister Button (Red Trash)**: Permanently removes node from registry (Admin only).

---

## 2. Expanded Feature Panes

### A. Interactive Console (`NodeTerminal.js`)
- **Philosophy**: Persistent PTY (Pseudo-Terminal) session.
- **Features**:
    - Real-time character-by-character streaming (ANSI support).
    - **Latency Monitor**: Displays RTT in milliseconds.
    - **Zoom/Fullscreen**: Toggle for complex shell tasks.
    - **Debug Mode**: Toggles visibility of background task events (start/stop/snapshot).
    - **Clear**: Wipes the xterm grid.

### B. File System Navigator (`FileSystemNavigator.js`)
- **Philosophy**: Lazy-loaded directory tree for massive file systems.
- **Features**:
    - **Directory Expansion**: Clicking a folder fetches its immediate children via gRPC `LIST`.
    - **File View**: Opens a modal with a monospaced code viewer (prevents binary file viewing).
    - **Sync Indicators**: Amber dots indicate if a file is currently synced with the server's Ghost Mirror.
    - **Operations**: Create File/Folder, Delete, and Breadcrumb navigation.

### C. Admin Settings Pane (Inline)
- **Identity Details**: Displays registered description.
- **Skill Configuration**: Toggles for `Shell` and `Sync` logic. (Browser automation is now a dedicated system-wide service).
- **Group Access Management**: Map specific user groups to this node with 'use' or 'root' permissions.
- **Download Bundle**: Generates the `agent_config.yaml` and installation package.

---

## 3. Execution Live Bus (Event Stream)

- **Position**: Settled at the bottom of the node list.
- **State**: **Collapsed by default**. Built using a zero-JS `<details>`/`<summary>` HTML pattern to keep the main view uncluttered, especially on mobile. 
- **Label**: Marked with a `Debug` pill badge to emphasize it as an optional tracing tool rather than primary management functionality.
- **Content**: When expanded, a streaming timeline of all mesh events (`task_start`, `task_complete`, `sync_progress`) is revealed.
- **Philosophy**: Providing a "Global Pulse" of what the AI is doing across the entire fleet of nodes. Will eventually be migrated to a dedicated Observability (o11y) dashboard space.

---

## 4. User Journey & Steps

### Path 1: Node Registration (Admin)
1. Click **Register Node** in header.
2. Enter Slug (e.g. `gpu-worker-1`) and Display Name.
3. Expanded **Settings** on the new node card.
4. Click **Download Configuration**.
5. Run the installation script on the physical machine using the generated YAML.

### Path 2: Live Debugging (User/Admin)
1. Locate the target node in the mesh list.
2. Verify **Live Pulse** is green.
3. Click the **Terminal** icon.
4. Execute `ls -la` or `top` to inspect environment.
5. Click **File Navigator** to locate artifacts or logs.

---

## 5. Source Code Mapping

| Component | UI Purpose | Source Path |
| :--- | :--- | :--- |
| `NodesPage.js` | Main Orchestrator View & Mesh Logic | [NodesPage.js](file:///app/frontend/src/pages/NodesPage.js) |
| `NodeHealthMetrics` | Real-time Rich CPU/RAM Metrics | [NodesPage.js (L140)](file:///app/frontend/src/pages/NodesPage.js#L140) |
| `NodeTerminal.js` | PTY-bound Xterm.js terminal | [NodeTerminal.js](file:///app/frontend/src/components/NodeTerminal.js) |
| `FileSystemNavigator.js` | File/Folder Explorer | [FileSystemNavigator.js](file:///app/frontend/src/components/FileSystemNavigator.js) |
| `NodeRegistryService` | Backend Node Tracking | [node_registry.py](file:///app/ai-hub/app/core/services/node_registry.py) |
| `AgentNodeStats` | Pydantic Rich Metric Schema | [schemas.py](file:///app/ai-hub/app/api/schemas.py) |
| `TaskAssistant` | gRPC Dispatcher Brain | [assistant.py](file:///app/ai-hub/app/core/grpc/services/assistant.py) |

---

## 6. Feature Completion & Verification

To ensure a feature is fully operational and stable, follow this mandatory verification path:

### 1. Proto Regeneration & Commit
- **CRITICAL**: If `agent.proto` has changed, you **MUST** regenerate the Python stubs for both the Hub and the Agent **BEFORE** deploying. Failure to do so will cause communication deadlocks or fields like `task_id` to be missed.
  ```bash
  # Hub
  cd /app/ai-hub/app/protos && python3 -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. agent.proto browser.proto
  # Agent
  cd /app/agent-node && python3 -m grpc_tools.protoc -Isrc/protos --python_out=src --grpc_python_out=src src/protos/agent.proto
  ```
- **Step**: Commit the `.proto` changes AND the newly generated `_pb2.py` files.
- **Action**: Push to production:
  ```bash
  bash /app/deploy_remote.sh
  ```

### 2. Production Health Check (The "Python Trick")
Once deployed, perform a basic connectivity check directly inside the production container. This bypasses potential frontend/network issues to isolate the backend logic.
- **SSH into the host** and run a targeted Python script inside the `ai_hub_service` container:
  ```bash
  docker exec ai_hub_service python3 -c "
  import requests
  # Replace with the user_id that owns the node
  headers = {'X-User-ID': '9a333ccd-9c3f-432f-a030-7b1e1284a436'}
  r = requests.get('http://localhost:8000/api/v1/nodes/test-prod-node/fs/ls?path=.', headers=headers)
  print(f'Status: {r.status_code}')
  print(r.text)
  "
  ```
- **Expected Outcome**: A `200 OK` status and a JSON body containing the file list.

### 3. Visual Verification (Worst Case)
If the automated checks pass but UI behavior is suspect, use the **Browser Subagent** workflow (`/browser_setup`) to capture screenshots of the live environment at `https://ai.jerxie.com/nodes`.

> [!IMPORTANT]
> **Subagent Interaction Efficiency**:
> If you need to test the UI, you **MUST** map out the exact step-by-step navigation path (which icons to click, which buttons to press) before calling the tool. Since the subagent cannot read the source code or component structure, it relies purely on visual discovery, which is highly inefficient without explicit step-by-step guidance.

---

## 7. Guidelines for Future Changes
