hamza.khyari
6a8f724299
CI / build (pull_request) Successful in 18s
CI / security (pull_request) Successful in 58s
CI / lint (pull_request) Successful in 3m19s
CI / typecheck (pull_request) Successful in 3m54s
CI / quality (pull_request) Successful in 3m55s
CI / integration_tests (pull_request) Successful in 6m49s
CI / unit_tests (pull_request) Successful in 7m3s
CI / docker (pull_request) Successful in 1m6s
CI / e2e_tests (pull_request) Successful in 11m45s
CI / benchmark-publish (pull_request) Has been skipped
CI / coverage (pull_request) Successful in 12m52s
CI / status-check (pull_request) Successful in 2s
CI / benchmark-regression (pull_request) Successful in 58m46s
Align LspCapability enum with the spec's 11-capability set
(docs/specification.md lines 20705-20717):
Renamed: TYPE_INFO -> HOVER, SYMBOLS -> DOCUMENT_SYMBOLS,
FORMAT -> FORMATTING
Added: DEFINITIONS, SIGNATURE_HELP, WORKSPACE_SYMBOLS
Updated LspToolAdapter._CAPABILITY_TOOL_MAP (11 entries):
- code_actions suffix -> code-actions (hyphen per spec)
- RENAME gets dedicated schema with new_name parameter
- workspace_symbols gets query-based schema
Updated _input_schema_for() with 4 schema categories extracted
to module-level constants: file-only, position-based, rename
(with new_name), and query-based. Added defensive ValueError for
unmapped capabilities. Added additionalProperties: false.
Extended LspClient.initialize() to advertise all 11 capabilities
in the initialize request (hover, definition, references, rename,
codeAction, formatting, signatureHelp, documentSymbol, workspace
symbol).
Fixed _make_runtime_handler() to handle workspace_symbols as
query-only input (no file_path required), resolving the
schema/handler contract mismatch.
Fixed stale references: type_info -> hover, symbols ->
document_symbols in test fixtures, feature files, CLI docstring.
Updated docs/reference/lsp.md and CHANGELOG.md.
Behave tests (38 scenarios): enum completeness, tool spec generation
with structural validation, input schema per category, all 11
stubbed provider keys, negative tests for invalid capability and
defensive ValueError branch.
ISSUES CLOSED: #834
125 lines
5.0 KiB
Markdown
125 lines
5.0 KiB
Markdown
# LSP Integration
|
|
|
|
Language Server Protocol (LSP) servers are registered in a global **LSP Registry** (namespaced like all other entities) and bound to actor graph nodes via YAML configuration. When an actor activates, the LSP Runtime starts the appropriate language servers. LSP capabilities (diagnostics, type info, symbol navigation, completions, references, rename, code actions) are exposed to the actor as callable tools (via the `LspToolAdapter`) and as automatic context enrichment.
|
|
|
|
## Local-Mode Constraints
|
|
|
|
In **local mode** the LSP subsystem operates as a set of stubs:
|
|
|
|
| Component | Local-Mode Behavior |
|
|
|--------------------|----------------------------------------------------|
|
|
| `LspRegistry` | Fully functional — register, list, remove servers |
|
|
| `LspRuntime` | Raises `LspNotAvailableError` on every operation |
|
|
| `LspToolAdapter` | Generates tool specs whose handlers always raise |
|
|
|
|
The registry is available for configuration and validation purposes even in local mode. The runtime and tool adapter become functional only when server mode is enabled.
|
|
|
|
## Models
|
|
|
|
### LspCapability
|
|
|
|
Enum of LSP features that can be exposed as tools:
|
|
|
|
| Value | Description |
|
|
|--------------------|------------------------------------------------|
|
|
| `DIAGNOSTICS` | Retrieve diagnostics (errors/warnings) |
|
|
| `HOVER` | Get type information and documentation |
|
|
| `COMPLETIONS` | Get code completion suggestions |
|
|
| `DEFINITIONS` | Go to the definition of a symbol |
|
|
| `REFERENCES` | Find all references to a symbol |
|
|
| `RENAME` | Rename a symbol across the workspace |
|
|
| `CODE_ACTIONS` | Retrieve available code actions for a range |
|
|
| `FORMATTING` | Format a document or selection |
|
|
| `SIGNATURE_HELP` | Get function signature information at a call |
|
|
| `DOCUMENT_SYMBOLS` | List all symbols in a file |
|
|
| `WORKSPACE_SYMBOLS`| Search for symbols across the workspace |
|
|
|
|
### LspServerConfig
|
|
|
|
Registration record for a language server:
|
|
|
|
| Field | Type | Description |
|
|
|----------------|----------------------|--------------------------------------|
|
|
| `name` | `str` | Namespaced server name |
|
|
| `languages` | `list[str]` | Programming languages served |
|
|
| `command` | `str` | Executable command to start server |
|
|
| `args` | `list[str]` | Additional CLI arguments |
|
|
| `env` | `dict[str, str]` | Environment variables |
|
|
| `capabilities` | `list[LspCapability]`| Capabilities exposed by this server |
|
|
|
|
### LspBinding
|
|
|
|
Binds an LSP server to an actor graph node:
|
|
|
|
| Field | Type | Description |
|
|
|--------------------|-------------|------------------------------------------|
|
|
| `node_name` | `str` | Actor graph node name |
|
|
| `lsp_server_name` | `str` | Namespaced LSP server name |
|
|
| `languages` | `list[str]` | Subset of languages (empty = all) |
|
|
| `auto_detect` | `bool` | Auto-detect language from file context |
|
|
|
|
## Error Hierarchy
|
|
|
|
All errors inherit from `CleverAgentsError`:
|
|
|
|
```
|
|
CleverAgentsError
|
|
└── LspError (base for all LSP errors)
|
|
├── LspNotAvailableError (operation attempted in local mode)
|
|
└── LspServerNotFoundError (server not in registry)
|
|
```
|
|
|
|
## CLI Commands
|
|
|
|
| Command | Description |
|
|
|---------------------------|----------------------------------------|
|
|
| `agents lsp add` | Register server from YAML config |
|
|
| `agents lsp remove` | Remove a registered server |
|
|
| `agents lsp list` | List servers with optional filters |
|
|
| `agents lsp show` | Show full server details |
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Register a Pyright LSP server
|
|
agents lsp add --config ./lsp/pyright.yaml
|
|
|
|
# List all Python language servers
|
|
agents lsp list --language python
|
|
|
|
# Show details for a specific server
|
|
agents lsp show local/pyright
|
|
|
|
# Remove a server
|
|
agents lsp remove local/pyright --yes
|
|
```
|
|
|
|
### YAML Configuration
|
|
|
|
```yaml
|
|
name: local/pyright
|
|
command: pyright-langserver
|
|
args: ["--stdio"]
|
|
languages: ["python"]
|
|
capabilities:
|
|
- diagnostics
|
|
- completions
|
|
- hover
|
|
- definitions
|
|
- references
|
|
- rename
|
|
env:
|
|
PYTHONPATH: ./src
|
|
```
|
|
|
|
## Thread Safety
|
|
|
|
The `LspRegistry` uses a `threading.RLock` to ensure safe concurrent access. All public methods (`register`, `get`, `list_servers`, `remove`) acquire the lock before reading or mutating state.
|
|
|
|
## Namespacing
|
|
|
|
LSP server names follow the project-wide namespacing pattern: `[[server:]namespace/]name`. For example:
|
|
|
|
- `local/pyright` — a locally-defined Pyright server
|
|
- `devops/clangd` — a clangd server in the devops namespace
|