@wrongstack/plug-lsp

Language Server Protocol (LSP) integration for WrongStack. Provides a unified /lsp command to install, run, and manage LSP servers, plus 4 LSP-backed tools for the agent (diagnostics, definition, rename, codebase search).

Quick Start

1. Enable the plugin

Add to your WrongStack config (~/.config/wrongstack/config.json or project .wrongstack/config.json):

{
  "features": { "plugins": true },
  "plugins": ["@wrongstack/plug-lsp"]
}

2. Install a language server

/lsp install typescript
/lsp install python
/lsp install go

3. Add to config and start

After installation, add the server to your config:

{
  "extensions": {
    "@wrongstack/plug-lsp": {
      "servers": {
        "typescript": {
          "command": "typescript-language-server",
          "args": ["--stdio"],
          "languages": ["typescript", "typescriptreact", "javascript", "javascriptreact"],
          "rootPatterns": ["tsconfig.json"]
        }
      }
    }
  }
}

Then restart your WrongStack session and run:

/lsp start typescript

/lsp Command

The primary interface for all LSP operations:

Available Languages for /lsp install

Registered Tools

The plugin registers 4 tools into WrongStack's tool system. These are kept because LSP provides genuinely unique data or capability the agent cannot replicate with basic tools (read, grep, edit) at comparable cost.

The following LSP tools are intentionally excluded: lsp_references (returns positions the agent still has to read), lsp_hover (usually confirms what reading the definition already showed), lsp_symbols (a symbol tree is less useful than reading the file), and lsp_code_actions (high noise-to-signal in well-maintained codebases).

Positions use 1-based line numbers and 1-based UTF-8 byte columns — matching WrongStack's grep tool convention, not LSP's 0-based UTF-16 code units.

Configuration Reference

Full configuration options under extensions["@wrongstack/plug-lsp"]:

{
  "extensions": {
    "@wrongstack/plug-lsp": {
      "autoStart": "lazy",
      "diagnosticsAfterEdit": "background",
      "diagnosticsWaitMs": 1500,
      "severityFilter": ["error", "warning"],
      "maxDiagnosticsPerFile": 5,
      "maxDiagnosticsTotal": 50,
      "autoDiscover": true,
      "logServerOutput": false,
      "servers": {
        "typescript": {
          "command": "typescript-language-server",
          "args": ["--stdio"],
          "languages": ["typescript", "typescriptreact"],
          "rootPatterns": ["tsconfig.json"],
          "initializationOptions": {},
          "settings": {},
          "startupTimeoutMs": 15000,
          "enabled": true
        }
      }
    }
  }
}

Options

Auto-Discovery

With autoDiscover: true (the default), the plugin searches for servers in:

1. PATH — any command on the system PATH is used
2. node_modules/.bin — npm-installed binaries in the project

This means a minimal config is often sufficient:

{
  "features": { "plugins": true },
  "plugins": ["@wrongstack/plug-lsp"]
}

If typescript-language-server is in your project's node_modules/.bin, it is automatically discovered and started on first file access.

Server Lifecycle

Each server runs as a separate child process communicating via JSON-RPC over stdio. The plugin handles:

• Initialization handshake — sends initialize → waits for InitializeResult → sends initialized
• Document tracking — sends textDocument/didOpen on first read, textDocument/didChange after edits
• Crash recovery — 3 restart attempts with exponential backoff (1s, 4s, 16s)
• Graceful shutdown — sends shutdown then exit on session end

States: disabled → starting → initializing → ready → shutting_down → exited

Custom Server Configuration

For languages not in the preset list, add manually to your config:

"servers": {
  "myserver": {
    "command": "my-language-server",
    "args": ["--stdio"],
    "languages": ["mylang"],
    "rootPatterns": ["mylang.config"],
    "startupTimeoutMs": 20000
  }
}

CLI Setup Command

For CI/CD or scripted installation, use the setup CLI directly:

# Install all preset servers (npm-based only)
pnpm --filter @wrongstack/plug-lsp setup -- --cwd /path/to/project

# Install specific servers
pnpm --filter @wrongstack/plug-lsp setup -- --cwd . --languages typescript,python,go

# Dry run
pnpm --filter @wrongstack/plug-lsp setup -- --dry-run --languages typescript

Troubleshooting

Server shows as "failed": Check the server binary is on PATH and starts correctly. Run /lsp status to see the error message from the server's stderr.

No diagnostics: Open the file first (LSP servers report diagnostics for open files). Run /lsp diagnostics <file> after reading the file.

Wrong language detected: Set the languages array explicitly in the server config to include the language ID for your file (e.g., "python" for Python files).

Architecture

packages/plug-lsp/src/
├── slash-commands/
│   ├── lsp.ts          — unified /lsp command dispatcher
│   ├── install.ts       — language server installation logic
│   ├── list/start/stop/restart/diagnostics.ts — individual commands
├── server/
│   ├── lsp-server.ts   — per-server LSP client (one process per server)
│   ├── connection.ts    — JSON-RPC 2.0 over stdio transport
│   └── lifecycle.ts     — state machine for server lifecycle
├── tools/              — 4 LSP-backed agent tools (diagnostics, definition, rename, codebase-search)
├── registry.ts         — manages all server instances
├── document-tracker.ts — tracks open/edited files across sessions
├── auto-discover.ts    — PATH and node_modules discovery
└── presets.ts          — built-in server configurations

Plugin Command Names

The plugin registers slash commands with the @wrongstack/plug-lsp namespace:

• /@wrongstack/plug-lsp:list
• /@wrongstack/plug-lsp:start
• /@wrongstack/plug-lsp:stop
• /@wrongstack/plug-lsp:restart
• /@wrongstack/plug-lsp:diagnostics

These are also available as the short form /lsp, /lsp list, etc.