UAT: LspToolAdapter only routes 4 of 11 declared LSP capabilities to runtime — 7 capabilities raise LspNotAvailableError even with runtime attached #2919

Open
opened 2026-04-05 02:48:36 +00:00 by freemo · 1 comment
Owner

Metadata

  • Branch: fix/lsp-tool-adapter-missing-capability-handlers
  • Commit Message: fix(lsp): implement missing runtime handlers for 7 LSP capabilities in LspToolAdapter
  • Milestone: v3.6.0
  • Parent Epic: #824

Background and Context

The LspToolAdapter is responsible for exposing all declared LSP capabilities as callable tools that delegate to the LspRuntime when a runtime is attached. The specification defines 11 LSP capabilities that must be fully routable: diagnostics, type_info (hover), symbol_navigation (definitions), completions, rename, code_actions, references, formatting, signature_help, document_symbols, and workspace_symbols.

Discovered during UAT testing of the LSP Integration feature area. Actors that declare any of the 7 unimplemented capabilities in their LSP server config will have tool specs generated for them (giving the impression the capability is available), but invoking those tools will always raise LspNotAvailableError — even when a fully connected LspRuntime is attached. This is a silent failure mode that is difficult to diagnose at runtime.

Current Behavior

_make_runtime_handler() in src/cleveragents/lsp/tool_adapter.py (lines ~100–145) only dispatches 4 of the 11 declared capabilities:

Capability Handler Status
DIAGNOSTICS runtime.get_diagnostics() Implemented
COMPLETIONS runtime.get_completions() Implemented
HOVER runtime.get_hover() Implemented
DEFINITIONS runtime.get_definitions() Implemented
REFERENCES Raises LspNotAvailableError
RENAME Raises LspNotAvailableError
CODE_ACTIONS Raises LspNotAvailableError
FORMATTING Raises LspNotAvailableError
SIGNATURE_HELP Raises LspNotAvailableError
DOCUMENT_SYMBOLS Raises LspNotAvailableError
WORKSPACE_SYMBOLS Raises LspNotAvailableError (special "not yet implemented" message)

The remaining 7 capabilities fall through to the final raise LspNotAvailableError(...) at the bottom of _make_runtime_handler(). The root cause is that LspRuntime and LspClient do not implement the corresponding methods (get_references, get_rename, get_code_actions, get_formatting, get_signature_help, get_document_symbols, get_workspace_symbols).

Expected Behavior

All 11 LSP capabilities declared in LspCapability must be handled by _make_runtime_handler(). When a runtime is attached, each capability must delegate to the corresponding LspRuntime method and return real LSP data. No declared capability should fall through to LspNotAvailableError when a runtime is connected.

Acceptance Criteria

  • _make_runtime_handler() contains dispatch branches for all 11 LspCapability enum values.
  • LspRuntime exposes get_references(), get_rename(), get_code_actions(), get_formatting(), get_signature_help(), get_document_symbols(), and get_workspace_symbols() methods.
  • LspClient implements the corresponding 7 LSP protocol calls.
  • Calling any of the 7 previously-broken capabilities via LspToolAdapter with a connected runtime returns a valid result (not LspNotAvailableError).
  • Calling any capability without a runtime still raises LspNotAvailableError as expected.
  • All existing tests continue to pass.

Supporting Information

  • File: src/cleveragents/lsp/tool_adapter.py, function _make_runtime_handler() (~lines 100–145)
  • Parent Epic: #824 (Epic: LSP Functional Runtime)
  • Related issues: #826 (implement functional LSP runtime), #834 (add missing LspCapability enum values)
  • Severity: High — actors using LSP capabilities beyond the basic 4 will silently receive error responses instead of real LSP data, with no indication that the runtime is connected but the handler is missing.

Subtasks

  • Audit LspCapability enum for the full list of declared capabilities and cross-reference against _make_runtime_handler() dispatch branches
  • Implement LspClient.get_references() — LSP textDocument/references request
  • Implement LspClient.get_rename() — LSP textDocument/rename request
  • Implement LspClient.get_code_actions() — LSP textDocument/codeAction request
  • Implement LspClient.get_formatting() — LSP textDocument/formatting request
  • Implement LspClient.get_signature_help() — LSP textDocument/signatureHelp request
  • Implement LspClient.get_document_symbols() — LSP textDocument/documentSymbol request
  • Implement LspClient.get_workspace_symbols() — LSP workspace/symbol request
  • Implement LspRuntime.get_references() delegating to LspClient
  • Implement LspRuntime.get_rename() delegating to LspClient
  • Implement LspRuntime.get_code_actions() delegating to LspClient
  • Implement LspRuntime.get_formatting() delegating to LspClient
  • Implement LspRuntime.get_signature_help() delegating to LspClient
  • Implement LspRuntime.get_document_symbols() delegating to LspClient
  • Implement LspRuntime.get_workspace_symbols() delegating to LspClient
  • Add dispatch branches in _make_runtime_handler() for all 7 missing capabilities
  • Tests (unit): Add unit tests for each new LspRuntime method
  • Tests (unit): Add unit tests for each new LspClient method
  • Tests (Behave): Add BDD scenarios covering all 11 capabilities via LspToolAdapter with a connected runtime
  • Tests (Behave): Add scenario verifying LspNotAvailableError is raised for all capabilities when no runtime is attached
  • Verify coverage >= 97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

  • All subtasks above are completed and checked off.
  • A Git commit is created where the first line of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation.
  • The commit is pushed to the remote on the branch matching the Branch in Metadata exactly.
  • The commit is submitted as a pull request to master, reviewed, and merged before this issue is marked done.
  • All nox stages pass.
  • Coverage >= 97%.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/lsp-tool-adapter-missing-capability-handlers` - **Commit Message**: `fix(lsp): implement missing runtime handlers for 7 LSP capabilities in LspToolAdapter` - **Milestone**: v3.6.0 - **Parent Epic**: #824 ## Background and Context The `LspToolAdapter` is responsible for exposing all declared LSP capabilities as callable tools that delegate to the `LspRuntime` when a runtime is attached. The specification defines 11 LSP capabilities that must be fully routable: `diagnostics`, `type_info` (hover), `symbol_navigation` (definitions), `completions`, `rename`, `code_actions`, `references`, `formatting`, `signature_help`, `document_symbols`, and `workspace_symbols`. Discovered during UAT testing of the LSP Integration feature area. Actors that declare any of the 7 unimplemented capabilities in their LSP server config will have tool specs generated for them (giving the impression the capability is available), but invoking those tools will always raise `LspNotAvailableError` — even when a fully connected `LspRuntime` is attached. This is a silent failure mode that is difficult to diagnose at runtime. ## Current Behavior `_make_runtime_handler()` in `src/cleveragents/lsp/tool_adapter.py` (lines ~100–145) only dispatches 4 of the 11 declared capabilities: | Capability | Handler | Status | |---|---|---| | `DIAGNOSTICS` | `runtime.get_diagnostics()` | ✅ Implemented | | `COMPLETIONS` | `runtime.get_completions()` | ✅ Implemented | | `HOVER` | `runtime.get_hover()` | ✅ Implemented | | `DEFINITIONS` | `runtime.get_definitions()` | ✅ Implemented | | `REFERENCES` | — | ❌ Raises `LspNotAvailableError` | | `RENAME` | — | ❌ Raises `LspNotAvailableError` | | `CODE_ACTIONS` | — | ❌ Raises `LspNotAvailableError` | | `FORMATTING` | — | ❌ Raises `LspNotAvailableError` | | `SIGNATURE_HELP` | — | ❌ Raises `LspNotAvailableError` | | `DOCUMENT_SYMBOLS` | — | ❌ Raises `LspNotAvailableError` | | `WORKSPACE_SYMBOLS` | — | ❌ Raises `LspNotAvailableError` (special "not yet implemented" message) | The remaining 7 capabilities fall through to the final `raise LspNotAvailableError(...)` at the bottom of `_make_runtime_handler()`. The root cause is that `LspRuntime` and `LspClient` do not implement the corresponding methods (`get_references`, `get_rename`, `get_code_actions`, `get_formatting`, `get_signature_help`, `get_document_symbols`, `get_workspace_symbols`). ## Expected Behavior All 11 LSP capabilities declared in `LspCapability` must be handled by `_make_runtime_handler()`. When a runtime is attached, each capability must delegate to the corresponding `LspRuntime` method and return real LSP data. No declared capability should fall through to `LspNotAvailableError` when a runtime is connected. ## Acceptance Criteria - `_make_runtime_handler()` contains dispatch branches for all 11 `LspCapability` enum values. - `LspRuntime` exposes `get_references()`, `get_rename()`, `get_code_actions()`, `get_formatting()`, `get_signature_help()`, `get_document_symbols()`, and `get_workspace_symbols()` methods. - `LspClient` implements the corresponding 7 LSP protocol calls. - Calling any of the 7 previously-broken capabilities via `LspToolAdapter` with a connected runtime returns a valid result (not `LspNotAvailableError`). - Calling any capability without a runtime still raises `LspNotAvailableError` as expected. - All existing tests continue to pass. ## Supporting Information - **File**: `src/cleveragents/lsp/tool_adapter.py`, function `_make_runtime_handler()` (~lines 100–145) - **Parent Epic**: #824 (Epic: LSP Functional Runtime) - **Related issues**: #826 (implement functional LSP runtime), #834 (add missing LspCapability enum values) - **Severity**: High — actors using LSP capabilities beyond the basic 4 will silently receive error responses instead of real LSP data, with no indication that the runtime is connected but the handler is missing. ## Subtasks - [ ] Audit `LspCapability` enum for the full list of declared capabilities and cross-reference against `_make_runtime_handler()` dispatch branches - [ ] Implement `LspClient.get_references()` — LSP `textDocument/references` request - [ ] Implement `LspClient.get_rename()` — LSP `textDocument/rename` request - [ ] Implement `LspClient.get_code_actions()` — LSP `textDocument/codeAction` request - [ ] Implement `LspClient.get_formatting()` — LSP `textDocument/formatting` request - [ ] Implement `LspClient.get_signature_help()` — LSP `textDocument/signatureHelp` request - [ ] Implement `LspClient.get_document_symbols()` — LSP `textDocument/documentSymbol` request - [ ] Implement `LspClient.get_workspace_symbols()` — LSP `workspace/symbol` request - [ ] Implement `LspRuntime.get_references()` delegating to `LspClient` - [ ] Implement `LspRuntime.get_rename()` delegating to `LspClient` - [ ] Implement `LspRuntime.get_code_actions()` delegating to `LspClient` - [ ] Implement `LspRuntime.get_formatting()` delegating to `LspClient` - [ ] Implement `LspRuntime.get_signature_help()` delegating to `LspClient` - [ ] Implement `LspRuntime.get_document_symbols()` delegating to `LspClient` - [ ] Implement `LspRuntime.get_workspace_symbols()` delegating to `LspClient` - [ ] Add dispatch branches in `_make_runtime_handler()` for all 7 missing capabilities - [ ] Tests (unit): Add unit tests for each new `LspRuntime` method - [ ] Tests (unit): Add unit tests for each new `LspClient` method - [ ] Tests (Behave): Add BDD scenarios covering all 11 capabilities via `LspToolAdapter` with a connected runtime - [ ] Tests (Behave): Add scenario verifying `LspNotAvailableError` is raised for all capabilities when no runtime is attached - [ ] Verify coverage >= 97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. - All nox stages pass. - Coverage >= 97%. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator
freemo added this to the v3.6.0 milestone 2026-04-05 02:48:41 +00:00
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: High (confirmed)
  • MoSCoW: Should Have — 7 of 11 LSP capabilities not routed at runtime

Valid UAT finding verified during batch triage.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: High (confirmed) - **MoSCoW**: Should Have — 7 of 11 LSP capabilities not routed at runtime Valid UAT finding verified during batch triage. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#824 Epic: LSP Functional Runtime
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#2919
No description provided.