xml-pipeline/docs/lsp-integration.md

# LSP Integration

**Status:** Implemented
**Date:** January 2026

The AgentServer console includes Language Server Protocol (LSP) integration for intelligent
editing of configuration files and AssemblyScript listener source code.

## Overview

LSP integration provides:
- **Autocompletion** — Context-aware suggestions while typing
- **Diagnostics** — Real-time error and warning messages
- **Hover documentation** — Press F1 to see docs for the current symbol
- **Signature help** — Function parameter hints (AssemblyScript only)

## Supported Language Servers

| Server | Purpose | Install |
|--------|---------|---------|
| yaml-language-server | organism.yaml, listener configs | `npm install -g yaml-language-server` |
| asls | AssemblyScript listener source | `npm install -g assemblyscript-lsp` |

## Configuration

LSP is **automatically enabled** when the language server is installed. No configuration needed.

The system detects language servers at startup:
```python
from xml_pipeline.console.lsp import is_lsp_available, is_asls_available

yaml_ok, yaml_reason = is_lsp_available()
# (True, "yaml-language-server available") or (False, "yaml-language-server not found...")

asls_ok, asls_reason = is_asls_available()
# (True, "AssemblyScript LSP available") or (False, "asls not found...")
```

## Editor Usage

### YAML Config Editing

When editing organism.yaml or listener configs via `/config -e`:

| Key | Action |
|-----|--------|
| Ctrl+S | Save and exit |
| Ctrl+Q | Quit without saving |
| F1 | Show hover documentation |
| Ctrl+Space | Trigger completion |

The editor shows `[YAML LSP]` in the header when connected.

### AssemblyScript Editing

When editing `.ts` or `.as` listener source files:

| Key | Action |
|-----|--------|
| Ctrl+S | Save and exit |
| Ctrl+Q | Quit without saving |
| F1 | Show hover documentation |
| Ctrl+Space | Trigger completion |
| Ctrl+P | Show signature help |

The editor shows `[ASLS]` in the header when connected.

## JSON Schema for YAML

The system generates JSON schemas for yaml-language-server validation:

```
~/.xml-pipeline/schemas/
├── organism.schema.json    # Schema for organism.yaml
└── listener.schema.json    # Schema for listener/*.yaml
```

These are automatically generated by `ensure_schemas()` at startup.

### Schema Modeline

YAML files can include a modeline to enable schema validation:

```yaml
# yaml-language-server: $schema=~/.xml-pipeline/schemas/listener.schema.json
name: greeter
description: Greeting agent
handler: handlers.hello.handle_greeting
```

The editor automatically injects this modeline when editing config files.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│  Editor (prompt_toolkit)                                     │
│  ┌─────────────────────────────────────────────────────────┐│
│  │  LSPEditor                                              ││
│  │  - Syntax highlighting (Pygments)                       ││
│  │  - Completion popup                                     ││
│  │  - Diagnostics in status bar                            ││
│  │  - Hover popup on F1                                    ││
│  └─────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  LSP Manager (singleton)                                     │
│  - Manages server lifecycle                                  │
│  - Reference counting for cleanup                            │
│  - Supports multiple servers concurrently                    │
└─────────────────────────────────────────────────────────────┘
                          │
           ┌──────────────┴──────────────┐
           ▼                              ▼
┌─────────────────────┐       ┌─────────────────────┐
│  YAMLLSPClient      │       │  ASLSClient         │
│  (yaml-language-    │       │  (asls)             │
│   server)           │       │                     │
└─────────────────────┘       └─────────────────────┘
```

## API Reference

### LSPEditor

```python
from xml_pipeline.console.editor import LSPEditor

# Edit YAML config
editor = LSPEditor(schema_type="listener", syntax="yaml")
edited_text, saved = await editor.edit(content, title="greeter.yaml")

# Edit AssemblyScript
editor = LSPEditor(syntax="assemblyscript")
edited_text, saved = await editor.edit(source, title="handler.ts")
```

### Helper Functions

```python
from xml_pipeline.console.editor import (
    edit_text_async,
    edit_file_async,
    edit_assemblyscript_source,
    detect_syntax_from_path,
)

# Edit with LSP
await edit_file_async("config/organism.yaml", schema_type="organism")

# Auto-detect syntax from extension
await edit_file_async("listeners/greeter.ts")  # Uses ASLS

# Convenience for AS files
await edit_assemblyscript_source("handler.ts")
```

### LSP Manager

```python
from xml_pipeline.console.lsp import get_lsp_manager, LSPServerType

manager = get_lsp_manager()

# Get YAML client
client = await manager.get_yaml_client()
if client:
    completions = await client.completion(uri, line, col)
    await manager.release_client(LSPServerType.YAML)

# Get ASLS client
client = await manager.get_asls_client()
if client:
    sig_help = await client.signature_help(uri, line, col)
    await manager.release_client(LSPServerType.ASSEMBLYSCRIPT)
```

## Graceful Fallback

If language servers are not installed, the editor still works:
- Syntax highlighting via Pygments (no external dependency)
- No completions or diagnostics
- Header shows no LSP indicator

This allows the system to work on machines without Node.js installed.

## Installation

1. Install Node.js (v16+)
2. Install language servers:
   ```bash
   npm install -g yaml-language-server
   npm install -g assemblyscript-lsp
   ```
3. Restart the console

The system will automatically detect and use the language servers.

## Troubleshooting

### Language server not detected

Check if the binary is in PATH:
```bash
which yaml-language-server
which asls
```

### Editor crashes on startup

Check logs for LSP errors:
```bash
python run_organism.py 2>&1 | grep -i lsp
```

### Completions not working

1. Ensure schema files exist in `~/.xml-pipeline/schemas/`
2. Check that the YAML file has the schema modeline
3. Verify yaml-language-server is installed

---

**v2.1 Feature** — January 2026