# aws/language-server-runtimes architecture

> Architecture diagram of the GitHub repository aws/language-server-runtimes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws/language-server-runtimes
- Repository: https://github.com/aws/language-server-runtimes

## Overview

Language Server Runtimes is a library for building language servers that expose protocol features to clients and provide a capability interface to server implementations. The main flow is client LSP traffic through a runtime entry point and router to registered servers, with protocol contracts defining messages and server interfaces defining available features. Distinct branches cover chat, credentials and identity management, agent support, telemetry, and standalone runtime utilities. Several implementation files are indexed but unsampled, so their documented capabilities are represented without asserting unverified call paths.

Main entry points: [`runtimes/runtimes/base-runtime.ts`](https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/base-runtime.ts) (Runtime entry), [`runtimes/server-interface/server.ts`](https://github.com/aws/language-server-runtimes/blob/main/runtimes/server-interface/server.ts) (Server contract), [`runtimes/runtimes/lsp/router/lspRouter.ts`](https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/lsp/router/lspRouter.ts) (LSP router), [`runtimes/runtimes/standalone.ts`](https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/standalone.ts) (Standalone runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime core"]
  node_entry["Runtime entry<br/>[base-runtime.ts]"]
  node_webworker["Web worker<br/>[webworker.ts]"]
  node_router["LSP router<br/>[lspRouter.ts]"]
  node_router_server["LSP server<br/>[lspServer.ts]"]
end

subgraph group_contracts["Protocol contracts"]
  node_protocol["LSP protocol<br/>[lsp.ts]"]
  node_protocol_features["Feature protocols"]
  node_types["Runtime types"]
  node_identity_protocol["Identity protocol"]
end

subgraph group_capabilities["Server capabilities"]
  node_server_contract["Server contract<br/>[server.ts]"]
  node_server_lsp["LSP interface<br/>[lsp.ts]"]
  node_identity_iface["Identity interface"]
  node_agent_iface["Agent interface<br/>[agent.ts]"]
  node_chat_iface["Chat interface<br/>[chat.ts]"]
end

subgraph group_services["Runtime services"]
  node_auth["Credentials service<br/>[auth.ts]"]
  node_chat_runtime["Chat runtime<br/>[baseChat.ts]"]
  node_agent_runtime["Agent runtime<br/>[agent.ts]"]
  node_telemetry["Operational telemetry"]
end

subgraph group_standalone["Standalone support"]
  node_standalone["Standalone runtime<br/>[standalone.ts]"]
  node_checked_files["Checked file operations"]
  node_proxy["Proxy support"]
end

node_client(("LSP client"))

node_client -->|"sends LSP"| node_entry
node_webworker -->|"configures transport"| node_entry
node_entry -->|"creates router"| node_router
node_entry -->|"sets up server"| node_router_server
node_router -->|"routes requests"| node_router_server
node_router -->|"registers handlers"| node_client
node_router -.->|"dispatches to servers"| node_server_contract
node_server_contract -->|"exposes feature"| node_server_lsp
node_server_contract -->|"exposes feature"| node_identity_iface
node_server_contract -->|"exposes feature"| node_agent_iface
node_server_contract -->|"exposes feature"| node_chat_iface
node_protocol_features -->|"uses LSP base"| node_protocol
node_identity_iface -->|"defines handlers"| node_identity_protocol
node_entry -->|"initializes"| node_auth
node_auth -->|"handles credential messages"| node_identity_protocol
node_entry -->|"initializes"| node_chat_runtime
node_entry -->|"initializes"| node_agent_runtime
node_entry -->|"configures"| node_telemetry
node_standalone -.->|"uses file checks"| node_checked_files
node_standalone -.->|"supports proxy setup"| node_proxy
node_protocol -->|"re-exports shared types"| node_types

click node_entry "https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/base-runtime.ts"
click node_webworker "https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/webworker.ts"
click node_router "https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/lsp/router/lspRouter.ts"
click node_router_server "https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/lsp/router/lspServer.ts"
click node_protocol "https://github.com/aws/language-server-runtimes/blob/main/runtimes/protocol/lsp.ts"
click node_protocol_features "https://github.com/aws/language-server-runtimes/tree/main/runtimes/protocol"
click node_types "https://github.com/aws/language-server-runtimes/tree/main/types"
click node_server_contract "https://github.com/aws/language-server-runtimes/blob/main/runtimes/server-interface/server.ts"
click node_server_lsp "https://github.com/aws/language-server-runtimes/blob/main/runtimes/server-interface/lsp.ts"
click node_identity_iface "https://github.com/aws/language-server-runtimes/blob/main/runtimes/server-interface/identity-management.ts"
click node_agent_iface "https://github.com/aws/language-server-runtimes/blob/main/runtimes/server-interface/agent.ts"
click node_chat_iface "https://github.com/aws/language-server-runtimes/blob/main/runtimes/server-interface/chat.ts"
click node_auth "https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/auth/auth.ts"
click node_identity_protocol "https://github.com/aws/language-server-runtimes/blob/main/runtimes/protocol/identity-management.ts"
click node_chat_runtime "https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/chat/baseChat.ts"
click node_agent_runtime "https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/agent.ts"
click node_telemetry "https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/operational-telemetry/operational-telemetry.ts"
click node_standalone "https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/standalone.ts"
click node_checked_files "https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/util/standalone/checkedFileOperations.ts"
click node_proxy "https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/util/standalone/experimentalProxyUtil.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_webworker,node_router,node_router_server,node_client toneBlue
class node_protocol,node_protocol_features,node_types,node_identity_protocol toneAmber
class node_server_contract,node_server_lsp,node_identity_iface,node_agent_iface,node_chat_iface toneMint
class node_auth,node_chat_runtime,node_agent_runtime,node_telemetry toneRose
class node_standalone,node_checked_files,node_proxy toneIndigo
```

## Components

### Runtime core

- [Runtime entry](https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/base-runtime.ts): `runtimes/runtimes/base-runtime.ts`
- [Web worker](https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/webworker.ts): `runtimes/runtimes/webworker.ts`
- [LSP router](https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/lsp/router/lspRouter.ts): `runtimes/runtimes/lsp/router/lspRouter.ts`
- [LSP server](https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/lsp/router/lspServer.ts): `runtimes/runtimes/lsp/router/lspServer.ts`

### Protocol contracts

- [LSP protocol](https://github.com/aws/language-server-runtimes/blob/main/runtimes/protocol/lsp.ts): `runtimes/protocol/lsp.ts`
- [Feature protocols](https://github.com/aws/language-server-runtimes/tree/main/runtimes/protocol): `runtimes/protocol`
- [Runtime types](https://github.com/aws/language-server-runtimes/tree/main/types): `types`
- [Identity protocol](https://github.com/aws/language-server-runtimes/blob/main/runtimes/protocol/identity-management.ts): `runtimes/protocol/identity-management.ts`

### Server capabilities

- [Server contract](https://github.com/aws/language-server-runtimes/blob/main/runtimes/server-interface/server.ts): `runtimes/server-interface/server.ts`
- [LSP interface](https://github.com/aws/language-server-runtimes/blob/main/runtimes/server-interface/lsp.ts): `runtimes/server-interface/lsp.ts`
- [Identity interface](https://github.com/aws/language-server-runtimes/blob/main/runtimes/server-interface/identity-management.ts): `runtimes/server-interface/identity-management.ts`
- [Agent interface](https://github.com/aws/language-server-runtimes/blob/main/runtimes/server-interface/agent.ts): `runtimes/server-interface/agent.ts`
- [Chat interface](https://github.com/aws/language-server-runtimes/blob/main/runtimes/server-interface/chat.ts): `runtimes/server-interface/chat.ts`

### Runtime services

- [Credentials service](https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/auth/auth.ts): `runtimes/runtimes/auth/auth.ts`
- [Chat runtime](https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/chat/baseChat.ts): `runtimes/runtimes/chat/baseChat.ts`
- [Agent runtime](https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/agent.ts): `runtimes/runtimes/agent.ts`
- [Operational telemetry](https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/operational-telemetry/operational-telemetry.ts): `runtimes/runtimes/operational-telemetry/operational-telemetry.ts`

### Standalone support

- [Standalone runtime](https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/standalone.ts): `runtimes/runtimes/standalone.ts`
- [Checked file operations](https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/util/standalone/checkedFileOperations.ts): `runtimes/runtimes/util/standalone/checkedFileOperations.ts`
- [Proxy support](https://github.com/aws/language-server-runtimes/blob/main/runtimes/runtimes/util/standalone/experimentalProxyUtil.ts): `runtimes/runtimes/util/standalone/experimentalProxyUtil.ts`

### Other components

- **LSP client**

## Connections

- LSP client → Runtime entry: sends LSP
- Web worker → Runtime entry: configures transport (evidence: `runtimes/runtimes/webworker.ts`)
- Runtime entry → LSP router: creates router (evidence: `runtimes/runtimes/base-runtime.ts`)
- Runtime entry → LSP server: sets up server (evidence: `runtimes/runtimes/base-runtime.ts`)
- LSP router → LSP server: routes requests (evidence: `runtimes/runtimes/lsp/router/lspRouter.ts`)
- LSP router → LSP client: registers handlers (evidence: `runtimes/runtimes/lsp/router/lspRouter.ts`)
- LSP router → Server contract: dispatches to servers
- Server contract → LSP interface: exposes feature (evidence: `runtimes/server-interface/server.ts`)
- Server contract → Identity interface: exposes feature (evidence: `runtimes/server-interface/server.ts`)
- Server contract → Agent interface: exposes feature (evidence: `runtimes/server-interface/server.ts`)
- Server contract → Chat interface: exposes feature (evidence: `runtimes/server-interface/server.ts`)
- Feature protocols → LSP protocol: uses LSP base (evidence: `runtimes/protocol/auth.ts`)
- Identity interface → Identity protocol: defines handlers (evidence: `runtimes/server-interface/identity-management.ts`)
- Runtime entry → Credentials service: initializes (evidence: `runtimes/runtimes/base-runtime.ts`)
- Credentials service → Identity protocol: handles credential messages (evidence: `runtimes/runtimes/auth/auth.ts`)
- Runtime entry → Chat runtime: initializes (evidence: `runtimes/runtimes/base-runtime.ts`)
- Runtime entry → Agent runtime: initializes (evidence: `runtimes/runtimes/base-runtime.ts`)
- Runtime entry → Operational telemetry: configures (evidence: `runtimes/runtimes/base-runtime.ts`)
- Standalone runtime → Checked file operations: uses file checks
- Standalone runtime → Proxy support: supports proxy setup
- LSP protocol → Runtime types: re-exports shared types (evidence: `runtimes/protocol/lsp.ts`)