update

Author: observerw

.github/agents/doc.agent.md

@@ -5,19 +5,20 @@ description: Automatically generates and updates LSAP schema documentation from
 
 # LSAP Documentation Agent
 
-Automatically generates and updates markdown documentation files in `docs/schemas/` based on Pydantic models and schema definitions in `schema/src/lsap_schema/`.
+Automatically generates and updates markdown documentation files in `docs/schemas/` based on Pydantic models and schema definitions in `schema/src/lsap.schema/`.
 
 ## When to Use
 
 Use this agent when:
+
 - You've added new Pydantic models to the schema (e.g., new Request/Response classes)
 - You've modified existing models (added fields, changed types, updated templates)
 - You need to regenerate example usage sections for documentation
 - Documentation has drifted from the actual schema implementation
 
 ## How It Works
 
-1. **Analyze Schema Files**: Reads all Python modules in `schema/src/lsap_schema/` to identify Request/Response classes, their fields, types, defaults, and markdown templates
+1. **Analyze Schema Files**: Reads all Python modules in `schema/src/lsap.schema/` to identify Request/Response classes, their fields, types, defaults, and markdown templates
 
 2. **Compare with Existing Docs**: Checks `docs/schemas/` for missing documentation, outdated field specifications, and mismatched example outputs
 
@@ -36,5 +37,3 @@ Use this agent when:
 - **Templates**: Ensure example outputs match the actual Liquid template rendering in `model_config.json_schema_extra`
 - **Pagination**: Document pagination fields (`max_items`, `start_index`, `pagination_id`) when applicable
 - **Cross-references**: Use `[link text](other_file.md)` format to reference related APIs
-
-

.gitignore

@@ -12,3 +12,17 @@ wheels/
 uv.lock
 
 references/
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+uv.lock
+
+references/

AGENTS.md

@@ -5,19 +5,18 @@
 - Lint & format: `ruff check --fix && ruff format`
 - Type checking: `ty check <dir_or_file>`
 - Run tests: `uv run pytest`
-- Use `uv` for Python related commands.
+- Python commands: always use `uv`
 
 ## Code Style Guidelines
 
 - Python: 3.12+ required
+- Imports & Formatting: use ruff
+- Async: Use async/await, `asyncer.TaskGroup` for concurrency
 
-## Schema Design
+## Implementation Guidelines
 
-- LLM-Agent centric design: Can agent build/understand the schema effectively?
-- Simplify Templates: Move complex logic from templates into data models.
-- Avoid advanced Pydantic features (e.g., `@computed_field`) to ensure clean and compatible JSON schema exports.
+- Path Handling: `client.from_uri()` returns relative paths by default. Use `relative=False` explicitly when absolute paths are required (e.g., for path comparisons in exclusion sets).
 
-## Template Design
+## Testing
 
-- Always read [cheetsheet](docs/liquid_cheatsheet.md) before writing Liquid templates.
-- Validate templates after writing.
+- Run `uv sync --upgrade` before testing and fixing type errors

CONTRIBUTING.md

@@ -6,7 +6,7 @@ Thank you for your interest in contributing to LSAP! This project aims to empowe
 
 LSAP is a multi-language monorepo:
 
-- **`src/lsap_schema/`**: Core protocol definitions and models (Python).
+- **`src/lsap.schema/`**: Core protocol definitions and models (Python).
 - **`python/`**: Python SDK and reference implementation.
 - **`typescript/`**: TypeScript type definitions and Zod schemas.
 - **`docs/`**: Protocol documentation and Liquid templates.
@@ -34,7 +34,7 @@ cd typescript && bun install
 
 ### Python & Schema
 
-The source of truth for LSAP schemas is the Python implementation in `src/lsap_schema/`.
+The source of truth for LSAP schemas is the Python implementation in `src/lsap.schema/`.
 
 - **Linting & Formatting**: `uv run ruff check --fix && uv run ruff format`
 - **Testing**: `uv run pytest`
@@ -50,11 +50,13 @@ The source of truth for LSAP schemas is the Python implementation in `src/lsap_s
 ## Design Guidelines
 
 ### Schema Design
+
 - **Agent-Centric**: Design schemas that are easy for LLMs to generate and consume.
 - **Clean Exports**: Avoid advanced Pydantic features (like `@computed_field`) that don't translate well to standard JSON Schema.
 - **Simplicity**: Move complex logic from templates into the data models.
 
 ### Template Design
+
 - **Liquid Templates**: We use Liquid for generating Markdown reports. Refer to [`docs/liquid_cheatsheet.md`](docs/liquid_cheatsheet.md).
 - **Validation**: Always validate templates with sample data after modification.
 

README.md

@@ -1,128 +1 @@
-# LSAP: Language Server Agent Protocol
-
-[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
-[![Protocol Version](https://img.shields.io/badge/Protocol-v1.0.0--alpha-blue.svg)]()
-
-**LSAP (Language Server Agent Protocol)** transforms low-level LSP capabilities into high-level, **Agent-Native** cognitive tools, empowering Coding Agents with **Repository-Scale Intelligence**.
-
-As an **Orchestration Layer**, LSAP composes atomic LSP operations into semantic interfaces. This aligns with Agent cognitive logic, allowing them to focus on high-level "intent realization" rather than tedious "editor operations."
-
-## Core Concept: Atomic Capabilities vs. Cognitive Capabilities
-
-The core difference of LSAP lies in how it defines "capabilities." LSP is designed for editors, providing **Atomic** operations; whereas LSAP is designed for Agents, providing **Cognitive** capabilities.
-
-- **LSP (Editor Perspective - Atomic)**:
-  - Editors require very low-level instructions: `textDocument/definition` (jump), `textDocument/hover` (hover), `textDocument/documentSymbol` (outline).
-  - **The Agent's Dilemma**: If an Agent uses LSP directly, it needs to execute a dozen interactions sequentially like a script (open file -> calculate offset -> request definition -> parse URI -> read file -> extract snippet) just to get a useful context.
-- **LSAP (Agent Perspective - Cognitive)**:
-  - LSAP encapsulates the complex chain of atomic operations above into a single semantic instruction.
-  - **Example**: A single request to "Find all references" triggers background execution of symbol localization, reference search, and context extraction, returning a consolidated **Markdown Report**.
-
-```mermaid
-sequenceDiagram
-    participant Agent as 🤖 Agent
-    participant LSAP as 🧠 LSAP Layer
-    participant LSP as 🔧 Language Server
-
-    Note left of Agent: Goal: Find all references of "User"
-
-    Agent->>LSAP: 1. Semantic Request (Locate + References)
-
-    rect rgb(245, 245, 245)
-        Note right of LSAP: ⚡️ Auto Orchestration
-        LSAP->>LSAP: Parse Semantic Anchor (Fuzzy Match)
-        LSAP->>LSP: textDocument/hover (Confirm Symbol Info)
-        LSAP->>LSP: textDocument/references (Get Reference List)
-        LSP-->>LSAP: Return List<Location>
-
-        loop For each reference point
-            LSAP->>LSP: textDocument/documentSymbol (Identify Function/Class)
-            LSAP->>LSAP: Read Surrounding Code (Context Lines)
-        end
-    end
-
-    LSAP-->>Agent: 2. Structured Markdown (Callers + Code Context)
-```
-
-## Interaction Example
-
-LSAP's interaction design strictly follows the **Markdown-First** principle: input expresses intent, and output provides refined knowledge.
-
-### Request: Semantic Search (Demonstrating Composed Capabilities)
-
-The Agent only needs to issue a high-level command without worrying about underlying row/column calculations or file reading:
-
-```jsonc
-// Intent: Find all usages of 'format_date' to refactor it
-{
-  "locate": {
-    "file_path": "src/utils.py",
-    "find": "def format_date<|>", // Semantic Anchor
-  },
-  "mode": "references",
-  "max_items": 10,
-}
-```
-
-### Response: Structured Knowledge
-
-LSAP aggregates the results of `references` (locations), `documentSymbol` (caller context), and `read` (code snippets):
-
-````markdown
-# References Found
-
-Total references: 45 | Showing: 2
-
-### `src/ui/header.py`:28
-
-In `Header.render` (`Method`)
-
-```python
-formatted = format_date(user.last_login)
-```
-
-### `src/api/views.py`:42
-
-In `UserDetail.get` (`Method`)
-
-```python
-return {"date": format_date(obj.created_at)}
-```
-````
-
-## I'm Not Convinced...
-
-### "LSAP Just Replicates LSP—What's Special?"
-
-While LSP provides **atomic operations**, LSAP offers **composed capabilities**.
-
-For instance, the **[Relation API](docs/schemas/draft/relation.md)** finds call paths between functions in a single request (handling traversal, cycles, and formatting), a task requiring complex orchestration in raw LSP. Similarly, the **[Unified Hierarchy API](docs/schemas/draft/hierarchy.md)** delivers unified graph representations optimized for agents.
-
-LSAP centralizes these patterns, preventing agents from wasting tokens on orchestration and enabling advanced capabilities like architectural and impact analysis.
-
-### "This Adds Complexity"
-
-LSAP **centralizes** complexity. Instead of every Agent reimplementing LSP orchestration logic, LSAP provides a shared, optimized layer for these common patterns.
-
-## Project Structure
-
-- [`docs/`](docs/): Core protocol definitions and Schema documentation.
-- [`python/`](python/): Python SDK reference implementation.
-- [`typescript/`](typescript/): TypeScript type definitions and utility library.
-- [`web/`](web/): Protocol documentation site.
-
-## Alternatives
-
-- Claude Code have native LSP supports now.
-- [claude-code-lsps](https://github.com/Piebald-AI/claude-code-lsps)
-- [serena](https://github.com/oraios/serena)
-- [cclsp](https://github.com/ktnyt/cclsp)
-- [mcpls](https://github.com/bug-ops/mcpls)
-
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on development workflows and design principles.
-
-## License
-
-[MIT](LICENSE)
+# Language Server Agent Protocol (LSAP)

justfile

@@ -3,11 +3,8 @@ sync:
 
 # Export JSON schemas from Python
 schema-json output:
-    cd schema && uv run -m lsap_schema -o {{output}}
+    uv run -m lsap.schema -o {{output}}
 
 # Generate Zod schemas from JSON schemas
 schema-zod:
     cd typescript && bun run scripts/gen-zod.ts
-
-# Run full codegen pipeline
-codegen: (schema-json "../typescript/schemas") schema-zod

pyproject.toml

@@ -1,13 +1,15 @@
 [project]
-name = "lsap-schema"
+name = "lsap"
 version = "0.1.0"
 description = "Add your description here"
 readme = "README.md"
-authors = [
-    { name = "observerw", email = "wozluohd@gmail.com" }
-]
 requires-python = ">=3.12"
 dependencies = [
+    "anyio>=4.12.0",
+    "asyncer>=0.0.11",
+    "attrs>=25.4.0",
+    "cattrs>=25.3.0",
+    "lsp-client",
     "lsprotocol>=2025.0.0",
     "pydantic>=2.12.5",
     "python-liquid>=2.1.0",
@@ -17,7 +19,18 @@ dependencies = [
 requires = ["uv_build>=0.9.9,<0.10.0"]
 build-backend = "uv_build"
 
+[tool.uv.workspace]
+members = ["lsap-schema"]
+
+[tool.uv.sources]
+lsp-client = { git = "https://github.com/lsp-client/lsp-client.git", branch = "release/v0.3" }
+
+[tool.pytest.ini_options]
+norecursedirs = ["references"]
+testpaths = ["tests"]
+
 [dependency-groups]
 dev = [
     "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
 ]