Q Chat Client

This package contains a chat client for the Q Language Server, that can be embedded in a webview. It uses MynahUI to render a web based chat interface.

Communication

The chat client communicates with the host application (e.g., an IDE extension) through postMessage requests to the webview:

• When the host application sends a request, the client processes the message and sends it to the UI
• When an event is triggered in the UI, the client sends a message through postMessage to the host application that rendered the chat client

Host environments

The webview is embedded by different IDE hosts, which use different browser engines and load the chat assets differently. As a result, the event.origin observed on inbound postMessage events is not uniform across hosts:

| Host | Rendering engine | Asset scheme | window.location.origin / inbound event.origin | Message-delivery bridge | |---|---|---|---|---| | VS Code | Chromium webview | vscode-webview:// | vscode-webview://<id> (non-HTTP) | acquireVsCodeApi().postMessage | | JetBrains | JCEF | https://toolkitasset | https://toolkitasset (same-origin) | JCEF JS query bridge + postMessage | | Visual Studio | Edge WebView2 | host-served | host-dependent | window.chrome.webview.postMessage | | Eclipse (Windows) | Edge WebView2 | HTML injected via Browser.setText() | empty "" or "null" (opaque origin) | host-injected window.postMessage | | Eclipse (macOS / Linux) | WebKit / WebKitGTK | local asset server | HTTP(S) same-origin | host-injected window.postMessage | | SageMaker JupyterLab | Browser (Chromium / Firefox / Safari) | same-domain iframe | same-origin | window.postMessage |

Because the origin is not uniform, the inbound message handler validates it defensively: it rejects only a real HTTP(S) cross-origin message and allows empty, "null", and file:// origins, which are produced by legitimate hosts (for example Eclipse on Windows, where Browser.setText()-injected HTML has an opaque origin). Any change to inbound message handling or origin validation must be validated against every host environment above — see the handleInboundMessage JSDoc in src/client/chat.ts.

Usage

To use the chat client, embed it in a webview within your application and handle the postMessage communication as needed. Chat client is based on inbound (from a destination to the chat client) and outbound events (from the chat client to a destination). Events consist of command and params:

interface SomeEvent {
    command: string;
    params: SomeOptions;
}

Inbound events

| Name | Description | command | params | | ------------------------------ | -------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | sendChatPrompt response | Provides response to sendChatPrompt request | aws/chat/sendChatPrompt | ChatResult | | openTab request | Request to open tab (creates tab if no tabId provided) | aws/chat/openTab | requestID - ID shared between the webview and vscode client, OpenTabParams | | sendToPrompt | Request to send selection to prompt | sendToPrompt | SendToPromptParams | | genericCommand | Request to execute generic command | genericCommand | GenericCommandParams | | errorMessage | Request to show error in chat UI | errorMessage | ErrorParams | | chatOptions | Configures chat startup options | chatOptions | ChatOptions | | chatUpdate | Updates existing chat messages | aws/chat/sendChatUpdate | ChatUpdateParams | | contextCommand | Sends context commands to the UI | aws/chat/sendContextCommands | ContextCommandParams | | listConversations response | Provides response with list of history conversations to the UI | aws/chat/listConversations | ListConversationsResult | | conversationClick response | Provides response to conversation click or action, specifying action execution result | aws/chat/conversationClick | ConversationClickResult | | getSerializedChat request | Request to get serialized chat | aws/chat/getSerializedChat | GetSerializedChatParams | | chatOptionsUpdate | Sends chat options update request from server | aws/chat/chatOptionsUpdate | ChatOptionsUpdateParams | | listRules response | Provides response with list of workspace rules to the UI | aws/chat/listRules | ListRulesResult | | ruleClicked response | Provides response to rule click or action, specifying action execution result | aws/chat/ruleClick | RuleClickResult | | addSelectedFilesToContext | Request to add selected files to context | aws/chat/openFileDialog | OpenFileDialogResult | | sendPinnedContext | Sends pinned context information to the UI | aws/chat/sendPinnedContext | PinnedContextParams |

Outbound events

| Name | Description | command | params | | --------------------------- | -------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | openTab response | Provides response to openTab request | aws/chat/openTab | requestID - ID shared between the webview and vscode client, UiMessageResultParams with result of type OpenTabResult | | disclaimerAcknowledged | Notifies destination that legal disclaimer was acknowledged by a user | disclaimerAcknowledged | N/A | | sendChatPrompt | Sends a chat prompt to the server | aws/chat/sendChatPrompt | ChatParams | | sendQuickActionCommand | Sends a quick action command | aws/chat/quickAction | QuickActionParams | | tabAdded | Notifies when a tab is added | aws/chat/tabAdd | TabAddParams | | tabChanged | Notifies when a tab is changed | aws/chat/tabChange | TabChangeParams | | tabRemoved | Notifies when a tab is removed | aws/chat/tabRemove | TabRemoveParams | | insertToCursorPosition | Requests to insert code at cursor position | insertToCursorPosition | InsertToCursorPositionParams | | copyToClipboard | Requests to copy code to clipboard | copyToClipboard | CopyCodeToClipboardParams | | authFollowUpClicked | Notifies when an auth follow-up is clicked | authFollowUpClicked | AuthFollowUpClickedParams | | followUpClicked | Notifies when a follow-up suggestion is clicked | aws/chat/followUpClick | FollowUpClickParams | | sendFeedback | Sends user feedback | aws/chat/feedback | FeedbackParams | | linkClick | Notifies when a link is clicked | aws/chat/linkClick | LinkClickParams | | sourceLinkClick | Notifies when a source link is clicked | aws/chat/sourceLinkClick | SourceLinkClickParams | | infoLinkClick | Notifies when an info link is clicked | aws/chat/infoLinkClick | InfoLinkClickParams | | uiReady | Notifies when the UI is ready | aws/chat/ready | N/A | | chatPromptOptionAcknowledged | Notifies when a chat prompt option is acknowledged | chatPromptOptionAcknowledged | ChatPromptOptionAcknowledgedParams | | createPrompt | Requests to create a prompt | aws/chat/createPrompt | CreatePromptParams | | fileClick | Notifies when a file is clicked | aws/chat/fileClick | FileClickParams | | listConversations | Requests to list conversations with filter provided | aws/chat/listConversations | ListConversationsParams | | conversationClick | Notifies when a conversation is clicked | aws/chat/conversationClick | ConversationClickParams | | tabBarAction | Notifies when a tab bar action is requested | aws/chat/tabBarAction | TabBarActionParams | | getSerializedChat response | Provides response to getSerializedChat request | aws/chat/getSerializedChat | GetSerializedChatResult | | stopChatResponse | Requests to stop current chat response | stopChatResponse | StopChatResponseParams | | sendButtonClickEvent | Sends button click event | aws/chat/buttonClick | ButtonClickParams | | onOpenSettings | Requests to open settings | openSettings | OpenSettingsParams | | onRuleClick | Notifies when a rule is clicked | aws/chat/ruleClick | RuleClickParams | | listRules | Requests to list workspace rules | aws/chat/listRules | ListRulesParams | | onAddPinnedContext | Requests to add pinned context | aws/chat/addPinnedContext | PinnedContextParams | | onRemovePinnedContext | Requests to remove pinned context | aws/chat/removePinnedContext | PinnedContextParams | | onOpenFileDialogClick | Requests to open file dialog | openFileDialog | OpenFileDialogParams | | onFilesDropped | Notifies when files are dropped | filesDropped | FilesDroppedParams | | promptInputOptionChange | Notifies when prompt input options change | aws/chat/promptInputOptionChange | PromptInputOptionChangeParams |

Configuration

Configuration can be passed as an explicit parameter when creating chat inside of webview, for example:

amazonQChat.createChat(acquireVsCodeApi(), configuration);

Configuration values:

// Configures quick actions
quickActionCommands?: QuickActionCommandGroup[]

// Configures chat client not to show legal disclaimer as it has already been acknowledged before
disclaimerAcknowledged?: boolean