cleveragents-core/docs/api/lsp.md

cleveragents.lsp — Language Server Protocol Integration

The lsp package provides the registry, runtime, tool adapter, server stub, protocol client, transport, and lifecycle manager for integrating Language Server Protocol (LSP) servers with CleverAgents actors.

See ADR-027 for design rationale and ADR-040 for LSP resource types.

---

Quick Start

from cleveragents.lsp import (
    LspRegistry,
    LspRuntime,
    LspServerConfig,
    LspCapability,
    LspTransport,
)

# Register a language server
registry = LspRegistry()
registry.register(LspServerConfig(
    name="local/pyright",
    description="Python type checker and language server",
    languages=["python"],
    command="pyright-langserver",
    args=["--stdio"],
    transport=LspTransport.STDIO,
    capabilities=[LspCapability.DIAGNOSTICS, LspCapability.COMPLETIONS],
))

# Start and query
runtime = LspRuntime(registry=registry)
runtime.start_server("local/pyright", workspace_path="/path/to/project")
diagnostics = runtime.get_diagnostics("local/pyright", file_path="src/main.py")

---

Enumerations

LspTransport

Transport mechanism for LSP server communication.

Member	Value	Description
STDIO	"stdio"	Standard input/output (default). Server spawned as subprocess.
TCP	"tcp"	TCP socket connection. Server listens on a port.

LspCapability

LSP capabilities that can be exposed as callable tools to actors.

Member	Value	Description
DIAGNOSTICS	"diagnostics"	Syntax and type errors
HOVER	"hover"	Type information on hover
COMPLETIONS	"completions"	Code completion suggestions
DEFINITIONS	"definitions"	Go-to-definition
REFERENCES	"references"	Find all references
RENAME	"rename"	Symbol rename
CODE_ACTIONS	"code_actions"	Quick fixes and refactors
FORMATTING	"formatting"	Document formatting
SIGNATURE_HELP	"signature_help"	Function signature hints
DOCUMENT_SYMBOLS	"document_symbols"	Outline of symbols in a file
WORKSPACE_SYMBOLS	"workspace_symbols"	Workspace-wide symbol search

---

Data Models

LspServerConfig

Registration record for a language server.

Field	Type	Required	Description
name	str	Yes	Namespaced server name (e.g. local/pyright)
description	str	No	Human-readable description
languages	list[str]	No	Programming languages served
command	str	Yes	Executable command to start the server
args	list[str]	No	Additional CLI arguments
transport	LspTransport	No	Communication transport (default: STDIO)
env	dict[str, str]	No	Extra environment variables
capabilities	list[LspCapability]	No	Capabilities this server exposes
initialization	dict[str, Any]	No	Custom initializationOptions
workspace_settings	dict[str, Any]	No	Workspace settings sent after init

LspBinding

Binds an LSP server to an actor graph node.

Field	Type	Description
node_name	str	Actor graph node name that owns the binding
lsp_server_name	str	Namespaced server name (must contain /)
languages	list[str]	Optional language allow-list (empty ⇒ all languages)
auto_detect	bool	Auto-detect language from file context when True

---

LspRegistry

Thread-safe, in-memory registry for LSP server configurations.

from cleveragents.lsp import LspRegistry, LspServerConfig

registry = LspRegistry()

Method	Signature	Description
register	(config: LspServerConfig) -> None	Register a server config; raises ValueError if name already registered
get	`(name: str) -> LspServerConfig	None`
get_or_raise	(name: str) -> LspServerConfig	Retrieve by name; raises LspServerNotFoundError if not found
remove	(name: str) -> bool	Remove a server config; returns True if removed
list_servers	`(namespace: str	None = None, language: str

Use Python membership testing (name in registry) to check for registration; the registry implements __contains__ and __len__ for introspection.

---

LspRuntime

Manages the full lifecycle of language servers: start, query, health-check, restart, and stop.

from cleveragents.lsp import LspRuntime, LspRegistry

runtime = LspRuntime(registry=registry)

Method	Signature	Description
start_server	(name: str, workspace_path: str) -> None	Start a server; performs the LSP initialize handshake
stop_server	(name: str) -> None	Stop a running server (reference-counted)
get_diagnostics	(name: str, file_path: str) -> list[dict[str, Any]]	Retrieve diagnostics for a file
get_completions	(name: str, file_path: str, line: int, column: int) -> list[Any]	Code completions at a position
get_hover	`(name: str, file_path: str, line: int, column: int) -> dict[str, Any]	None`
get_definitions	(name: str, file_path: str, line: int, column: int) -> list[dict[str, Any]]	Go-to-definition locations
activate_bindings	(bindings: list[Any], workspace_path: str) -> list[str]	Start servers referenced by actor bindings
deactivate_bindings	(bindings: list[Any]) -> None	Release servers referenced by actor bindings
stop_all	() -> None	Stop all running servers

Automatic restart: If a server crashes during a query, the runtime attempts one automatic restart before raising LspError.

---

LspToolAdapter

Bridges LSP capabilities into the CleverAgents tool system. Each registered capability becomes a callable tool in ToolRegistry with source="lsp".

from cleveragents.lsp import LspToolAdapter, LspRuntime

adapter = LspToolAdapter(runtime=runtime)
specs = adapter.generate_tool_specs(registry.get_or_raise("local/pyright"))
# specs: list[dict] for ToolRegistry.register_many(...)

When no runtime is supplied, tool handlers raise LspNotAvailableError rather than silently returning empty results.

---

Low-level Exports

The following utilities are re-exported for advanced scenarios:

• LanguageDiscovery — Detects language IDs from file paths for runtime operations.
• LspServer — Lightweight server wrapper used by the lifecycle manager.
• StdioTransport — Concrete transport implementation for stdio-based servers.

Most applications interact with these indirectly via LspRuntime and LspLifecycleManager.

---

LspLifecycleManager

Manages LSP server process spawning, health checks, and graceful shutdown. Used internally by LspRuntime; rarely needed directly.

from cleveragents.lsp import LspLifecycleManager

manager = LspLifecycleManager()
manager.start("local/pyright", config, workspace_path="/path/to/project")
manager.stop("local/pyright")

---

LspClient

Low-level JSON-RPC 2.0 client for LSP protocol communication. Used internally by LspRuntime; prefer LspRuntime for most use cases.

---

Errors

Exception	Description
LspError	Base class for all LSP errors
LspNotAvailableError	Raised when LSP runtime is not configured
LspServerNotFoundError	Raised when a server name is not in the registry

---

Actor YAML Integration

Per-node LSP bindings in actor YAML control which server each node uses:

name: local/my-actor
nodes:
  analyzer:
    model: anthropic/claude-4-sonnet
    lsp_bindings:
      - server: local/pyright
        capabilities: [diagnostics, completions, definitions]

---

Related Documentation

• LSP Reference — detailed protocol and lifecycle reference
• LSP Resource Types — lsp.* resource type definitions
• LSP Lifecycle Restart — automatic restart protocol
• ADR-027 — design rationale