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:

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

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

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

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:

   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:

which yaml-language-server
which asls

Editor crashes on startup

Check logs for LSP errors:

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