freemo
740e08b2a4
5.7 KiB
ADR-027: Language Server Protocol (LSP) Integration
Status: Proposed
Date: 2026-02-17
Supersedes: None
Author(s): CleverAgents Team
Approver(s):
Context
CleverAgents needs deep IDE integration for plan-aware workflows: validation feedback displayed inline, context exploration on hover, and code actions that trigger plan operations. Building bespoke plugins for each editor (VS Code, JetBrains, Neovim, Emacs, etc.) would be expensive and prone to divergence. The architecture requires a single, standard, editor-agnostic interface that connects to the CleverAgents backend and behaves identically across local and server modes.
Decision
CleverAgents implements the IDE plugin as a Language Server Protocol (LSP) server. The LSP server surfaces plan-aware code actions, diagnostics, and context lookups, and communicates with the backend exclusively through ACP (ADR-026).
Design
LSP Server Role
The LSP server is a Presentation-layer adapter. It translates LSP requests into ACP calls and maps ACP responses back to LSP messages.
Editor ←— LSP JSON-RPC —→ LSP Server ←— ACP —→ Service Facade
Feature Mapping
| LSP Feature | CleverAgents Source | ACP Operation |
|---|---|---|
| Diagnostics | Validation results (required + informational) | validation.list_results |
| Code actions | Run validation, propose fix, apply plan, cancel plan | plan.execute, plan.apply, validation.run |
| Hover | Context snippets, decision provenance, UKO entity summaries | context.inspect |
| Workspace symbols | Registered resources, active plans, attached validations | resource.list, plan.list |
Workspace and Resource Resolution
- LSP workspace roots are matched to registered resource paths in the Resource Registry.
- File URI paths are resolved through the Resource Registry so that sandbox-resident files map correctly to their logical resources.
- If a workspace root does not correspond to a registered resource, plan-aware features degrade gracefully (standard editing still works).
Diagnostic Severity Mapping
| Validation Mode | LSP Severity |
|---|---|
required — failed |
Error |
required — passed |
(suppressed) |
informational — failed |
Warning |
informational — passed |
Hint |
Lifecycle
The LSP server is a long-lived process launched by the editor. It:
- Initializes an ACP client (in-process for local mode, HTTPS for server mode).
- Subscribes to plan and validation events via ACP streaming.
- Pushes diagnostics to the editor as events arrive.
- Handles editor-initiated requests (code actions, hover, completion) synchronously via ACP.
Constraints
- The LSP server must not access storage, database, or domain services directly — all operations go through ACP.
- IDE features must remain strictly editor-agnostic; no editor-specific APIs outside the LSP specification.
- LSP diagnostics must reflect validation results without modifying any resources (read-only at the presentation boundary).
- The LSP server must function in both local mode (in-process ACP) and server mode (remote ACP over HTTPS).
Consequences
Positive
- One integration serves all LSP-compatible editors (VS Code, JetBrains via LSP bridge, Neovim, Emacs, Helix, etc.).
- IDE features stay exactly aligned with CLI/TUI/Web behavior because they share the same ACP contract.
- Reduced maintenance burden compared to N bespoke editor plugins.
- Diagnostics arrive in real-time via ACP event streaming, keeping editors up to date during long-running plan execution.
Negative
- LSP's fixed feature set may limit richer custom UI experiences that specific editors could offer (e.g., custom webview panels in VS Code).
- ACP round-trips add latency to interactive IDE operations compared to direct in-process access.
Risks
- Future LSP specification changes could require compatibility work in the server.
- High-frequency IDE events (typing, hover) could place excessive load on ACP endpoints if not debounced.
Alternatives Considered
Editor-specific plugins — More tailored UX per editor but requires separate implementations and ongoing maintenance for each editor. Rejected as the primary strategy (may be revisited for value-add features on top of the LSP baseline).
Custom IDE protocol — Maximum flexibility but zero ecosystem adoption, higher learning curve for contributors, and no editor-side library support. Rejected.
Compliance
- LSP conformance tests: Validate request/response message formats and declared capabilities against the LSP specification.
- ACP integration tests: Verify that every LSP feature correctly maps to the corresponding ACP operation and produces the expected editor-visible result.
- Diagnostics tests: Ensure validation results translate to LSP diagnostics with the correct severity mapping and no resource side effects.
- Degradation tests: Verify graceful fallback when workspace roots do not map to registered resources.
Related ADRs
| ADR | Title | Relationship |
|---|---|---|
| ADR-001 | Layered Architecture | The LSP server is a Presentation-layer adapter |
| ADR-013 | Validation Abstraction | Validation results are the primary source for LSP diagnostics |
| ADR-026 | Agent Client Protocol (ACP) | The LSP server communicates with the backend exclusively through ACP |
Acceptance
Votes For
| Voter | Comment |
|---|
Total: 0
Votes Against
| Voter | Comment |
|---|
Total: 0
Abstentions
| Voter | Comment |
|---|
Total: 0