Epic: LSP Runtime Implementation — Functional Language Server Lifecycle and Context Enrichment #934

Open
opened 2026-03-14 01:13:31 +00:00 by freemo · 4 comments
Owner

Background and Context

The specification defines LSP integration as a core capability for attaching language intelligence (diagnostics, type info, symbol navigation, completions, references, rename, code actions) to actors and agents (spec §Overview, §Glossary, §LSP Integration, §Architecture).

The current implementation in src/cleveragents/lsp/ (~30% complete) has:

  • LspRegistry (functional — namespaced, thread-safe)
  • LspToolAdapter (generates tool specs but all handlers raise LspNotAvailableError)
  • LspBinding model (data model only, no orchestration)
  • LspRuntime (entirely a stub — all methods raise LspNotAvailableError)
  • LspServer (JSON-RPC over stdin/stdout with initialize/shutdown — basic but functional)

The runtime, tool adapter handlers, auto-context enrichment, and per-node graph binding orchestration are all stubs.

Expected Behavior

The LSP subsystem must manage the full lifecycle of language servers, expose their capabilities as callable tools for actors, and automatically enrich actor context with language intelligence data.

Acceptance Criteria

  • LspRuntime functional: start_server, stop_server, get_diagnostics, get_completions, get_hover, get_references, get_definition, get_rename all operational
  • LSP server lifecycle management: lazy start on first use, workspace mapping, file synchronization
  • LspToolAdapter handlers execute real LSP requests (not LspNotAvailableError)
  • Auto-context enrichment: LSP diagnostics and type annotations injected into ACMS hot context
  • Per-node LSP bindings in actor graphs: actors can bind LSP servers by name, by language, or automatically
  • Different nodes in an actor graph can have different LSP bindings
  • Actor graph node activation starts appropriate LSP servers

Subtasks

  • Implement LspRuntime.start_server with lazy activation and workspace mapping
  • Implement LspRuntime.stop_server with graceful shutdown
  • Implement all LSP capability methods (diagnostics, hover, definition, completions, references, rename, code actions)
  • Wire LspToolAdapter handlers to LspRuntime methods
  • Implement auto-context enrichment: inject LSP diagnostics into ACMS hot context
  • Implement per-node LSP binding orchestration in actor graph activation
  • Implement automatic LSP server selection based on detected resource languages
  • Implement file synchronization between workspace and LSP server
  • Tests (Behave): Add scenarios for LSP server lifecycle
  • Tests (Behave): Add scenarios for tool adapter functionality
  • Tests (Robot): Add integration tests with real LSP servers (e.g., pyright)
  • Verify coverage >=97% via nox -s coverage_report
  • Run nox (all default sessions), fix any errors

Definition of Done

This epic is complete when all child issues are closed AND the LSP subsystem provides functional language intelligence to actors through tools and automatic context enrichment, with real LSP server lifecycle management.

## Background and Context The specification defines LSP integration as a core capability for attaching language intelligence (diagnostics, type info, symbol navigation, completions, references, rename, code actions) to actors and agents (spec §Overview, §Glossary, §LSP Integration, §Architecture). The current implementation in `src/cleveragents/lsp/` (~30% complete) has: - `LspRegistry` (functional — namespaced, thread-safe) - `LspToolAdapter` (generates tool specs but all handlers raise `LspNotAvailableError`) - `LspBinding` model (data model only, no orchestration) - `LspRuntime` (entirely a stub — all methods raise `LspNotAvailableError`) - `LspServer` (JSON-RPC over stdin/stdout with initialize/shutdown — basic but functional) The runtime, tool adapter handlers, auto-context enrichment, and per-node graph binding orchestration are all stubs. ## Expected Behavior The LSP subsystem must manage the full lifecycle of language servers, expose their capabilities as callable tools for actors, and automatically enrich actor context with language intelligence data. ## Acceptance Criteria - [ ] `LspRuntime` functional: `start_server`, `stop_server`, `get_diagnostics`, `get_completions`, `get_hover`, `get_references`, `get_definition`, `get_rename` all operational - [ ] LSP server lifecycle management: lazy start on first use, workspace mapping, file synchronization - [ ] `LspToolAdapter` handlers execute real LSP requests (not `LspNotAvailableError`) - [ ] Auto-context enrichment: LSP diagnostics and type annotations injected into ACMS hot context - [ ] Per-node LSP bindings in actor graphs: actors can bind LSP servers by name, by language, or automatically - [ ] Different nodes in an actor graph can have different LSP bindings - [ ] Actor graph node activation starts appropriate LSP servers ## Subtasks - [ ] Implement `LspRuntime.start_server` with lazy activation and workspace mapping - [ ] Implement `LspRuntime.stop_server` with graceful shutdown - [ ] Implement all LSP capability methods (diagnostics, hover, definition, completions, references, rename, code actions) - [ ] Wire `LspToolAdapter` handlers to `LspRuntime` methods - [ ] Implement auto-context enrichment: inject LSP diagnostics into ACMS hot context - [ ] Implement per-node LSP binding orchestration in actor graph activation - [ ] Implement automatic LSP server selection based on detected resource languages - [ ] Implement file synchronization between workspace and LSP server - [ ] Tests (Behave): Add scenarios for LSP server lifecycle - [ ] Tests (Behave): Add scenarios for tool adapter functionality - [ ] Tests (Robot): Add integration tests with real LSP servers (e.g., pyright) - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This epic is complete when all child issues are closed AND the LSP subsystem provides functional language intelligence to actors through tools and automatic context enrichment, with real LSP server lifecycle management.
freemo added this to the v3.5.0 milestone 2026-03-14 01:15:47 +00:00
Author
Owner

Parent Legendary: cleverthis/cleveragents#3 — Core Functionality

Blocked by:

  • #933 (A2A Protocol) — LSP tool calls route through A2A

Related issues:

  • #935 (ACMS Pipeline) — LSP auto-context enrichment feeds into ACMS hot context
  • #942 (Resource Inheritance) — LSP binding uses resource types for language matching
## Dependency Links **Parent Legendary**: [cleverthis/cleveragents#3 — Core Functionality](https://git.cleverthis.com/cleverthis/cleveragents/issues/3) **Blocked by**: - #933 (A2A Protocol) — LSP tool calls route through A2A **Related issues**: - #935 (ACMS Pipeline) — LSP auto-context enrichment feeds into ACMS hot context - #942 (Resource Inheritance) — LSP binding uses resource types for language matching
freemo self-assigned this 2026-03-14 04:27:20 +00:00
Member

Phase 1 kickoff (agent run):

  • Verified issue is open.
  • Reassigned assignee to brent.edwards per execution request.
  • Transitioned state label to State/In Progress.
  • Created isolated workspace at /tmp/cleveragents-934 and branch feature/934-lsp-runtime-implementation.
  • Read required references: docs/specification.md, CONTRIBUTING.md, docs/timeline.md.

Implementation plan for this pass:

  1. Complete missing functional LSP runtime capability methods (hover, definition, references, rename, code_actions) and lazy-start behavior.
  2. Wire LspToolAdapter runtime handlers for all implemented capabilities.
  3. Add file synchronization support (didChange) in LSP client/runtime path.
  4. Improve per-node LSP binding extraction from actor graph schema (NodeDefinition.lsp_binding) so compilation metadata carries real node bindings.
  5. Add/extend Behave + Robot coverage, then run required nox quality gates and iterate.

I will post detailed implementation and quality results incrementally in follow-up comments.

Phase 1 kickoff (agent run): - Verified issue is open. - Reassigned assignee to `brent.edwards` per execution request. - Transitioned state label to `State/In Progress`. - Created isolated workspace at `/tmp/cleveragents-934` and branch `feature/934-lsp-runtime-implementation`. - Read required references: `docs/specification.md`, `CONTRIBUTING.md`, `docs/timeline.md`. Implementation plan for this pass: 1. Complete missing functional LSP runtime capability methods (`hover`, `definition`, `references`, `rename`, `code_actions`) and lazy-start behavior. 2. Wire `LspToolAdapter` runtime handlers for all implemented capabilities. 3. Add file synchronization support (`didChange`) in LSP client/runtime path. 4. Improve per-node LSP binding extraction from actor graph schema (`NodeDefinition.lsp_binding`) so compilation metadata carries real node bindings. 5. Add/extend Behave + Robot coverage, then run required nox quality gates and iterate. I will post detailed implementation and quality results incrementally in follow-up comments.
freemo self-assigned this 2026-04-02 06:13:56 +00:00
Author
Owner

Label compliance fix applied:

  • Replaced orphaned label State/In Progress with valid label State/In progress
  • Reason: State/In Progress (capital P) is an orphaned label that no longer exists in the repository's label list. The correct label is State/In progress (lowercase p, ID: 1322).

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

Label compliance fix applied: - Replaced orphaned label `State/In Progress` with valid label `State/In progress` - Reason: `State/In Progress` (capital P) is an orphaned label that no longer exists in the repository's label list. The correct label is `State/In progress` (lowercase p, ID: 1322). --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer
Owner

Planning Update — New Implementation Issues Created

This epic previously had only 5 child issues (all TEST-INFRA issues for missing test levels). The following implementation issues have been created to cover the full LSP Runtime implementation:

New Child Issues

Issue Title Dependency
#7427 feat(lsp): implement LspRuntime core — server lifecycle, workspace mapping, file synchronization First — no blockers
#7429 feat(lsp): implement LspRuntime capability methods — diagnostics, hover, definition, completions, references, rename After #7427
#7431 feat(lsp): implement LspToolAdapter handlers and auto-context enrichment via ACMS hot context After #7427, #7429

Implementation Order

#7427 (LspRuntime Core) → #7429 (Capability Methods) → #7431 (Tool Adapter + Context Enrichment)

All 3 issues block this epic (#934). The epic is complete when all child issues are closed AND the LSP subsystem provides functional language intelligence to actors.


Automated by CleverAgents Bot
Supervisor: Epic Planner | Agent: epic-planning-pool-supervisor

## Planning Update — New Implementation Issues Created This epic previously had only 5 child issues (all TEST-INFRA issues for missing test levels). The following implementation issues have been created to cover the full LSP Runtime implementation: ### New Child Issues | Issue | Title | Dependency | |-------|-------|------------| | #7427 | feat(lsp): implement LspRuntime core — server lifecycle, workspace mapping, file synchronization | First — no blockers | | #7429 | feat(lsp): implement LspRuntime capability methods — diagnostics, hover, definition, completions, references, rename | After #7427 | | #7431 | feat(lsp): implement LspToolAdapter handlers and auto-context enrichment via ACMS hot context | After #7427, #7429 | ### Implementation Order ``` #7427 (LspRuntime Core) → #7429 (Capability Methods) → #7431 (Tool Adapter + Context Enrichment) ``` All 3 issues block this epic (#934). The epic is complete when all child issues are closed AND the LSP subsystem provides functional language intelligence to actors. --- **Automated by CleverAgents Bot** Supervisor: Epic Planner | Agent: epic-planning-pool-supervisor
Sign in to join this conversation.
No milestone
No project
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#934
No description provided.