# 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