@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:

| Command | Description | |---|---| | /lsp | List all configured servers and their states | | /lsp list | Same as /lsp | | /lsp status | Detailed status with failed server errors and active file count | | /lsp install <lang> | Install the LSP server for a language | | /lsp start [name] | Start all servers, or a specific one | | /lsp stop [name] | Stop all servers, or a specific one | | /lsp restart [name] | Restart all servers, or a specific one | | /lsp diagnostics [file] | Show diagnostics for a file or workspace | | /lsp help | Show full help |

Available Languages for /lsp install

| Language | Server | Install Method | |---|---|---| | typescript | typescript-language-server | npm | | python | pyright-langserver | npm | | json | vscode-json-language-server | npm | | html | vscode-html-language-server | npm | | css | vscode-css-language-server | npm | | yaml | yaml-language-server | npm | | shell | bash-language-server | npm | | go | gopls | Go toolchain | | rust | rust-analyzer | Rust toolchain | | ruby | ruby-lsp | RubyGems |

Registered Tools

The plugin registers 5 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.

| Tool | Permission | Description | |---|---|---| | lsp_diagnostics | auto | Get type/lint diagnostics for a file or whole workspace | | lsp_definition | auto | Jump to the definition of a symbol (more precise than grep) | | lsp_completion | auto | Semantic completions for a cursor location, including live editor content when provided | | lsp_rename | confirm | Safe semantic rename across the workspace | | codebase-lsp-search | auto | Fast symbol search via WrongStack's index, with LSP fallback |

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

| Option | Default | Description | |---|---|---| | autoStart | "lazy" | "lazy" = start on first file access; "eager" = all at session start; "never" = manual only | | diagnosticsAfterEdit | "background" | "background" = fetch after edits; "manual" = on request only | | diagnosticsWaitMs | 1500 | Milliseconds to wait after an edit before fetching diagnostics | | severityFilter | ["error","warning"] | Which diagnostic severities to return | | maxDiagnosticsPerFile | 5 | Maximum diagnostics per file | | maxDiagnosticsTotal | 50 | Maximum diagnostics total | | autoDiscover | true | Auto-discover servers on PATH or node_modules/.bin | | logServerOutput | false | Log server stderr to WrongStack log |

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/              — 5 LSP-backed agent tools (diagnostics, definition, completion, 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.