Agent (UI)

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 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 , user\@domain com ) 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 constructs a resolveuseridentity ipc request message containing the retrieved identifier type and value sends the request to the service via ipc receives the resolveuseridentityresponse from the service 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) 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 agent/ui sends request to service via ipc to generate an sso token for the current user receives token back from service constructs the final portal url including the sso token 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) agent/ui sends ipc request to service to generate an sso token for the currently resolved commandit user id service communicates with backend ( /auth/generate sso token ), gets token service returns token to agent/ui via ipc agent/ui constructs the portal url with the token (e g , https //\[portaldomain]/auth/sso?token= ) 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 attempt ipc reset gracefully close the existing ipc client connection to the service, if active 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 reset local ui settings restore any locally stored ui settings (e g , window position, last viewed tab) to their default values 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