Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

.system/specs/PX-SPEC-LSP4N8Q2-agent-lsp-navigation/index.md

Raw
Rendered preview

id: PX-SPEC-LSP4N8Q2 type: spec title: Agent LSP Navigation

Intent

Give Pi agents bounded semantic code navigation through installed language servers, without owning parser infrastructure or editor UI. Keep upstream configuration maintenance separate from runtime queries. Complement text search and ast-grep; leave memory unchanged.

Scope

In: curated local server registry, explicit upstream refresh, one lsp tool, definitions, references, hover, type definitions, implementations, document/workspace symbols, one-hop incoming/outgoing calls. Out: server installation, automatic config repair, recursive call graphs, rename, formatting, code actions, command execution, diagnostics UI, editor buffers, automatic prompt injection. No requirement to support every language, server, or LSP operation.

Configuration lifecycle

Explicit maintenance produces reviewed local defaults; queries consume them without fetching upstream catalogs.

flowchart TB
  H["Helix defaults"] --> U["Explicit refresh"]
  S["Selected supplements"] --> U
  U --> D["Review changes and conflicts"]
  D --> R["Committed local registry"]
  R --> T["LSP tool"]
  A["Agent query"] --> T
  T --> L["Installed language server"]
  • Registry records launch command/arguments, applicable languages/files, root-selection information, necessary initialization options/settings, and source revision provenance.
  • Initialization options and runtime settings retain their distinct meanings.
  • Helix is primary reference; other catalogs supply deliberately selected additions, not unconditional merges.
  • Conflicting imports are visible; local decisions survive refresh unless explicitly replaced.
  • Importing does not blindly carry editor preferences, machine-specific installation paths, or client-specific placeholders into supported defaults.
  • Failed or interrupted refresh leaves last usable registry intact; runtime does not depend on upstream availability.
  • Source reuse respects upstream licensing.
  • Missing executable or invalid configuration is reported, not installed, repaired, or silently bypassed.
  • User/project configuration follows repository settings and trust law; no credential belongs in registry data.

Agent contract

Queries select operation, target file or workspace, and operation-specific input. Position-based requests use file, one-based line, and an explicitly documented column unit; internal server encoding must not change agent-visible coordinates. Symbol discovery accepts a query or file, without requiring an already known source position.

Operation Question answered
Definition Which declaration does this usage resolve to?
References Where does the server resolve usages of this symbol?
Hover What type, signature, or documentation applies here?
Type definition Where is this value's type defined?
Implementations What implements this contract?
Document symbols What declarations exist in this file?
Workspace symbols Which indexed symbols match this query?
Incoming/outgoing calls What calls this target, or what does it call?

Results identify operation, server, scope, source locations and concise content appropriate to the operation. Location results include bounded source context; hover includes applicable range when available. Output size, query duration, and client-visible cancellation are bounded. Results disclose tool-imposed truncation, interrupted partial responses, and server-reported limits. Server/index completeness is unknown unless established by a documented server contract; configured scope is not proof of exhaustive coverage.

Capability-dependent behavior

The tool owns server startup, capability discovery, configuration exchange, document synchronization, and shutdown. Only actual client capabilities are advertised; advertised server capabilities and applicable changes determine operation availability.

flowchart TB
  Q["Query"] --> C{"Supported?"}
  C -->|no| U["Unsupported"]
  C -->|yes| E["Query synchronized source"]
  E --> R["Result, uncertainty, or failure"]
  • Unsupported capabilities, invalid input, ambiguity, timeout, client-visible cancellation, and reported failures remain distinguishable.
  • Semantic absence, empty relationships, and not-ready states are distinguished only when evidenced; otherwise report no result with readiness unknown.
  • No silent substitution of references for callers, syntactic calls for resolved callees, or text matches for semantic results.
  • Call hierarchy resolves target before requesting either direction; multiple targets produce distinguishable candidates instead of an arbitrary choice.
  • Incoming results attribute call-site ranges to callers; outgoing results attribute them to the queried caller.
  • Call hierarchy is one hop, not a complete runtime dependency graph; successful empty results mean server found none.
  • Newer protocol fields/features do not automatically expand supported behavior; protocol updates and registry refresh are independent maintenance events.

Source and process lifecycle

On-disk files are authoritative; no editor-buffer integration is required. Queries synchronize observed on-disk document snapshots and relevant change information before requesting results. Managed-document synchronization does not establish workspace/index freshness; unverifiable freshness is reported as unknown. Source context and coordinate conversion are not presented as verified against a different or unknown source revision. File versions, workspace/root selection, and Unicode position conversion remain correct across repeated queries. Servers are reused only within compatible workspace/configuration contexts; failures do not produce fabricated empty results. Cancellation or deadline expiry ends the client-visible query within a bounded time; later responses cannot turn that outcome into success. Immediate server-worker termination is not guaranteed; canceling one query does not require stopping a reusable server. Session teardown and Pi shutdown terminate owned server processes within a bounded time. Queries never apply server-requested workspace edits or execute server-requested commands.

Acceptance criteria

  • Explicit upstream refresh yields reviewable changes with provenance, preserves local decisions, exposes conflicts, and retains usable defaults after failure/interruption.
  • Queries use local registry without catalog network access; missing tools and invalid configuration are actionable failures without installation, repair, or bypass.
  • Definition, references, hover, type definition, implementations, and document/workspace symbols return correct bounded evidence against representative supporting servers.
  • Supported call hierarchy returns correct one-hop targets and call-site ownership in both directions; ambiguous preparation returns candidates.
  • Unsupported capability, invalid input, ambiguity, timeout, client-visible cancellation, and reported server/config failure are observably distinct; unobservable absence/readiness distinctions remain unknown.
  • Results disclose server, scope, tool-imposed truncation, reported server limits, and unknown completeness; no approximate fallback masquerades as resolved evidence.
  • Known Pi/external edits, Unicode positions, and multiple workspace roots preserve correct query targets; unverifiable workspace freshness or source-revision correspondence is disclosed rather than asserted.
  • Repeated queries reuse compatible servers; cancellation/deadlines bound client-visible waits without accepting late success, and teardown terminates owned server processes within a bounded time.
  • Native Pi tool use works with a real installed server; server-initiated requests cannot mutate project files or execute commands through the extension.
  • Registry refresh or protocol-library updates do not silently change supported tool semantics.

References

---
id: PX-SPEC-LSP4N8Q2
type: spec
title: Agent LSP Navigation
---

## Intent

Give Pi agents bounded semantic code navigation through installed language servers, without owning parser infrastructure or editor UI.
Keep upstream configuration maintenance separate from runtime queries.
Complement text search and ast-grep; leave memory unchanged.

## Scope

In: curated local server registry, explicit upstream refresh, one `lsp` tool, definitions, references, hover, type definitions, implementations, document/workspace symbols, one-hop incoming/outgoing calls.
Out: server installation, automatic config repair, recursive call graphs, rename, formatting, code actions, command execution, diagnostics UI, editor buffers, automatic prompt injection.
No requirement to support every language, server, or LSP operation.

## Configuration lifecycle

Explicit maintenance produces reviewed local defaults; queries consume them without fetching upstream catalogs.

```mermaid
flowchart TB
  H["Helix defaults"] --> U["Explicit refresh"]
  S["Selected supplements"] --> U
  U --> D["Review changes and conflicts"]
  D --> R["Committed local registry"]
  R --> T["LSP tool"]
  A["Agent query"] --> T
  T --> L["Installed language server"]
```

- Registry records launch command/arguments, applicable languages/files, root-selection information, necessary initialization options/settings, and source revision provenance.
- Initialization options and runtime settings retain their distinct meanings.
- Helix is primary reference; other catalogs supply deliberately selected additions, not unconditional merges.
- Conflicting imports are visible; local decisions survive refresh unless explicitly replaced.
- Importing does not blindly carry editor preferences, machine-specific installation paths, or client-specific placeholders into supported defaults.
- Failed or interrupted refresh leaves last usable registry intact; runtime does not depend on upstream availability.
- Source reuse respects upstream licensing.
- Missing executable or invalid configuration is reported, not installed, repaired, or silently bypassed.
- User/project configuration follows repository settings and trust law; no credential belongs in registry data.

## Agent contract

Queries select operation, target file or workspace, and operation-specific input.
Position-based requests use file, one-based line, and an explicitly documented column unit; internal server encoding must not change agent-visible coordinates.
Symbol discovery accepts a query or file, without requiring an already known source position.

| Operation | Question answered |
| --- | --- |
| Definition | Which declaration does this usage resolve to? |
| References | Where does the server resolve usages of this symbol? |
| Hover | What type, signature, or documentation applies here? |
| Type definition | Where is this value's type defined? |
| Implementations | What implements this contract? |
| Document symbols | What declarations exist in this file? |
| Workspace symbols | Which indexed symbols match this query? |
| Incoming/outgoing calls | What calls this target, or what does it call? |

Results identify operation, server, scope, source locations and concise content appropriate to the operation.
Location results include bounded source context; hover includes applicable range when available.
Output size, query duration, and client-visible cancellation are bounded.
Results disclose tool-imposed truncation, interrupted partial responses, and server-reported limits.
Server/index completeness is unknown unless established by a documented server contract; configured scope is not proof of exhaustive coverage.

## Capability-dependent behavior

The tool owns server startup, capability discovery, configuration exchange, document synchronization, and shutdown.
Only actual client capabilities are advertised; advertised server capabilities and applicable changes determine operation availability.

```mermaid
flowchart TB
  Q["Query"] --> C{"Supported?"}
  C -->|no| U["Unsupported"]
  C -->|yes| E["Query synchronized source"]
  E --> R["Result, uncertainty, or failure"]
```

- Unsupported capabilities, invalid input, ambiguity, timeout, client-visible cancellation, and reported failures remain distinguishable.
- Semantic absence, empty relationships, and not-ready states are distinguished only when evidenced; otherwise report no result with readiness unknown.
- No silent substitution of references for callers, syntactic calls for resolved callees, or text matches for semantic results.
- Call hierarchy resolves target before requesting either direction; multiple targets produce distinguishable candidates instead of an arbitrary choice.
- Incoming results attribute call-site ranges to callers; outgoing results attribute them to the queried caller.
- Call hierarchy is one hop, not a complete runtime dependency graph; successful empty results mean server found none.
- Newer protocol fields/features do not automatically expand supported behavior; protocol updates and registry refresh are independent maintenance events.

## Source and process lifecycle

On-disk files are authoritative; no editor-buffer integration is required.
Queries synchronize observed on-disk document snapshots and relevant change information before requesting results.
Managed-document synchronization does not establish workspace/index freshness; unverifiable freshness is reported as unknown.
Source context and coordinate conversion are not presented as verified against a different or unknown source revision.
File versions, workspace/root selection, and Unicode position conversion remain correct across repeated queries.
Servers are reused only within compatible workspace/configuration contexts; failures do not produce fabricated empty results.
Cancellation or deadline expiry ends the client-visible query within a bounded time; later responses cannot turn that outcome into success.
Immediate server-worker termination is not guaranteed; canceling one query does not require stopping a reusable server.
Session teardown and Pi shutdown terminate owned server processes within a bounded time.
Queries never apply server-requested workspace edits or execute server-requested commands.

## Acceptance criteria

- [ ] Explicit upstream refresh yields reviewable changes with provenance, preserves local decisions, exposes conflicts, and retains usable defaults after failure/interruption.
- [ ] Queries use local registry without catalog network access; missing tools and invalid configuration are actionable failures without installation, repair, or bypass.
- [ ] Definition, references, hover, type definition, implementations, and document/workspace symbols return correct bounded evidence against representative supporting servers.
- [ ] Supported call hierarchy returns correct one-hop targets and call-site ownership in both directions; ambiguous preparation returns candidates.
- [ ] Unsupported capability, invalid input, ambiguity, timeout, client-visible cancellation, and reported server/config failure are observably distinct; unobservable absence/readiness distinctions remain unknown.
- [ ] Results disclose server, scope, tool-imposed truncation, reported server limits, and unknown completeness; no approximate fallback masquerades as resolved evidence.
- [ ] Known Pi/external edits, Unicode positions, and multiple workspace roots preserve correct query targets; unverifiable workspace freshness or source-revision correspondence is disclosed rather than asserted.
- [ ] Repeated queries reuse compatible servers; cancellation/deadlines bound client-visible waits without accepting late success, and teardown terminates owned server processes within a bounded time.
- [ ] Native Pi tool use works with a real installed server; server-initiated requests cannot mutate project files or execute commands through the extension.
- [ ] Registry refresh or protocol-library updates do not silently change supported tool semantics.

## References

- [LSP specification](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification).
- [Helix language/server defaults](https://github.com/helix-editor/helix/blob/master/languages.toml).
- [lsp-bridge server catalog](https://github.com/manateelazycat/lsp-bridge/tree/master/langserver).