Agent (UI)

6 min

1. Overview

This document details the V1 specification for the CommandIT Agent/UI component. This is the end-user-facing desktop application providing access to support functions like ticketing, chat, notifications, and portal access. It runs in the context of the logged-in user session and communicates with the backend CommandIT platform via the local, privileged Service component using Inter-Process Communication (IPC).

Technology Stack: Tauri (Rust backend for system interactions/IPC) + TypeScript/React (Frontend UI).
Execution: Standard user-level desktop application. Launched automatically at user login.
Target Platforms (V1): Windows 7 SP1+ (x64), macOS 12 Monterey+ (Universal Binary).
Prerequisites: Requires the CommandIT Service component to be running. Requires WebView2 Runtime on Windows (installer handles check/install).
Core Responsibilities (V1): User Identification, IPC Communication with Service, Basic Ticketing (Create, View List, Attach Screenshot), Notification Handling (Display, History, Acknowledge, SSO Links, Unread Indicator), Functional Chat Interface (details per external spec), Portal Access via SSO, Updater Coordination Trigger, Custom Branding Application, Self-Repair Functionality.

2. Core UI Lifecycle & Appearance

2.1 Installation: Installed as part of the main CommandIT Agent package. Installer handles placing binaries in appropriate user/system application directories. May create shortcuts or command aliases for repair functions.
2.2 Launch at Login: Configured during installation to launch automatically when the user logs in:
- Windows: Via Run registry key (HKCU\Software\Microsoft\Windows\CurrentVersion\Run) or a scheduled task triggered at logon.
- macOS: Via a LaunchAgent plist file placed in ~/Library/LaunchAgents/.
2.3 Startup:
- Initializes Tauri backend and React frontend.
- Establishes connection to the Service component via IPC (see Section 3).
- Performs initial user identification (see Section 4).
- Fetches custom branding settings via Service IPC (see 2.5).
- Displays main UI window (or minimizes to tray/menu bar based on configuration/state).
2.4 Tray/Menu Bar Icon:
- Provides a persistent icon in the system tray (Windows) or menu bar (macOS).
- Icon MUST be customizable via branding settings (see 2.5), with a default fallback icon.
- Icon should visually indicate agent status (e.g., Connected, Disconnected from Service).
- Icon MUST visually change (e.g., display a badge, overlay, or color shift) when there are unread or unacknowledged notifications requiring user attention (see Section 6).
- Provides a context menu with options like: Open Main Window, Create Ticket, Open Portal, Check for Updates, Repair Agent UI, Quit.
2.5 Custom Branding:
- Support: The Agent/UI MUST support customization of its appearance based on settings defined for the device's organization.
- Settings Source: Branding settings (e.g., custom tray/menu bar icon URL, primary/secondary theme colors) are stored server-side (likely in PortalBrandingSettings table, linked to the device's Organization).
- Delivery: The Service component is responsible for fetching the applicable branding settings for the device's organization from the backend API. The Service passes these settings (icon URL, color codes) to the Agent/UI via IPC (e.g., during initial status sync or via a dedicated GetBrandingResponse message).
- Application: The Agent/UI frontend MUST dynamically apply the received branding:
  - Load and display the custom icon in the tray/menu bar and potentially other relevant UI locations (e.g., window title bar). Handle image loading errors gracefully.
  - Apply the received theme colors (e.g., primary accent color, background variations) to the UI elements, likely using CSS variables or a theme provider.
- Fallback: If custom branding settings are not configured, fail to load, or are invalid, the Agent/UI MUST revert to a default, built-in CommandIT brand identity (default icon, default color scheme).
2.6 Shutdown: Handles graceful shutdown, closing IPC connection, terminating processes cleanly when user quits or logs off/shuts down the OS.

3. IPC Client

Purpose: Handles all communication with the local Service component.
Mechanism: Acts as the client connecting to the Service's IPC server.
- Windows: Connects to Named Pipe \\.\pipe\CommandITAgentService.
- macOS: Connects to Unix Domain Socket /var/run/commandit_agent_service.sock (or similar defined path).
Connection Handling:
- Attempts connection on startup.
- Implements retry logic with backoff if the Service is not immediately available (e.g., Service is starting).
- Monitors connection status. If connection is lost, attempts to re-establish periodically. UI should reflect disconnected state (e.g., tray icon change).
Message Protocol: Sends and receives JSON messages based on the defined schemas (see Appendix A draft).
- Generates unique message_id (UUID string) for each request sent to the Service.
- Matches incoming responses from the Service using the correlation_id.
- Handles potential timeouts waiting for responses from the Service.
Error Handling: Gracefully handles IPC errors (connection refused, pipe closed, socket error, invalid messages, timeouts). Logs errors locally and displays user-friendly error messages in the UI (e.g., "Cannot connect to CommandIT Service").

4. User Identification

Purpose: Identify the currently logged-in OS user and map them to a CommandIT user account.
Process:
1. On startup (and potentially periodically or on-demand), the Agent/UI calls OS-native APIs to retrieve the current user's identity:
  - Windows: GetUserNameExW using NameUserPrincipal format (e.g., [email protected]). Fallback to NameSamCompatible (DOMAIN\user) if UPN is unavailable.
  - macOS: NSUserName() to get the short name. Potentially supplement with directory lookup if needed/possible for email/UPN.
2. Constructs a ResolveUserIdentity IPC request message containing the retrieved identifier type and value.
3. Sends the request to the Service via IPC.
4. Receives the ResolveUserIdentityResponse from the Service.
5. If success is true, stores the returned commandit_user_id and user_display_name in the UI's session state for use in subsequent actions (e.g., ticket creation, API relays).
6. If success is false, indicates an error state in the UI (e.g., "Could not verify user identity with CommandIT") and potentially disables features requiring a linked user.

5. Ticketing Interface (Basic V1)

Purpose: Allow end-users to create support tickets and view their existing tickets.
Ticket Creation:
- Provides a UI form with fields for:
  - Subject (Text Input, Required).
  - Body/Description (Text Area, Required, supports multi-line).
  - (Optional fields like Priority might be added based on backend configuration fetched via Service).
- Screenshot Attachment:
  - Provides a button/mechanism to initiate screenshot capture.
  - Uses OS APIs (PrintWindow, BitBlt, screencapture, platform-specific screen capture libraries) to capture full screen or allow user region selection.
  - Stores captured image temporarily locally (e.g., PNG or JPEG format).
  - Allows user to preview and confirm attachment.
- Submission:
  - Bundles form data (subject, body), the resolved requester_user_id (from Section 4), and potentially the temporary screenshot data (e.g., as base64 encoded string or requiring a separate upload step coordinated via Service).
  - Sends data within a RelayApiRequest IPC message to the Service, targeting the backend POST /api/v1/tickets endpoint.
  - Displays success or failure feedback based on the RelayApiResponse.
Ticket Viewing (Basic List):
- Provides a view listing the user's open tickets.
- Fetches data by sending a RelayApiRequest via Service targeting GET /api/v1/tickets?requester_user_id={userId}&status=open.
- Displays key fields like Ticket Number, Subject, Status, Last Updated Date.
- V1 defers detailed ticket view, adding updates/replies.

6. Notification Handling (V1)

Purpose: Receive, display, and manage notifications pushed from the CommandIT platform.
Receiving: Listens for NotificationPush messages sent from the Service via IPC.
Display:
- On receiving a new notification, displays an OS-native toast/banner notification containing the title and brief content.
- Maintains a persistent notification history panel/list within the Agent/UI, showing received notifications (Title, Body, Timestamp, Severity). Unread/unacknowledged items should be visually distinct.
State Tracking & Unread Indicator: The UI MUST track the read/acknowledged state of each notification. This state determines whether the visual indicator on the tray/menu bar icon (Section 2.4) is active.
Acknowledgement:
- If a received notification payload indicates requires_ack: true, the UI must display an "Acknowledge" or "Mark as Read" button for that notification in the history panel.
- Clicking this button sends an appropriate RelayApiRequest via the Service (e.g., targeting POST /api/v1/notifications/{notification_id}/ack) to update the status on the backend. The UI should update the local state and potentially clear the unread indicator if this was the last unacknowledged item.
Link Handling:
- Parses notification body content for hyperlinks.
- Renders hyperlinks appropriately.
- Standard Links: Clicking opens the URL in the system's default external web browser.
- Portal Links: If a link is identified as targeting the CommandIT portal (based on URL pattern configured/provided by backend), clicking it must first trigger the Portal SSO flow:
  1. Agent/UI sends request to Service via IPC to generate an SSO token for the current user.
  2. Receives token back from Service.
  3. Constructs the final portal URL including the SSO token.
  4. Launches the default browser with the SSO URL.

7. Chat Interface (Functional V1)

Purpose: Provide real-time chat functionality for support.
Implementation: Implements the UI and core logic defined in the separate, external Chat Specification document.
Communication: Relies entirely on the Service component via IPC (RelayApiRequest or potentially dedicated chat message types) to send and receive chat messages, fetch history, and manage channel state with the CommandIT backend.
Ticket Creation: Includes the capability for users or technicians/bots to initiate the creation of a new Ticket directly from within a chat conversation context.

8. Approval Workflow (Framework V1)

Purpose: Handle approval requests initiated by the Service (for future features like Remote Control, elevated actions).
Receiving: Listens for ApprovalRequest IPC messages from the Service.
UI Prompt: Upon receiving a request, displays a prominent, modal dialog to the user.
- Content includes: Requester Name, Action Description, Context (e.g., Ticket #).
- Provides clear "Approve" and "Deny" buttons.
- Handles the specified timeout_seconds - if no user interaction occurs within the timeout, it automatically considers the request denied.
Response: Sends the user's choice ('Approved', 'Denied', or 'Timeout') back to the Service via an ApprovalResponse IPC message, including the original request_id for correlation.

9. Updater Coordination

UI Element: Provides a "Check for Updates" button or menu item within the UI settings or context menu.
Action: Clicking this element sends a TriggerUpdateCheck IPC message to the Service component. UI may display feedback like "Update check initiated". Does not display progress or results directly (handled by Updater/Service).

10. Error Handling

Provides user-friendly feedback for errors encountered during operation:
- Inability to connect to the Service component via IPC.
- Failures relaying API requests (e.g., ticket creation failed).
- Failure to resolve user identity.
- Errors during screenshot capture.
Logs detailed errors locally (file within user profile or AppData/Application Support) for troubleshooting.

11. Portal Access (V1)

UI Element: Provides a clearly labeled button or menu item (e.g., "Open Customer Portal") within the main UI or tray/menu bar context menu.
Action: Clicking this element initiates the Portal SSO flow (detailed in Section 9 of the main spec):
1. Agent/UI sends IPC request to Service to generate an SSO token for the currently resolved commandit_user_id.
2. Service communicates with backend (/auth/generate-sso-token), gets token.
3. Service returns token to Agent/UI via IPC.
4. Agent/UI constructs the portal URL with the token (e.g., https://[PortalDomain]/auth/sso?token=...).
5. Agent/UI launches the system's default web browser with the constructed URL.

12. Repair Function

Purpose: To resolve issues specific to the Agent/UI component, such as problems connecting to the Service via IPC, corrupted local UI state/cache, or persistent UI rendering errors, without affecting the core Service component or requiring elevated privileges.
Initiation:
- Primary: Via a command-line argument passed to the Agent/UI executable (e.g., CommandIT-Agent-UI.exe --repair on Windows, or similar for macOS). This allows initiation even if the UI is completely unresponsive. The main installer may create a shortcut or script to facilitate this.
- Secondary: Optionally, via a "Repair Agent UI" button within the tray/menu bar icon's context menu (see Section 2.4), if the basic UI process is still running.
- Context: MUST run within the context of the affected user session. Does not require Administrator/root privileges.
Actions Performed:
1. Attempt IPC Reset: Gracefully close the existing IPC client connection to the Service, if active.
2. Clear UI Caches & State: Delete locally stored caches, state, and non-essential configuration specific to the Agent/UI application. This includes:
  - Location: User's profile directory (e.g., %APPDATA%\CommandIT Agent UI or ~/Library/Application Support/CommandIT Agent UI).
  - Data: Cached notification history (if stored by UI), UI layout preferences, potentially locally stored theme/branding info (it will be re-fetched), session state tokens (excluding core user mapping if possible).
  - Does NOT affect Service data, logs, database, Agent GUID, or Device Secret.
3. Reset Local UI Settings: Restore any locally stored UI settings (e.g., window position, last viewed tab) to their default values.
4. Restart Application: Terminate the current Agent/UI process and attempt to relaunch it cleanly.
User Feedback: If initiated via command line, output status messages (e.g., "Clearing UI cache...", "Restarting Agent UI...") to the console. If initiated via UI, provide visual feedback during the process.