pi-config/extensions/pi-lsp-extension/specs/completions-tool.md

Completions Tool

Summary

Add an lsp_completions tool that returns completion suggestions at a given position in a file. This lets the LLM discover available methods, properties, and APIs on objects without having to read documentation or source code.

Motivation

When writing code, the LLM often needs to know what methods are available on an object — e.g., "what can I call on s3Client?" or "what fields does this struct have?". Today it either guesses (risking hallucination) or has to read the source/type definitions manually.

LSP completion is exactly this: given a cursor position, the language server returns ranked suggestions with type signatures and documentation. Kiro CLI exposes this and it's one of their differentiators.

Goals

• lsp_completions tool — return completion items at a position, with type signatures and docs
• Smart triggering — the LLM can ask "what methods are available on X" and get actionable results
• Concise output — return the top N results (default 20) with kind, label, type, and doc summary — not the full verbose LSP response

Non-goals

• Snippet expansion or tab-completion UX — this is a query tool, not an interactive completion engine
• Commit characters, edit ranges, or other IDE-specific completion metadata
• Tree-sitter fallback — completions fundamentally require type information, so this is LSP-only

Design

Tool definition

lsp_completions

Parameter	Type	Description
path	string	File path
line	number	Line number (1-indexed)
character	number	Column number (1-indexed)
limit	number?	Max results to return (default: 20)

Trigger workflow

The LLM typically uses this in one of two ways:

1. Explore an API: Write s3Client. in a file, then call lsp_completions at the position after the dot to see available methods.
2. Verify a method exists: Before calling response.bodyAsString(), check completions on response. to confirm the method name.

In both cases the file needs to be open in the LSP (handled by FileSync) and the content needs to reflect the current state.

Synthetic trigger

A common case is "what methods does X have?" where X is already in the code but there's no trailing dot. The tool should support a convenience mode:

• If the position points to the end of an identifier, the tool temporarily inserts a . after it, requests completions, then removes it. This avoids forcing the LLM to edit the file just to explore an API.
• This is optional and gated by a trigger parameter ("auto" | "none", default "auto").

Output format

20 completions at src/handler.ts:42:15

method  getObject(params: GetObjectRequest): Promise<GetObjectOutput>
          Retrieves an object from S3.
method  putObject(params: PutObjectRequest): Promise<PutObjectOutput>
          Uploads an object to S3.
property region: string
          The AWS region for this client.
...

Each item shows:

• Kind — method, property, function, variable, class, keyword, etc.
• Label + signature — from detail or labelDetails in the LSP response
• Documentation — first 1-2 lines of the doc comment, if available

Items are sorted by the LSP server's sortText ranking (which considers scope, type match, and usage frequency).

Resolve for details

Many LSP servers return minimal items in the initial response and require a completionItem/resolve call for documentation and full signatures. The tool should:

1. Request completions at the position
2. For the top N items, call completionItem/resolve in parallel to get full details
3. Merge results and format output

This adds latency but dramatically improves output quality. Cap resolve calls to the limit parameter to bound cost.

File layout

src/tools/
└── completions.ts

Integration

• Register in index.ts alongside existing tools
• Add to the extension's system prompt snippet: mention that lsp_completions is available for discovering methods and properties
• No tree-sitter fallback — return a clear message if no LSP server is running

Open questions

• Synthetic trigger safety — temporarily modifying file content to insert a . could cause issues if the LSP processes the change and emits diagnostics before we revert. Should we use a separate virtual document, or is the insert-request-revert cycle fast enough to be safe?
• Performance — completionItem/resolve for 20 items could be slow on some servers. Should we resolve lazily (only top 5) or make it configurable?
• Filter parameter — should the tool accept a filter string to pre-filter results (e.g., only methods, only properties)? Or is that over-engineering for v1?