python-agent-harness 1.5.5.5__tar.gz → 1.5.5.6__tar.gz

{python_agent_harness-1.5.5.5/python_agent_harness.egg-info → python_agent_harness-1.5.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-agent-harness
-Version: 1.5.5.5
+Version: 1.5.5.6
 Summary: A lightweight, hackable mini-OpenCode written in Python.
 Author-email: Huming Chen <chenhuming@gmail.com>
 License-Expression: MIT
@@ -105,7 +105,7 @@ Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_
 
 - **FSM-driven execution** — explicit `WAIT` / `TOOL` / `TRET` / `SUPERVISE` / `DONE` / `ERRS` / `ABRT` states. Completion supervision nudges the model when it stops early, while failed tool calls are sanitized so they never strand the agent. Transient API failures (`429` / `5xx`) retry with exponential backoff and jitter. Auth-expired status codes (configurable via `AUTH_REFRESH_STATUS_CODES` in `config.py`; defaults to `[401, 502]`) trigger automatic API key re-read from config/env — some API gateways return `502` instead of `401` when the backend auth token has expired. Note: codes in this list are treated as auth-expired exclusively and will not be retried with backoff, so only include codes that are unambiguously auth-related in your environment.
 - **Context management** — CJK-aware token estimation, per-model context windows, and automatic compaction at 70% usage.
-- **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Insert`, `Edit` (including unified diffs), `Write`, `Mkdir`, `Bash`, `Skill`, `Question`, and `PlanExit`. Synchronous tools execute sequentially, but a round made up entirely of read-only tools (`Read`, `Glob`, `Grep`, `Skill`) is dispatched concurrently via a bounded thread pool; asynchronous tools such as `Bash` and `Agent` can run concurrently as well. Results are always delivered in the model's emitted order.
+- **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Insert`, `Edit` (including unified diffs), `Write`, `Mkdir`, `Bash`, `Skill`, `Question`, `LSP`, and `PlanExit`. Synchronous tools execute sequentially, but a round made up entirely of read-only tools (`Read`, `Glob`, `Grep`, `Skill`, `LSP`) is dispatched concurrently via a bounded thread pool; asynchronous tools such as `Bash` and `Agent` can run concurrently as well. Results are always delivered in the model's emitted order.
 - **Plan / Build modes** — plan mode is read-only except for the per-session plan file.
 - **Persistent sessions** — sessions are automatically saved after every response to `~/.local/share/python-agent-harness/sessions/`, with LLM-generated titles and support for `/restore --latest` and `/sessions`.
 - **Focused TUI** — a Rich-based interface with a pinned status bar, Todos panel, inline red/green diff rendering for `Edit` and `Write`, and a `prompt_toolkit` editor with history and completion. `Esc+Enter` submits, `Ctrl-D` quits, and `Ctrl-C` cancels without leaving the application.
@@ -178,6 +178,16 @@ All LLM settings live in a single JSON configuration file. Environment variables
     "context_path": null,
     "skill_path": null
   },
+  "lsp": {
+    "servers": {
+      ".c":   { "command": ["clangd", "--compile-commands-dir=$REPO/build/Linux_x86_64", "--background-index"], "language_id": "c" },
+      ".h":   { "command": ["clangd", "--compile-commands-dir=$REPO/build/Linux_x86_64", "--background-index"], "language_id": "c" },
+      ".cpp": { "command": ["clangd", "--compile-commands-dir=$REPO/build/Linux_x86_64", "--background-index"], "language_id": "cpp" },
+      ".cc":  { "command": ["clangd", "--compile-commands-dir=$REPO/build/Linux_x86_64", "--background-index"], "language_id": "cpp" },
+      ".hpp": { "command": ["clangd", "--compile-commands-dir=$REPO/build/Linux_x86_64", "--background-index"], "language_id": "cpp" },
+      ".cxx": { "command": ["clangd", "--compile-commands-dir=$REPO/build/Linux_x86_64", "--background-index"], "language_id": "cpp" }
+    }
+  },
   "mcp": {
     "servers": {
       "example": {
@@ -206,6 +216,7 @@ All LLM settings live in a single JSON configuration file. Environment variables
 - **`subagent_llm`** — LLM configuration for `Agent` tool requests. Unset values inherit from the main `llm`. Set `profile` to reuse a profile from `models`. Precedence is: profile settings > explicit `subagent_llm` settings > main `llm` > environment variables.
 - **`default_agent`** — name of the agent to use at session start (instead of the built-in `agent.md`). The agent must exist as a `.md` file in the `prompts/agents/` directory. When unset or `null`, the built-in default agent is used. Use `/agent default` in the TUI to switch back to the built-in at any time.
 - **`paths.context_path` / `paths.skill_path`** — locations from which to load context files and skills. When unset, the project-local `<project>/contexts` and `<project>/skills` directories are used.
+- **`lsp.servers`** — optional per-extension LSP server overrides for the `LSP` code-intelligence tool. Keys are file extensions (e.g. `.py`, `.cpp`); each value has a `command` (the server argv) and an optional `language_id` (defaults to the extension without its dot). These layer on top of the built-in `DEFAULT_SERVERS` table in `lsp/manager.py`; an entry for an existing extension replaces its default. The server binary must be on `PATH`.
 - **`mcp.servers`** — MCP server configuration. Requires the `[mcp]` extra. Each server supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, and `enabled`.
 - **Configuration precedence** — code defaults < config file < `OPENAI_*` environment variables. Sub-agent settings also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`).
 - **Custom config** — use `--config PATH` or `PYTHON_AGENT_HARNESS_CONFIG`.
@@ -290,6 +301,7 @@ python_agent_harness/
 ├── cli.py             # CLI entry points
 ├── tui/               # Rich + prompt_toolkit TUI (package)
 ├── diffrender.py      # Unified diff generation + Rich rendering
+├── lsp/               # Built-in LSP client
 ├── mcp/               # Optional MCP client
 └── tools/             # Tool implementations + registry
 ```

{python_agent_harness-1.5.5.5 → python_agent_harness-1.5.5.6}/README.md

@@ -71,7 +71,7 @@ Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_
 
 - **FSM-driven execution** — explicit `WAIT` / `TOOL` / `TRET` / `SUPERVISE` / `DONE` / `ERRS` / `ABRT` states. Completion supervision nudges the model when it stops early, while failed tool calls are sanitized so they never strand the agent. Transient API failures (`429` / `5xx`) retry with exponential backoff and jitter. Auth-expired status codes (configurable via `AUTH_REFRESH_STATUS_CODES` in `config.py`; defaults to `[401, 502]`) trigger automatic API key re-read from config/env — some API gateways return `502` instead of `401` when the backend auth token has expired. Note: codes in this list are treated as auth-expired exclusively and will not be retried with backoff, so only include codes that are unambiguously auth-related in your environment.
 - **Context management** — CJK-aware token estimation, per-model context windows, and automatic compaction at 70% usage.
-- **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Insert`, `Edit` (including unified diffs), `Write`, `Mkdir`, `Bash`, `Skill`, `Question`, and `PlanExit`. Synchronous tools execute sequentially, but a round made up entirely of read-only tools (`Read`, `Glob`, `Grep`, `Skill`) is dispatched concurrently via a bounded thread pool; asynchronous tools such as `Bash` and `Agent` can run concurrently as well. Results are always delivered in the model's emitted order.
+- **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Insert`, `Edit` (including unified diffs), `Write`, `Mkdir`, `Bash`, `Skill`, `Question`, `LSP`, and `PlanExit`. Synchronous tools execute sequentially, but a round made up entirely of read-only tools (`Read`, `Glob`, `Grep`, `Skill`, `LSP`) is dispatched concurrently via a bounded thread pool; asynchronous tools such as `Bash` and `Agent` can run concurrently as well. Results are always delivered in the model's emitted order.
 - **Plan / Build modes** — plan mode is read-only except for the per-session plan file.
 - **Persistent sessions** — sessions are automatically saved after every response to `~/.local/share/python-agent-harness/sessions/`, with LLM-generated titles and support for `/restore --latest` and `/sessions`.
 - **Focused TUI** — a Rich-based interface with a pinned status bar, Todos panel, inline red/green diff rendering for `Edit` and `Write`, and a `prompt_toolkit` editor with history and completion. `Esc+Enter` submits, `Ctrl-D` quits, and `Ctrl-C` cancels without leaving the application.
@@ -144,6 +144,16 @@ All LLM settings live in a single JSON configuration file. Environment variables
     "context_path": null,
     "skill_path": null
   },
+  "lsp": {
+    "servers": {
+      ".c":   { "command": ["clangd", "--compile-commands-dir=$REPO/build/Linux_x86_64", "--background-index"], "language_id": "c" },
+      ".h":   { "command": ["clangd", "--compile-commands-dir=$REPO/build/Linux_x86_64", "--background-index"], "language_id": "c" },
+      ".cpp": { "command": ["clangd", "--compile-commands-dir=$REPO/build/Linux_x86_64", "--background-index"], "language_id": "cpp" },
+      ".cc":  { "command": ["clangd", "--compile-commands-dir=$REPO/build/Linux_x86_64", "--background-index"], "language_id": "cpp" },
+      ".hpp": { "command": ["clangd", "--compile-commands-dir=$REPO/build/Linux_x86_64", "--background-index"], "language_id": "cpp" },
+      ".cxx": { "command": ["clangd", "--compile-commands-dir=$REPO/build/Linux_x86_64", "--background-index"], "language_id": "cpp" }
+    }
+  },
   "mcp": {
     "servers": {
       "example": {
@@ -172,6 +182,7 @@ All LLM settings live in a single JSON configuration file. Environment variables
 - **`subagent_llm`** — LLM configuration for `Agent` tool requests. Unset values inherit from the main `llm`. Set `profile` to reuse a profile from `models`. Precedence is: profile settings > explicit `subagent_llm` settings > main `llm` > environment variables.
 - **`default_agent`** — name of the agent to use at session start (instead of the built-in `agent.md`). The agent must exist as a `.md` file in the `prompts/agents/` directory. When unset or `null`, the built-in default agent is used. Use `/agent default` in the TUI to switch back to the built-in at any time.
 - **`paths.context_path` / `paths.skill_path`** — locations from which to load context files and skills. When unset, the project-local `<project>/contexts` and `<project>/skills` directories are used.
+- **`lsp.servers`** — optional per-extension LSP server overrides for the `LSP` code-intelligence tool. Keys are file extensions (e.g. `.py`, `.cpp`); each value has a `command` (the server argv) and an optional `language_id` (defaults to the extension without its dot). These layer on top of the built-in `DEFAULT_SERVERS` table in `lsp/manager.py`; an entry for an existing extension replaces its default. The server binary must be on `PATH`.
 - **`mcp.servers`** — MCP server configuration. Requires the `[mcp]` extra. Each server supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, and `enabled`.
 - **Configuration precedence** — code defaults < config file < `OPENAI_*` environment variables. Sub-agent settings also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`).
 - **Custom config** — use `--config PATH` or `PYTHON_AGENT_HARNESS_CONFIG`.
@@ -256,6 +267,7 @@ python_agent_harness/
 ├── cli.py             # CLI entry points
 ├── tui/               # Rich + prompt_toolkit TUI (package)
 ├── diffrender.py      # Unified diff generation + Rich rendering
+├── lsp/               # Built-in LSP client
 ├── mcp/               # Optional MCP client
 └── tools/             # Tool implementations + registry
 ```

{python_agent_harness-1.5.5.5 → python_agent_harness-1.5.5.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-agent-harness"
-version = "1.5.5.5"
+version = "1.5.5.6"
 description = "A lightweight, hackable mini-OpenCode written in Python."
 authors = [
     {name = "Huming Chen", email = "chenhuming@gmail.com"}

{python_agent_harness-1.5.5.5 → python_agent_harness-1.5.5.6}/python_agent_harness/__init__.py

@@ -1,15 +1,21 @@
 """python-agent-harness: a Python port of the gptel-agent-harness."""
 
+from .client import Client, LLMClient
+from .lsp.config import LSPConfig, LSPServerConfig
 from .mcp.config import MCPConfig, MCPServerConfig
 from .mcp.manager import MCPManager
 from .models import AgentMode, Message, ToolCall, ToolSpec
 from .session import Session
 
-__version__ = "1.5.5.5"
+__version__ = "1.5.5.6"
 
 __all__ = [
+    "Client",
+    "LLMClient",
     "Session",
     "AgentMode",
+    "LSPConfig",
+    "LSPServerConfig",
     "MCPConfig",
     "MCPManager",
     "MCPServerConfig",

{python_agent_harness-1.5.5.5 → python_agent_harness-1.5.5.6}/python_agent_harness/agent.py

@@ -38,6 +38,7 @@ from __future__ import annotations
 from typing import Any, Protocol
 
 from . import config
+from .client import LLMClient
 from .context_manager import ContextManager
 from .models import Message, ToolCall
 from .token_estimator import context_window_for, estimate_payload_tokens
@@ -74,7 +75,7 @@ class AgentLoop:
         top_level: bool = True,
         system: str | None = None,
         max_rounds: int = 60,
-        client: Any | None = None,
+        client: LLMClient | None = None,
     ) -> None:
         self.session = session
         self.messages: list[Message] = messages if messages is not None else []
@@ -631,7 +632,7 @@ def run_agent_loop(
     top_level: bool = True,
     system: str | None = None,
     max_rounds: int = 60,
-    client: Any | None = None,
+    client: LLMClient | None = None,
 ) -> str | None:
     """Convenience wrapper running a full agent run (FSM).
 

{python_agent_harness-1.5.5.5 → python_agent_harness-1.5.5.6}/python_agent_harness/cli.py

@@ -41,6 +41,11 @@ def make_session(
     settings = config.load_llm_config(config_path)
     paths = config.load_paths_config(config_path)
     mcp_config = config.load_mcp_config(config_path)
+    # Validate lsp.servers eagerly so a malformed override fails fast at
+    # session start (with a clear message) instead of poisoning the first
+    # LSP tool call mid-session.  The LSP manager re-reads it lazily via
+    # config_path; this call only surfaces config errors early.
+    config.load_lsp_config(config_path)
     model = model or settings["model"]
     # resolve sub-agent overrides against the EFFECTIVE main settings
     # (so a CLI/caller model override is inherited too when the
@@ -243,6 +248,14 @@ def cmd_config(args: argparse.Namespace) -> int:
             print(f"  {pattern}: {size}")
     else:
         print("context_windows: (none configured — built-in table in config.py applies)")
+    # Show LSP server overrides (per-extension, layered over the built-ins)
+    lsp_config = config.load_lsp_config(args.path)
+    if lsp_config.servers:
+        print("lsp servers:")
+        for ext, server in sorted(lsp_config.servers.items()):
+            print(f"  {ext}: language_id={server.language_id}, command={' '.join(server.command)}")
+    else:
+        print("lsp servers: (none configured — built-in DEFAULT_SERVERS in lsp/manager.py applies)")
     # Show default agent
     default_agent = config.load_default_agent(args.path)
     print(f"default_agent: {default_agent or '(default: agent.md)'}")

{python_agent_harness-1.5.5.5 → python_agent_harness-1.5.5.6}/python_agent_harness/client.py

@@ -19,13 +19,82 @@ import time
 import uuid
 from collections.abc import Callable, Iterator
 from pathlib import Path
-from typing import Any
+from typing import Any, Protocol, runtime_checkable
 
 import httpx
 
 from . import config
 from .models import Message, ToolCall, ToolSpec, Usage
 
+
+@runtime_checkable
+class LLMClient(Protocol):
+    """Structural interface the agent loop needs from an LLM backend.
+
+    ``AgentLoop`` and ``Session`` depend only on this surface, never on
+    the concrete ``Client`` transport.  Anything providing these
+    members — the OpenAI-compatible ``Client`` below, a fake/replay
+    double in tests, or an alternative provider — can drive the FSM.
+
+    The members mirror how the agent consumes a client today:
+
+    - ``chat`` / ``chat_sync`` — the two request entry points (streaming
+      turns and one-shot compaction/title/summary calls).
+    - ``clone`` — a fresh, state-isolated copy for a concurrent
+      sub-agent (pools and the abort flag must never be shared).
+    - ``abort`` / ``close`` — cancel an in-flight request / release the
+      pool.
+    - ``set_timeout`` — apply a new request timeout (``/model`` switch).
+    - ``base_url`` / ``api_key`` / ``model`` / ``timeout`` — connection
+      settings the session reads and rewrites on a profile switch.
+    - ``context_window`` — the model's window (config-aware), read by
+      the context manager for compaction decisions.
+    - ``log_path`` — the shared LLM log file, inherited by clones.
+    """
+
+    base_url: str
+    api_key: str | None
+    model: str
+    timeout: float
+    log_path: Path | None
+
+    @property
+    def context_window(self) -> int: ...
+
+    def chat(
+        self,
+        messages: list[Message],
+        tools: list[ToolSpec] | None = ...,
+        system: str | None = ...,
+        temperature: float | None = ...,
+        max_tokens: int | None = ...,
+        reasoning_effort: str | None = ...,
+        on_delta: Callable[[str], None] | None = ...,
+        on_tool_call: Callable[[str, str, str], None] | None = ...,
+        stream: bool = ...,
+        cancel_check: Callable[[], bool] | None = ...,
+        on_retry: Callable[[], None] | None = ...,
+    ) -> tuple[Message, Usage]: ...
+
+    def chat_sync(
+        self,
+        messages: list[Message],
+        system: str | None = ...,
+        temperature: float | None = ...,
+        max_tokens: int | None = ...,
+        reasoning_effort: str | None = ...,
+        cancel_check: Callable[[], bool] | None = ...,
+    ) -> tuple[Message, Usage]: ...
+
+    def clone(self) -> LLMClient: ...
+
+    def abort(self) -> None: ...
+
+    def close(self) -> None: ...
+
+    def set_timeout(self, timeout: float) -> None: ...
+
+
 # serializes appends to the shared LLM log file: concurrent sub-agents
 # (each with its own client but ONE shared log_path, see Client.clone)
 # finish their interactions in parallel, and interleaved write() calls

{python_agent_harness-1.5.5.5 → python_agent_harness-1.5.5.6}/python_agent_harness/config.py

@@ -7,6 +7,7 @@ import os
 import sys
 from pathlib import Path
 
+from .lsp.config import LSPConfig
 from .mcp.config import MCPConfig
 
 # ---- context management -------------------------------------------------
@@ -98,6 +99,7 @@ DEFAULT_TOOLS: list[str] = [
     "Bash",
     "Skill",
     "Question",
+    "LSP",
 ]
 
 # ---- tool output limits --------------------------------------------------------
@@ -255,6 +257,15 @@ CONFIG_TEMPLATE = """\
     "context_path": null,
     "skill_path": null
   }},
+  "lsp": {{
+    "_comment": "Optional per-extension LSP server overrides. Keys are file extensions (e.g. '.py', '.cpp'); 'command' is the server argv; 'language_id' defaults to the extension without the dot. These override the built-in DEFAULT_SERVERS table. Remove this section to use only the built-ins. The server binary must be on PATH. The '.example' entry below is inert (no such extension) — copy it to a real extension like '.cpp' to activate.",
+    "servers": {{
+      ".example": {{
+        "command": ["clangd", "--background-index", "--clang-tidy"],
+        "language_id": "cpp"
+      }}
+    }}
+  }},
   "mcp": {{
     "_comment": "Optional MCP servers (requires: pip install -e '.[mcp]'). Each server's tools become agent tools named mcp__<server>__<tool>. Transports: stdio (spawn command+args, pass through env var names), streamable-http / sse (connect to url, optional headers). 'parallel: true' marks read-only servers whose tools may run concurrently; default is serial. 'timeout' bounds connects, discovery and calls (seconds).",
     "servers": {{
@@ -446,6 +457,31 @@ def load_mcp_config(path: str | os.PathLike | None = None) -> MCPConfig:
     return MCPConfig.from_dict(section.get("servers"))
 
 
+def load_lsp_config(path: str | os.PathLike | None = None) -> LSPConfig:
+    """Load per-extension LSP server overrides from the config file.
+
+    Reads the optional ``lsp.servers`` object (keyed by file extension,
+    e.g. ``".py"``) and returns an ``LSPConfig`` (empty when the file
+    has no ``lsp`` section or no servers). These entries layer on top of
+    the built-in ``DEFAULT_SERVERS`` table in ``lsp/manager.py``.
+
+    Malformed entries raise ValueError so config errors surface at
+    session start rather than the first LSP call.
+    """
+    data = _read_config(path)
+    section = data.get("lsp") or {}
+    if not isinstance(section, dict):
+        raise ValueError(f"config file {_config_path(path)}: lsp must be an object")
+    servers = section.get("servers") or {}
+    if not isinstance(servers, dict):
+        raise ValueError(f"config file {_config_path(path)}: lsp.servers must be an object")
+    try:
+        return LSPConfig.from_dict(servers)
+    except ValueError as e:
+        # Re-raise with the config-file path for a clearer message.
+        raise ValueError(f"config file {_config_path(path)}: {e}") from e
+
+
 def load_models_config(path: str | os.PathLike | None = None) -> dict[str, dict]:
     """Load named LLM profiles from the config file's ``models`` object.
 

python_agent_harness-1.5.5.6/python_agent_harness/lsp/__init__.py

@@ -0,0 +1,14 @@
+"""Minimal built-in LSP client used by python-agent-harness."""
+
+from .client import LSPClient, LSPError
+from .config import LSPConfig, LSPServerConfig
+from .manager import get_client, shutdown_all
+
+__all__ = [
+    "LSPClient",
+    "LSPConfig",
+    "LSPError",
+    "LSPServerConfig",
+    "get_client",
+    "shutdown_all",
+]

python_agent_harness-1.5.5.6/python_agent_harness/lsp/client.py

@@ -0,0 +1,314 @@
+"""Small, dependency-free LSP/JSON-RPC client used by the agent harness.
+
+This intentionally implements only the transport/lifecycle pieces needed by the
+agent-facing LSP tool. It is synchronous at the public boundary because the
+harness' Tool API is synchronous; a reader thread keeps server messages flowing.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import queue
+import subprocess
+import threading
+from pathlib import Path
+from typing import Any
+
+
+class LSPError(RuntimeError):
+    pass
+
+
+class LSPClient:
+    def __init__(self, command: list[str], root: str, language_id: str, timeout: float = 30.0):
+        self.command = command
+        self.root = os.path.realpath(root)
+        self.language_id = language_id
+        self.timeout = timeout
+        self.proc: subprocess.Popen[bytes] | None = None
+        self._reader: threading.Thread | None = None
+        self._write_lock = threading.Lock()
+        self._state_lock = threading.Lock()
+        self._next_id = 1
+        self._pending: dict[int, queue.Queue] = {}
+        self._opened: dict[str, int] = {}
+        self._texts: dict[str, str] = {}
+        self._diagnostics: dict[str, list[dict[str, Any]]] = {}
+        self._capabilities: dict[str, Any] = {}
+        self.position_encoding = "utf-16"
+        self._closed = False
+
+    @property
+    def alive(self) -> bool:
+        return self.proc is not None and self.proc.poll() is None and not self._closed
+
+    def start(self) -> None:
+        if self.alive:
+            return
+        self._closed = False
+        try:
+            self.proc = subprocess.Popen(
+                self.command,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL,
+                cwd=self.root,
+                bufsize=0,
+            )
+        except OSError as e:
+            raise LSPError(f"failed to start LSP server {' '.join(self.command)!r}: {e}") from e
+        self._reader = threading.Thread(
+            target=self._read_loop, daemon=True, name=f"lsp-reader:{self.command[0]}"
+        )
+        self._reader.start()
+        try:
+            result = self.request(
+                "initialize",
+                {
+                    "processId": os.getpid(),
+                    "rootUri": Path(self.root).as_uri(),
+                    "workspaceFolders": [
+                        {"uri": Path(self.root).as_uri(), "name": Path(self.root).name}
+                    ],
+                    "capabilities": {
+                        "general": {"positionEncodings": ["utf-16", "utf-8"]},
+                        "workspace": {
+                            "workspaceFolders": True,
+                            "symbol": {"dynamicRegistration": False},
+                        },
+                        "textDocument": {
+                            "definition": {"linkSupport": True},
+                            "references": {},
+                            "hover": {"contentFormat": ["markdown", "plaintext"]},
+                            "documentSymbol": {"hierarchicalDocumentSymbolSupport": True},
+                            "implementation": {"linkSupport": True},
+                            "callHierarchy": {"dynamicRegistration": False},
+                        },
+                    },
+                    "trace": "off",
+                },
+            )
+            self._capabilities = result.get("capabilities", {}) if isinstance(result, dict) else {}
+            encoding = self._capabilities.get("positionEncoding")
+            if encoding in {"utf-8", "utf-16", "utf-32"}:
+                self.position_encoding = encoding
+            self.notify("initialized", {})
+        except Exception:
+            self.close()
+            raise
+
+    def request(self, method: str, params: Any = None) -> Any:
+        self.start_if_needed()
+        with self._state_lock:
+            request_id = self._next_id
+            self._next_id += 1
+            waiter: queue.Queue = queue.Queue(maxsize=1)
+            self._pending[request_id] = waiter
+        message: dict[str, Any] = {"jsonrpc": "2.0", "id": request_id, "method": method}
+        if params is not None:
+            message["params"] = params
+        try:
+            self._send(message)
+            kind, value = waiter.get(timeout=self.timeout)
+        except queue.Empty as e:
+            with self._state_lock:
+                self._pending.pop(request_id, None)
+            raise LSPError(f"LSP request timed out: {method}") from e
+        except BaseException:
+            # _send() may raise (server down / write failure); drop the
+            # now-orphaned pending entry so it does not leak forever.
+            with self._state_lock:
+                self._pending.pop(request_id, None)
+            raise
+        if kind == "error":
+            code = value.get("code") if isinstance(value, dict) else None
+            msg = (
+                value.get("message", "unknown LSP error") if isinstance(value, dict) else str(value)
+            )
+            raise LSPError(f"LSP {method} failed ({code}): {msg}")
+        return value
+
+    def notify(self, method: str, params: Any = None) -> None:
+        self.start_if_needed()
+        message: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+        if params is not None:
+            message["params"] = params
+        self._send(message)
+
+    def start_if_needed(self) -> None:
+        if not self.alive:
+            self.start()
+
+    def open_document(self, uri: str, text: str) -> None:
+        self.start_if_needed()
+        # Decide which notification to send while holding _state_lock, but
+        # send it AFTER releasing the lock: notify()->_send() does a blocking
+        # write on the server's stdin pipe, and holding _state_lock across that
+        # write can deadlock the reader thread (which needs _state_lock to
+        # deliver responses/diagnostics) if the pipe buffer fills.
+        with self._state_lock:
+            version = self._opened.get(uri, 0)
+            if version:
+                if self._texts.get(uri) == text:
+                    return
+                version += 1
+                self._opened[uri] = version
+                self._texts[uri] = text
+                method = "textDocument/didChange"
+                params: dict[str, Any] = {
+                    "textDocument": {"uri": uri, "version": version},
+                    "contentChanges": [{"text": text}],
+                }
+            else:
+                self._opened[uri] = 1
+                self._texts[uri] = text
+                method = "textDocument/didOpen"
+                params = {
+                    "textDocument": {
+                        "uri": uri,
+                        "languageId": self.language_id,
+                        "version": 1,
+                        "text": text,
+                    }
+                }
+        self.notify(method, params)
+
+    def close_document(self, uri: str) -> None:
+        with self._state_lock:
+            if uri not in self._opened:
+                return
+            self._opened.pop(uri, None)
+            self._texts.pop(uri, None)
+        if self.alive:
+            self.notify("textDocument/didClose", {"textDocument": {"uri": uri}})
+
+    def diagnostics(self, uri: str) -> list[dict[str, Any]]:
+        with self._state_lock:
+            return list(self._diagnostics.get(uri, []))
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        proc = self.proc
+        was_alive = proc is not None and proc.poll() is None
+        if was_alive:
+            with contextlib.suppress(Exception):
+                self.request("shutdown", None)
+            with contextlib.suppress(Exception):
+                self.notify("exit", None)
+        self._closed = True
+        proc = self.proc
+        if proc is not None and proc.poll() is None:
+            with contextlib.suppress(Exception):
+                proc.terminate()
+                proc.wait(timeout=2)
+            with contextlib.suppress(Exception):
+                proc.kill()
+        # Close the pipe file objects so their file descriptors are
+        # released (subprocess does not close them on terminate/kill —
+        # leaving them open leaks fds and emits ResourceWarning).
+        if proc is not None:
+            for stream in (proc.stdin, proc.stdout):
+                if stream is not None:
+                    with contextlib.suppress(Exception):
+                        stream.close()
+        with self._state_lock:
+            with contextlib.suppress(queue.Full):
+                for waiter in self._pending.values():
+                    waiter.put_nowait(("error", {"message": "LSP client closed"}))
+            self._pending.clear()
+            self._opened.clear()
+            self._texts.clear()
+
+    def _send(self, message: dict[str, Any]) -> None:
+        data = json.dumps(message, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+        packet = b"Content-Length: " + str(len(data)).encode("ascii") + b"\r\n\r\n" + data
+        proc = self.proc
+        if proc is None or proc.stdin is None or proc.poll() is not None:
+            raise LSPError("LSP server is not running")
+        with self._write_lock:
+            try:
+                proc.stdin.write(packet)
+                proc.stdin.flush()
+            except OSError as e:
+                raise LSPError(f"failed writing to LSP server: {e}") from e
+
+    def _read_loop(self) -> None:
+        try:
+            proc = self.proc
+            if proc is None or proc.stdout is None:
+                return
+            stream = proc.stdout
+            while not self._closed:
+                headers: dict[str, str] = {}
+                while True:
+                    line = stream.readline()
+                    if not line:
+                        return
+                    line = line.rstrip(b"\r\n")
+                    if not line:
+                        break
+                    if b":" in line:
+                        key, value = line.split(b":", 1)
+                        headers[key.decode("ascii", "replace").lower()] = value.strip().decode(
+                            "ascii", "replace"
+                        )
+                try:
+                    length = int(headers.get("content-length", "0"))
+                except ValueError:
+                    continue
+                payload = stream.read(length)
+                if len(payload) != length:
+                    return
+                try:
+                    message = json.loads(payload.decode("utf-8"))
+                except (UnicodeDecodeError, json.JSONDecodeError):
+                    continue
+                self._handle_message(message)
+        finally:
+            with self._state_lock:
+                pending = list(self._pending.values())
+                self._pending.clear()
+            with contextlib.suppress(queue.Full):
+                for waiter in pending:
+                    waiter.put_nowait(("error", {"message": "LSP server exited"}))
+
+    def _handle_message(self, message: dict[str, Any]) -> None:
+        if "id" in message and ("result" in message or "error" in message):
+            request_id = message.get("id")
+            if isinstance(request_id, int):
+                with self._state_lock:
+                    waiter = self._pending.pop(request_id, None)
+                if waiter is not None:
+                    waiter.put(
+                        ("error", message["error"])
+                        if "error" in message
+                        else ("result", message.get("result"))
+                    )
+            return
+
+        method = message.get("method")
+        params = message.get("params")
+        if method == "textDocument/publishDiagnostics" and isinstance(params, dict):
+            uri = params.get("uri")
+            if isinstance(uri, str):
+                with self._state_lock:
+                    self._diagnostics[uri] = params.get("diagnostics", []) or []
+            return
+
+        # Servers may send requests/notifications to the client. Respond to
+        # common client-side requests so a server does not stall waiting for
+        # configuration/progress/UI handling that the coding agent does not need.
+        if "id" in message and isinstance(message.get("id"), int):
+            method = str(method or "")
+            if method == "workspace/configuration":
+                items = params if isinstance(params, list) else []
+                result = [None for _ in items]
+            elif method == "workspace/applyEdit":
+                result = {"applied": False}
+            else:
+                result = None
+            with contextlib.suppress(LSPError):
+                self._send({"jsonrpc": "2.0", "id": message["id"], "result": result})