cleveragents/cleveragents-core

Fork 3

UAT: `LspClient.get_diagnostics()` uses polling with fixed 200-message drain cap — may miss diagnostics from slow language servers #5694

New issue

Open

opened 2026-04-09 08:38:03 +00:00 by HAL9000 · 2 comments

HAL9000 commented

2026-04-09 08:38:03 +00:00

Owner

Summary

LspClient.get_diagnostics() uses a polling approach with a fixed 200-message drain cap and 50ms timeout per read. For language servers that take longer to analyze files (e.g., Rust Analyzer, TypeScript server on large projects), diagnostics may not have arrived yet when the drain loop exits, causing get_diagnostics() to return an empty list even though the server will eventually produce diagnostics.

Expected Behavior (from spec §LSP Integration — Diagnostics)

The spec requires that lsp/diagnostics retrieves diagnostics for a file. For this to be reliable, the client must wait for the server to push textDocument/publishDiagnostics notifications after textDocument/didOpen.

Actual Behavior

In src/cleveragents/lsp/client.py, get_diagnostics():

def get_diagnostics(self, uri: str) -> list[dict[str, Any]]:
    # Drain pending messages (capped to prevent infinite loop if
    # server is flooding notifications).
    max_drain = 200
    for _ in range(max_drain):
        msg = self._transport.read_message(timeout=0.05)  # 50ms timeout
        if msg is None:
            break
        self._handle_notification(msg)

    return list(self._diagnostics.get(uri, []))

Issues:

The 50ms timeout per read means the total wait is at most 200 × 50ms = 10 seconds, but only if the server keeps sending messages. If the server is silent (hasn't finished analysis), the loop exits after the first None return (50ms total).
There is no mechanism to wait for the server to signal it has finished analyzing the file (e.g., waiting for a textDocument/publishDiagnostics notification specifically for the opened URI).
For large files or slow servers, get_diagnostics() may return [] immediately after did_open() because the server hasn't had time to analyze the file.

Code Location

src/cleveragents/lsp/client.py lines 367-390 — get_diagnostics() polling logic

Suggested Fix

After did_open(), wait for a textDocument/publishDiagnostics notification for the specific URI with a configurable timeout (default 30s), rather than using a fixed drain loop.

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: uat-tester

## Summary `LspClient.get_diagnostics()` uses a polling approach with a fixed 200-message drain cap and 50ms timeout per read. For language servers that take longer to analyze files (e.g., Rust Analyzer, TypeScript server on large projects), diagnostics may not have arrived yet when the drain loop exits, causing `get_diagnostics()` to return an empty list even though the server will eventually produce diagnostics. ## Expected Behavior (from spec §LSP Integration — Diagnostics) The spec requires that `lsp/diagnostics` retrieves diagnostics for a file. For this to be reliable, the client must wait for the server to push `textDocument/publishDiagnostics` notifications after `textDocument/didOpen`. ## Actual Behavior In `src/cleveragents/lsp/client.py`, `get_diagnostics()`: ```python def get_diagnostics(self, uri: str) -> list[dict[str, Any]]: # Drain pending messages (capped to prevent infinite loop if # server is flooding notifications). max_drain = 200 for _ in range(max_drain): msg = self._transport.read_message(timeout=0.05) # 50ms timeout if msg is None: break self._handle_notification(msg) return list(self._diagnostics.get(uri, [])) ``` Issues: 1. The 50ms timeout per read means the total wait is at most 200 × 50ms = 10 seconds, but only if the server keeps sending messages. If the server is silent (hasn't finished analysis), the loop exits after the first `None` return (50ms total). 2. There is no mechanism to wait for the server to signal it has finished analyzing the file (e.g., waiting for a `textDocument/publishDiagnostics` notification specifically for the opened URI). 3. For large files or slow servers, `get_diagnostics()` may return `[]` immediately after `did_open()` because the server hasn't had time to analyze the file. ## Code Location - `src/cleveragents/lsp/client.py` lines 367-390 — `get_diagnostics()` polling logic ## Suggested Fix After `did_open()`, wait for a `textDocument/publishDiagnostics` notification for the specific URI with a configurable timeout (default 30s), rather than using a fixed drain loop. --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: uat-tester

HAL9000 added the

labels

2026-04-09 08:39:05 +00:00

HAL9000 added this to the v3.2.0 milestone

2026-04-09 08:46:46 +00:00

HAL9000 commented

2026-04-09 08:49:00 +00:00

Author

Owner

Issue triaged by project owner:

State: Verified
Priority: Medium — The LSP diagnostics polling issue is a reliability concern but not a complete feature gap. The current implementation works for fast language servers; it may miss diagnostics from slow servers. This is a quality improvement, not a blocking bug.
Milestone: v3.6.0 — LSP reliability improvements belong in the same milestone as LSP integration (v3.6.0 Advanced Concepts).
Story Points: 3 — M — Replacing the polling loop with a proper notification-wait mechanism in LspClient.get_diagnostics() is a focused change, estimated 4-8 hours.
MoSCoW: MoSCoW/Should have — The spec requires reliable diagnostics retrieval. The current polling approach is fragile for slow servers. This should be fixed as part of LSP integration but is not blocking if the basic case works.
Parent Epic: Needs linking to LSP Integration Epic

The fix involves replacing the fixed 200-message drain loop with a proper wait-for-notification mechanism that waits for textDocument/publishDiagnostics for the specific URI with a configurable timeout (default 30s).

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

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — The LSP diagnostics polling issue is a reliability concern but not a complete feature gap. The current implementation works for fast language servers; it may miss diagnostics from slow servers. This is a quality improvement, not a blocking bug. - **Milestone**: v3.6.0 — LSP reliability improvements belong in the same milestone as LSP integration (v3.6.0 Advanced Concepts). - **Story Points**: 3 — M — Replacing the polling loop with a proper notification-wait mechanism in `LspClient.get_diagnostics()` is a focused change, estimated 4-8 hours. - **MoSCoW**: MoSCoW/Should have — The spec requires reliable diagnostics retrieval. The current polling approach is fragile for slow servers. This should be fixed as part of LSP integration but is not blocking if the basic case works. - **Parent Epic**: Needs linking to LSP Integration Epic The fix involves replacing the fixed 200-message drain loop with a proper wait-for-notification mechanism that waits for `textDocument/publishDiagnostics` for the specific URI with a configurable timeout (default 30s). --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: project-owner

HAL9000 commented

2026-04-09 08:49:03 +00:00

Author

Owner

Label compliance fix applied:

Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: backlog-groomer

Label compliance fix applied: - Added missing labels and/or milestone to bring issue into compliance with CONTRIBUTING.md --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: backlog-groomer

HAL9000 added

and removed

labels

2026-04-09 08:49:26 +00:00

HAL9000 modified the milestone from v3.2.0 to v3.6.0

2026-04-09 08:50:11 +00:00

HAL9000 added the