2 +id: NL-RESEARCH-KZYYEFY_
4 +title: Pi and Neovim capabilities for pivi
7 +#
Pi and Neovim capabilities for pivi 11 +Installed documentation only; no remembered API behavior.
13 +| Source | Version | Location |
15 +| Pi docs (`rpc.md`, `extensions.md`, `usage.md`, `sessions.md`, `json.md`) | 0.85.1 | `$PI_CONTEXT_DOCS_PATH` |
16 +| Neovim runtime docs (`api.txt`, `lua.txt`, `undo.txt`, `editing.txt`, `options.txt`) | 0.12.5 | `$VIMRUNTIME/doc` |
22 +- `pi --mode rpc` speaks JSON commands on stdin, responses and events on stdout.
23 +- Strict JSONL, LF only; clients strip a trailing `\r`; Unicode separators must not split records.
24 +- Optional `id` on commands correlates responses; most events carry no `id`.
25 +- Startup flags relevant to a client: `--provider`, `--model`, `--name`, `--session <path|id>`, `--session-dir`, `--no-session`, `-e <ext>`, `--tools`, `--append-system-prompt`.
27 +###
Commands that map to pivi surfaces 29 +| pivi need | RPC command | Notes |
31 +| Submit prompt | `prompt` | During streaming requires `streamingBehavior: steer \| followUp`, else error |
32 +| Queue while running | `steer`, `follow_up`, `clear_queue` | Extension commands rejected here |
33 +| Stop | `abort`, `abort_retry`, `abort_bash` | `abort` waits for idle |
34 +| Status | `get_state`, `get_session_stats` | Model, thinking, streaming, queue, context usage |
35 +| Transcript | `get_messages`, `get_entries`, `get_tree` | `get_entries since` is a durable cursor; `leafId` detects branch moves |
36 +| Sessions | `new_session`, `switch_session`, `fork`, `clone`, `set_session_name` | Switch/fork cancellable by extensions |
37 +| Slash commands | `get_commands` | Returns extension, prompt-template, and skill commands; invoked as `/name` through `prompt` |
38 +| Model/thinking | `set_model`, `cycle_model`, `get_available_models`, `set_thinking_level`, `get_available_thinking_levels` | |
39 +| Compaction | `compact`, `set_auto_compaction` | |
41 +Built-in TUI commands such as `/settings` and `/hotkeys` are absent from `get_commands` and do not execute over RPC.
43 +###
Concurrency semantics 48 + Idle --> Streaming: prompt
49 + Streaming --> Streaming: steer / follow_up queued
50 + Streaming --> Streaming: extension command executes immediately
51 + Streaming --> Idle: agent_settled
52 + Streaming --> Idle: abort
55 +- A plain `prompt` while streaming is rejected without `streamingBehavior`.
56 +- An extension command (`/name`) sent through `prompt` executes immediately even during streaming and manages its own LLM interaction.
57 +- `agent_end` marks one low-level run; `agent_settled` marks full settlement after retry, compaction, and queued continuations.
58 +- Therefore a truly ephemeral question that never enters session history needs either an extension command or a separate process (`pi -p` / `pi --mode json` / a second `--mode rpc --no-session` child).
62 +Streamed as JSONL: `agent_start`, `agent_end`, `agent_settled`, `turn_start`, `turn_end`, `message_start`, `message_update`, `message_end`, `tool_execution_start|update|end`, `bash_execution_update`, `queue_update`, `compaction_start|end`, `auto_retry_start|end`, `summarization_retry_*`, `extension_error`.
64 +- `message_update` carries only deltas; clients assemble partial state by `contentIndex`; `message_end.message` is authoritative.
65 +- Tool-call streaming exposes `toolcall_start` (`id`, `toolName`), `toolcall_delta` (argument chunks), `toolcall_end` (complete call). This is the only source for progressive edit intent, and argument chunks are partial JSON text.
66 +- `tool_execution_update.partialResult` is cumulative, not a delta.
68 +###
Extension UI over RPC 70 +| Method | RPC behavior |
72 +| `select`, `confirm`, `input`, `editor` | Request/response sub-protocol with matching `id`; optional `timeout` auto-resolves agent-side |
73 +| `notify`, `setStatus`, `setWidget`, `setTitle`, `set_editor_text` | Fire-and-forget requests |
74 +| `custom` | Returns `undefined` |
75 +| `setWorkingMessage`, `setWorkingIndicator`, `setFooter`, `setHeader`, `setEditorComponent`, `setToolsExpanded` | No-ops |
76 +| `getEditorText`, `getToolsExpanded`, theme getters/setters | Degraded or empty |
78 +`ctx.mode === "rpc"` and `ctx.hasUI === true`; TUI-only capability must be guarded on `ctx.mode === "tui"`.
80 +###
Extension hooks a companion extension can use 82 +- `pi.registerTool` at load or at runtime; new tools are callable without `/reload`.
83 +- Built-in tools `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls` can be overridden by registering the same name; result and `details` shapes must match exactly; omitted renderers fall back to built-ins; `promptSnippet`/`promptGuidelines` are not inherited.
84 +- Built-in tools also accept pluggable operations (`ReadOperations`, `WriteOperations`, `EditOperations`, `BashOperations`, …) via `createReadTool` and siblings, plus a `spawnHook` for shell tools. This delegates I/O without reimplementing tool semantics.
85 +- `tool_call` can mutate arguments or block; `tool_result` can post-process.
86 +- `input` event sees raw text with `source` of `interactive | rpc | extension` and can `continue`, `transform`, or `handled`.
87 +- `before_agent_start` exposes and can extend `systemPrompt` and structured `systemPromptOptions`.
88 +- `pi.registerCommand` supports `getArgumentCompletions`; `pi.getCommands` mirrors `get_commands`.
89 +- Tool output must be truncated; built-in limits are 50KB and 2000 lines.
95 +- `vim.system(cmd, { stdin = true, stdout = fun(err, data), stderr = fun(err, data) })` gives streaming callbacks plus `SystemObj:write(data)` and `obj:write(nil)` to close stdin; `obj:kill()` stops the child.
96 +- Output callbacks run in fast contexts; API calls must be deferred through `vim.schedule` (`api-fast`, `vim.in_fast_event()`).
97 +- `jobstart`/`nvim_chan_send` remain the alternative channel API.
99 +###
Buffers and edits 101 +| Need | Mechanism | Caveat |
103 +| Precise edit | `nvim_buf_set_text`, `nvim_buf_set_lines` | Each call opens a new undo block |
104 +| One undoable change | `:undojoin` before the next change | `E790` after undo/redo; must not be used blindly |
105 +| Change detection | `nvim_buf_attach` `on_lines`, `b:changedtick` | Callbacks are fast-context |
106 +| Diffing model output against buffer | `vim.text.diff` with `result_type = 'indices'` | Available in 0.12 |
107 +| Disk coherence after buffer edits | buffer write plus `:checktime`; `'autoread'` defaults on | Unwritten buffers stay invisible to filesystem tools |
111 +- Extmarks provide `virt_text` with `virt_text_pos = "inline"` for ghost text, `virt_lines` (with `virt_lines_above`, `virt_lines_overflow`), highlights, and signs.
112 +- `nvim_set_decoration_provider` with `ephemeral` marks renders per redraw without persistent state.
113 +- `vim.diagnostic` namespaces keep agent findings separate from LSP and compiler diagnostics.
114 +- Quickfix and location lists use `setqflist`/`setloclist` and normal navigation.
116 +###
Integration surface 118 +- `nvim_exec_autocmds` emits `User` events with a `data` payload (`event-data`), which fits publishing cached pivi state.
119 +- `nvim_create_user_command` supplies subcommands, `nargs`, and custom completion for `:Pi help` and `:Pi command ...`.
120 +- `<Plug>` mappings expose behavior without claiming global keys.
121 +- `vim.ui.select` and `vim.ui.input` can back RPC dialog methods.
123 +##
Spec claims versus evidence 125 +| Spec claim | Support | Risk |
127 +| Non-terminal JSONL subprocess channel | `pi --mode rpc` plus `vim.system` stdin/stdout | Low |
128 +| Semantic status (queue, run, tool, retry, compaction) | `get_state`, `get_session_stats`, event stream | Low |
129 +| Slash commands via `:Pi command ...` | `get_commands` plus `prompt` with `/name` | Low; TUI-only commands unavailable |
130 +| `:Pi help` runnable during an active run | Extension command executes during streaming, or a separate ephemeral process | Medium; not ephemeral if routed through the working session |
131 +| Loaded buffers authoritative for reads and edits | Built-in tool override or injected `ReadOperations`/`EditOperations`/`WriteOperations` | Medium; result and `details` shapes must match exactly |
132 +| Progressive ghost text from streaming tool arguments | `toolcall_delta` plus inline `virt_text` | Medium; requires tolerant partial-JSON parsing |
133 +| One coherent undoable change per edit | `nvim_buf_set_text` plus `:undojoin` | Medium; `E790` and multi-hunk edits |
134 +| Edits visible to later shell work without watchers | Explicit buffer write plus `:checktime` | Medium; unwritten buffers diverge from disk |
135 +| Extension dialogs mapped to native surfaces | `extension_ui_request`/`extension_ui_response` | Low |
136 +| Multiple sessions, resume, switch | `--session`, `switch_session`, `new_session`, `fork`, `clone` | Low |
140 +- Does `:Pi help` use a second short-lived Pi process, or a companion extension command inside the working session that suppresses history?
141 +- Can two Pi processes safely target one session file, or must ephemeral help always run with `--no-session`?
142 +- Is buffer authority better implemented as operations injection into built-in tools than as full tool overrides, given the exact `details` shape requirement?
143 +- How should partial `toolcall_delta` arguments be parsed safely enough to show ghost text without ever mutating a buffer?
144 +- When must pivi write a modified buffer to disk so that agent shell commands observe agent edits?