Runtimes to host Language Servers for AWS
npm install @aws/language-server-runtimesLanguage Server Runtimes is a JSON-RPC based protocol for interactions between servers and clients (typically embedded in development tools). The JSON-RPC protocol follows the version utilized in the LSP Specification - 3.17, for compatibility. A subset of LSP version 3.17 is supported (see LSP) plus an additional set of request and response types (see Features).
Language Server Runtimes supports a number of host environments that each have their own underlying transport mechanisms and environment considerations, which must also support JSON-RPC communication. To see the differences between host environments, see Runtime Host Environments.
The server runtime will provide “Features” which refers to the Language Server Runtimes core feature (eg. LSP, Logging, etc). These features will be injected on top of the Server business logic implementation at build time. Capabilities are a set of language features provided by an LSP.
The project source code is split into next directories:
- /src: This directory contains all the source code of the project.
- /protocol: JSON-RPC-based Runtime protocol implementation in Typescript, which defines the communication between Runtime and Runtime Clients (e.g. AWS Toolkit extension).
- /runtimes: implementation of several runtimes (standalone, webworker) and features, that are exposed to Runtime Servers developed by Server implementors.
- /server-interface: defines interfaces of features, that Runtime provides to Runtime Servers implementors.
- /testing: testing helper for Server implementors.
The server runtime implementation acts as a proxy for LSP methods, which means it supports all LSP methods. In addition to that, it can extend the LSP method to support custom capabilities.
#### Feature Specification
| Method | Support | Notes |
| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| onInlineCompletion | Yes | Provide list of inline completion suggestions from the Server |
| onExecuteCommand | Yes | Executes a custom command provided by the Server. Servers are advised to document custom commands they support in the package README. |
##### LSP Window
| Description | Method | Params | Method type | Response Type |
| ------------------------------------ | --------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| Request to check diagnostics for specified files | aws/checkDiagnostics | CheckDiagnosticsParams | Request Server to Client | CheckDiagnosticsResult |
##### LSP Workspace
| Description | Method | Params | Method type | Response Type |
| ------------------------------------ | --------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| Request to select workspace item (folder, file) with the selected items returned | aws/selectWorkspaceItem | SelectWorkspaceItemParams | Request Server to Client | SelectWorkspaceItemResult |
| Request to open a file in the workspace programmatically | aws/openWorkspaceFile | OpenWorkspaceFileParams | Request Server to Client | OpenWorkspaceFileResult |
| Sent notification to open file differences for the new file content. Supports new, updated or removed files. | aws/openFileDiff | OpenFileDiffParams | Notification Server to Client | n/a |
| Sent notification that file was copied from old to new path using file system operation. | aws/didCopyFile | CopyFileParams | Notification Server to Client | n/a |
| Sent notification that content was written to file using file system operation. | aws/didWriteFile | FileParams | Notification Server to Client | n/a |
| Sent notification that content was appended to file using file system operation. | aws/didAppendFile | FileParams | Notification Server to Client | n/a |
| Sent notification that file or directory was removed using file system operation. | aws/didRemoveFileOrDirectory | FileParams | Notification Server to Client | n/a |
| Sent notification that directory was created using file system operation. | aws/didCreateDirectory | FileParams | Notification Server to Client | n/a |
##### LSP Extensions
| Method Name | Method | Params | Method Type | Response Type | Notes |
| ----------------------------------- | ------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| getConfigurationFromServer | aws/getConfigurationFromServer | GetConfigurationFromServerParams | Request | LSPAny | Retrieves configuration from the server for a specified section |
| onInlineCompletionWithReferences | aws/textDocument/inlineCompletionWithReferences | InlineCompletionWithReferencesParams | Request | InlineCompletionListWithReferences | Provides list of inline completion suggestions from the Server with references for each of its suggestion |
| onLogInlineCompletionSessionResults | aws/logInlineCompletionSessionResults | LogInlineCompletionSessionResultsParams | Notification | n/a | Logs the results from inline completion suggestions from the Server |
The runtime supports two types of credentials: IAM credentials and Bearer tokens (e.g. Builder ID). These credentials should be available to destinations in plaintext.
``ts
// IAM Credentials data
export interface IamCredentials {
accessKeyId: string
secretAccessKey: string
sessionToken?: string
}
// Bearer Token data
export interface BearerCredentials {
token: string
}
`
Destinations are responsible for managing credentials state, refreshing and updating them on the runtime when their state changes.
#### Initialization
The runtimes by default support authentication with both types of credentials, without the need of a prior agreement or handshake with the client. If the client supports a specific type of credentials, the corresponding LSP update method can be called directly. For cases when passing plaintext credentials is not suitable (e.g. standalone runtimes), they can be encrypted before being sent to the server (see Encryption).
#### Feature Specification
The following table outlines custom LSP methods are supported by servers for authentication:
| Description | Method | Params | Method type | Response Type |
| ---------------------- | ------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Send IAM Credentials | aws/credentials/iam/update | UpdateCredentialsPayload | Request | ResponseMessage |aws/credentials/token/update
| Send Bearer token | | UpdateCredentialsPayload | Request | ResponseMessage |aws/credentials/iam/delete
| Delete IAM credentials | | n/a | Notification | n/a |aws/credentials/token/delete
| Delete bearer token | | n/a | Notification | n/a |
`ts
export type Credentials = IamCredentials | BearerCredentials
// Credentials provided to the server by the server's host
export interface UpdateCredentialsPayload {
// Plaintext IamCredentials/BearerCredentials or JSON blob of encrypted credentials
data: string | Credentials
// If the payload is encrypted
// Defaults to false if undefined or null
encrypted?: boolean
}
`
##### Get Connection Metadata
Server Auth feature supports storing extra Auth connection data in the server.
Get connection metadata is request that server sends to client in order to obtain new connection information.
Server expects client to provide metadata specified in ConnectionMetadata interface.
| Description | Method | Params | Method type | Response Type |
| ----------------------- | --------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------- | -------------------- |
| Get Connection Metadata | aws/credentials/getConnectionMetadata | n/a | Request | ConnectionMetadata |
`ts
export interface ConnectionMetadata {
sso?: SsoProfileData
}
export interface SsoProfileData {
startUrl?: string
}
`
#### Initialization
The runtimes by default supports the telemetry feature, allowing servers to send metrics to destinations. Additional option to disable this feature during initialization as well as during an ongoing session is currently in plan.
#### Feature Specification
The telemetry notification is sent from the server to the client to ask the client to log a telemetry event. AWS Runtimes using Telemetry feature will send metric events with default LSP telemetry notification with specified payload interface. Telemetry notifications are specified as follow:
| Description | Method | Params | Method type | Response Type |
| -------------------- | ----------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| Send telemetry event | telemetry/event | MetricEvent | Notification | n/a |
`ts`
export type MetricEvent = {
name: string
data?: any
result?: ResultType
errorData?: ErrorData
}
Design TBD
#### Initialization
The runtimes by default supports the logging feature, allowing servers to output logs varied by different log levels.
#### Feature Specification
The log level to be set in the runtime for logging can be decided by the client as part of initialize request, which is the first
request initiated by client to the LSP server. The log level can be updated dynamically even after server start by triggering workspace/didChangeConfiguration getConfigurations
notification from the client - which prompts the runtime to fetch the new log level to be set from the client through LSP request. InitializeParams.initializationOptions.logLevel
1. Params in the initialize request:
2. Configuration request params for requesting log level from runtimes to client: {section: "aws.logLevel"}
The runtime defines Chat interface that allow runtime server implementors to define handlers for chat events to enable conversational experiences. Chat data types are mostly modeled after mynah-ui, an event driven UI library designed for chat experiences. mynah-ui is the suggested UI library to be used on the destination. However the Chat interface is generic enough to be compatible with other UI approaches
#### Initialization
The runtime supports chat by default
#### Feature Specification
| Description | Method | Params | Method type | Response Type |
| ------------------------------------ | --------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | --------------- |
| Send chat prompt. Supports streaming chat message content to client. Response is optional - this event can be used to only trigger chat prompt request and then aws/chat/sendChatUpdate can be used to send chat updates asyncronously. | aws/chat/sendChatPrompt | ChatParams | Request Client to Server | ChatResult |aws/chat/endChat
| End conversation | | EndChatParams | Request Client to Server | EndChatResult |aws/chat/sendChatUpdate
| Send chat quick action. Response is optional - this event can be used to only trigger chat quick action request and then can be used to send chat updates asyncronously. | aws/chat/sendChatQuickAction | QuickActionParams | Request Client to Server | ChatResult |aws/chat/buttonClick
| Send generic button click request to the server. This event can be used to trigger a button click action. Response can be used by client to determine if relevant action executed successfully. | | ButtonClickParams | Request Client to Server | ButtonClickResult |aws/chat/ready
| Send chat UI ready event | | n/a | Notification Client to Server | n/a |aws/chat/feedback
| Send chat feedback event | | FeedbackParams | Notification Client to Server | n/a |aws/chat/tabAdd
| Send tab add event | | TabAddParams | Notification Client to Server | n/a |aws/chat/tabChange
| Send active tab change event | | TabChangeParams | Notification Client to Server | n/a |aws/chat/tabRemove
| Send tab remove event | | TabRemoveParams | Notification Client to Server | n/a |aws/chat/insertToCursorPosition
| Send insert to cursor position event | | InsertToCursorPositionParams | Notification Client to Server | n/a |aws/chat/linkClick
| Send link click event | | LinkClickParams | Notification Client to Server | n/a |aws/chat/infoLinkClick
| Send info link click event | | InfoLinkClickParams | Notification Client to Server | n/a |aws/chat/sourceLinkClick
| Send source link click event | | SourceLinkClickParams | Notification Client to Server | n/a |aws/chat/followUpClick
| Send followup chat item click event | | FollowUpClickParams | Notification Client to Server | n/a |tabId
| Send request to open existing tab, if is passed or create and open new tab, if tabId is not passed. For the new tab, it's also possible to set tab state and content. | aws/chat/openTab | OpenTabParams | Request Server to Client | OpenTabResult |messageId
| Send chat messages and tab state update to specific tab. Depending on new vs existing within ChatMessage message, the massgage will be added or updated. | aws/chat/sendChatUpdate | ChatUpdateParams | Notification Server to Client | n/a |aws/chat/fileClick
| Send file or file action click event. | | FileClickParams | Notification Client to Server | n/a |aws/chat/sendInlineChatPrompt
| Send inline chat prompt. Response is optional - this event can be used to only trigger inline chat prompt request and then updates can be sent asynchronously. | | InlineChatParams | Request Client to Server | InlineChatResult |aws/chat/inlineChatResult
| Send inline chat result notification with user decision and metrics. | | InlineChatResultParams | Notification Client to Server | n/a |@
| Send or update context commands that customer can attach to their prompt request (available via in chat UI). | aws/chat/sendContextCommands | ContextCommandParams | Notification Server to Client | n/a |aws/chat/createPrompt
| Send create prompt event that triggers new prompt or rule creation flow on server. | | CreatePromptParams | Notification Client to Server | n/a |listConversations
| Send request to list the conversations available in history: all or based on filter if provided. As there can be several filter options used, the filter in the request is a map of filter option ids to corresponding values. Possible filter options are expected to be provided in the previous result before filter can be used. | aws/chat/listConversations | ListConversationsParams | Request Client to Server | ListConversationsResult |aws/chat/conversationClick
| Send conversation or conversation action click event. If no action is provided, the default action is "open". | | ConversationClickParams | Request Client to Server | ConversationClickResult |aws/chat/listMcpServers
| Send request to list the MCP servers available: all or based on filter if provided. Similar to conversations, the filter in the request is a map of filter option ids to corresponding values. | | ListMcpServersParams | Request Client to Server | ListMcpServersResult |aws/chat/mcpServerClick
| Send MCP server or MCP server action click event. If no action is provided, the default action is "select". | | McpServerClickParams | Request Client to Server | McpServerClickResult |aws/chat/listAvailableModels
| Send request to list available models for the current chat tab. | | ListAvailableModelsParams | Request Client to Server | ListAvailableModelsResult |aws/chat/sendPinnedContext
| Send pinned context to client. Pinned context contains context commands that are pinned to the current tab. | | PinnedContextParams | Notification Server to Client | n/a |aws/chat/pinnedContextAdd
| Notify server that pinned context has been added by the client. | | PinnedContextParams | Notification Client to Server | n/a |aws/chat/pinnedContextRemove
| Notify server that pinned context has been removed by the client. | | PinnedContextParams | Notification Client to Server | n/a |aws/chat/activeEditorChanged
| Notify server that active editor has changed. | | ActiveEditorChangedParams | Notification Client to Server | n/a |aws/chat/listRules
| Send request to list the rules available for a specific tab. | | ListRulesParams | Request Client to Server | ListRulesResult |aws/chat/ruleClick
| Send rule or rule folder click event. | | RuleClickParams | Request Client to Server | RuleClickResult |aws/chat/chatOptionsUpdate
| Send server-initiated chat metadata updates. The interface is designed to be extensible for future chat options, currently focused on notification for developer profile changes. | | ChatOptionsUpdateParams | Notification Server to Client | n/a |aws/chat/promptInputOptionChange
| Send prompt input option event changes | | PromptInputOptionChangeParams | Notification Client to Server | n/a |aws/chat/tabBarAction
| Send tab bar action request (e.g., export). | | TabBarActionParams | Request Client to Server | TabBarActionResult |aws/chat/getSerializedChat
| Send request to get serialized chat content in specified format. | | GetSerializedChatParams | Request Client to Server | GetSerializedChatResult |aws/chat/openFileDialog
| Send request to open file dialog for file selection. | | OpenFileDialogParams | Request Client to Server | OpenFileDialogResult |aws/chat/subscription/details
| Sent to display subscription information in the chat UI | | SubscriptionDetailsParams | Notification Server to Client | n/a |aws/chat/subscription/upgrade
| Sent to begin a subscription upgrade | | SubscriptionUpgradeParams | Notification Client to Server | n/a |
`ts
export interface ChatPrompt {
prompt?: string
escapedPrompt?: string
command?: string
}
interface PartialResultParams {
partialResultToken?: number | string
}
export interface ChatParams extends PartialResultParams {
tabId: string
prompt: ChatPrompt
cursorState?: CursorState[]
textDocument?: TextDocumentIdentifier
}
`
Complete Chat parameter and result interfaces can be found in chat.ts
The Identity Management feature is designed to centralize the management of authentication and identity-related functionality. The APIs consist of:
- Listing and managing user profiles and SSO sessions
- Obtaining valid SSO access tokens, handling the PKCE or Device Code login flows as needed
- Controlling the lifetime and notifications for active SSO tokens
- Invalidating cached SSO tokens
#### Feature Specification
| Description | Method | Params | Method type | Response Type |
| ------------------------------------ | --------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| List profiles | aws/identity/listProfiles | ListProfilesParams | Request | ListProfilesResult |aws/identity/updateProfile
| Update profiles | | UpdateProfileParams | Request | UpdateProfileResult |aws/identity/getSsoToken
| Get SSO token | | GetSsoTokenParams | Request | GetSsoTokenResult |aws/identity/invalidateSsoToken
| Invalidate SSO token | | InvalidateSsoTokenParams | Request | InvalidateSsoTokenResult |aws/identity/ssoTokenChanged
| SSO token changed | | SsoTokenChangedParams | Notification | n/a |
Complete Identity Management parameter and result interfaces can be found in identity-management.ts
#### Client Capability
Requires the client to implement support for receiving the following requests:
- window/showDocument
client.onRequest
ShowDocumentRequest.method,
async (params: ShowDocumentParams) => { ... }
)
-
client.onRequest
ShowMessageRequest.method,
async (params: ShowMessageRequestParams) => { ... }
)
-
client.onProgress(
GetSsoTokenProgressType,
GetSsoTokenProgressToken,
async (partialResult: GetSsoTokenProgress) => {
// partialResult is likely encrypted
...
}
)
The notification feature can be used to send custom customer-facing notifications to clients. Notifications can contain actions, like show URL, but also followup actions, like request customer acknowledgement. When customer reacts to followup actions, asynchronous notification is expected to be sent from client to server to notify server about this.
Notifications should be used in rare / exceptional cases that require customer attention (like some change happened or action recommended), but are not blocking the main flow. Clients can decide to throttle notifications, if too many are sent.
Consider using LSP ShowMessage notification instead, if your notification does not require actions or followup actions.
#### Feature Specification
| Description | Method | Params | Method type | Response Type |
| ------------------------------------ | --------------------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
| Show notification to customer | aws/window/showNotification | NotificationParams | Notification | n/a |aws/window/notificationFollowup
| Send notification followup back to server | | NotificationFollowupParams | Notification | n/a |
Tool invocations can use LSP, Workspace or Chat capabilities to interact with the client environment.
The agent feature uses the following interface:
`tsrunTool
export type Agent = {
/**
* Add a tool to the local tool repository. Tools with the same name will be overwritten.
*
* Tools should be called using .
*
* @param spec Tool Specification
* @param handler The async method to execute when the tool is called
*/
addTool:
spec: S,
handler: (input: T, token?: CancellationToken) => Promise
) => void
/**
* Run a tool by name. This method will lookup the tool in the local tool repository and
* validate the input against the tool's schema.
*
* Throws an error if the tool is not found, or if validation fails.
*
* @param toolName The name of the tool to run
* @param input The input to the tool
* @returns The result of the tool execution
*/
runTool: (toolName: string, input: any, token?: CancellationToken) => Promise
/**
* Get the list of tools in the local tool repository.
* @param options Options for the format of the output. Can be either 'bedrock' or 'mcp' (the default)
* @returns The tool repository in the requested output format
*/
getTools:
}
`
A typical agent loop would look like this:
`ts
const AgentServer: Server = ({ chat, agent }) => {
agent.addTool({
name: 'use_greeting',
description: 'A kind greeting to the user'
inputSchema: {
type: 'object',
parameters: {
name: {
type: 'string'
}
}
}
}, async (input: { name: string }) => {
return hello, ${name}
})
chat.onChatPrompt((params: ChatParams) => {
let currentStep = 0;
const maxSteps = 5; // Prevent infinite loops
let finalResponse = '';
const conversationHistory = [];
while (currentStep < maxSteps) {
const response = await invokeModel(conversationHistory, params.prompt.prompt, agent.getTools({format: 'bedrock'})) // or { format: 'mcp' }
// Check if the response includes tool uses
if (response.tool_use && response.tool_use.length > 0) {
// Execute each tool use
const toolResults = await Promise.all(
response.tool_use.map((toolUse) => ({
toolUseId: toolUse.Id,
content: await agent.runTool(toolUse.name, toolUse.input)
}))
)
// Ensure error handling and validation errors
// You could also emit partial results here to keep the user informed of progress
// Add tool results to conversation
conversationHistory.push({
role: "tool",
content: JSON.stringify(toolResults)
})
// Continue the conversation with tool results
userInput = Tool execution results: ${JSON.stringify(toolResults)}. Please continue with the task.
} else {
// No more tool calls needed, return final response
finalResponse = response.content;
break;
}
currentStep++
}
return {
body: finalResponse
}
})
// disposable
return () => {
// Do nothing
}
}
`
Servers typically run as processes or web workers. Details are provided below on how to initialize each type of server runtime.
Language Server Runtimes uses LSP abstracts to create a JSON-RPC connection between client and server. We use the Initialize LSP lifecycle method to provide initialization options to the server.
Features will be instantiated and configured during execution of the Initialize flow of the main connection.
Client will send the Initialize LSP request with custom options to configure features in the optional InitializeParams.initializationOptions property. The configuration passed here will influence implementation details of different capabilities defined below. initializationOptions can be processed by the runtime and used to initialize features according to their implementation details. For information on which options are used, please see Initilization sections in each feature.
Features and modes can be communicated to the server at startup through command line arguments. Implementation detail of the Standalone Server is that it can be started with a special --set-credentials-encryption-key argument to enter special flow for accepting encryption options as an argument before starting the main LSP connection.
`
server-standalone.exe
[--version] - server returns its version
...
Server startup diagram:
#### Encryption
Runtimes support the passing of encrypted credentials over LSP with stdio as transport. Encryption options must be sent to the runtime over stdin before the LSP initalization starts. Currently, runtimes support AES symmetric encryption with 256 bit keys.
The following steps outline how to enable encrypted credentials:
1. Create a random 256 bit (32 byte) encryption key.
2. Pass the
command line argument to the server process at launch. This will signal to the server that the client wants to enable encryption and will wait for the encryption options during the next 5 seconds.
3. Immediately send a JSON blob over stdin with the information in the script below, followed by the new line /n character, which will signal the end of transmission to the runtime. If LSP initialization continues, encryption options have been validated and saved. If the client fails to send encryption options during the first 5 seconds or the JSON object is invalid, the process will exit with status code 10.`json
{
"version": "1.0",
"key": "",
"mode": "JWT"
}
`4. After LSP initialization is complete, destinations should send credentials over LSP and are responsible for keeping them updated.
To send encrypted credentials, the
parameters should be sent over the corresponding aws/credentials/${type}/update method.UpdateCredentialsPayload specification:1. - encrypted: set to
true ;
2. - data: string value representing the encrypted JWT token. Encryption must be done with { alg: 'dir', enc: 'A256GCM' } parameters. The payload to be encrypted must contain data field with the credentials.
3. Clients can set nbf/exp claims on the JWT token, which will be validated on the runtime side. A clockTolerance of 60 seconds is allowed when verifying the claims.`json
// JWT payload to be encrypted
{
"data":
}
``TBD
See CONTRIBUTING for more information.
This project is licensed under the Apache-2.0 License.