repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(neovim): specify and plan pivi tool presentation

50d905fcddb499eeed113b8cde78f522e2e26d6c

Oliver Krylow <o.krylow@isp-insoft.de> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (2)

neovim/.system/plans/NL-PLAN-T7XG71CC-deliver-pivi-tool-presentation/index.md

Added
new file mode 100644
1 +---
2 +id: NL-PLAN-T7XG71CC
3 +type: plan
4 +title: Deliver pivi tool presentation
5 +spec: NL-SPEC-GMWDCMJZ
6 +status: approved
7 +depends_on:
8 + - NL-PLAN-CEJPO_XF
9 + - NL-PLAN-LAJ8PGRK
10 +---
12 +# Deliver pivi tool presentation
14 +## Intent
16 +Make a tool call as legible in Neovim as it is in Pi's own interface, using native surfaces rather than a ported component tree.
18 +[NL-PLAN-LAJ8PGRK](../NL-PLAN-LAJ8PGRK-deliver-pivi-transcript-presentation-and-navigat/index.md) made every tool call an addressable, collapsible entry.
19 +That entry currently shows what a tool acted on and nothing about how it ended, and it discards everything a tool reports about its own work.
21 +Blocker: the behavior below is not yet in [NL-SPEC-GMWDCMJZ](../../specs/NL-SPEC-GMWDCMJZ-pivi-native-neovim-integration/index.md).
22 +A tool presentation section and its acceptance criteria were drafted and await one-shot approval.
23 +This plan is not executable until that amendment lands.
25 +## Evidence
27 +Read from the installed Pi 0.85.1 implementation, not from prose.
28 +Tool results reach a client unchanged, so everything a tool reports is already on the wire and merely unused.
30 +| Tool | What it reports about its own work | When |
31 +| --- | --- | --- |
32 +| edit | a display diff, a unified patch, and the first changed line | always |
33 +| bash | progressive output, truncation, and a full output path | while running, throttled |
34 +| read | truncation | only when truncated |
35 +| grep, find, ls | truncation and the limit that was reached | only at a limit |
36 +| write | nothing | — |
38 +Neovim side: no diff parser ships, but diff syntax and the diff highlight groups do, and the theme already defines them.
40 +## Module map
42 +```mermaid
43 +flowchart TB
44 + session["bugabinga.pivi.session"] --> tool["bugabinga.pivi.tool"]
45 + tool --> entry["bugabinga.pivi.entry"]
46 + tool --> render["bugabinga.pivi.render"]
47 + render --> fold["bugabinga.pivi.fold"]
48 + tool --> diff["bugabinga.pivi.diff"]
49 + diff --> command["bugabinga.pivi.command"]
50 + tool --> navigate["bugabinga.pivi.navigate"]
51 +```
53 +| Module | Responsibility |
54 +| --- | --- |
55 +| `bugabinga.pivi.tool` | Interprets what a tool reports: outcome, change, progress, language, truncation |
56 +| `bugabinga.pivi.render` | Presents that interpretation as decoration inside the entry |
57 +| `bugabinga.pivi.diff` | Editor comparison of a completed change |
58 +| `bugabinga.pivi.fold` | Collapsed line that still states subject and outcome |
59 +| `bugabinga.pivi.navigate` | Reaching the first changed line rather than the file start |
60 +| `bugabinga.pivi.entry` | Carries the interpretation as entry metadata |
61 +| `bugabinga.pivi.session` | Feeds tool reports in, including while a tool still runs |
63 +## Slice order
65 +```mermaid
66 +flowchart LR
67 + s1["1 Outcome after the name"] --> s2["2 Change as a diff"]
68 + s1 --> s6["6 Truncation is reachable"]
69 + s2 --> s3["3 First changed line"]
70 + s2 --> s4["4 Editor comparison"]
71 + s1 --> s5["5 Output while running"]
72 + s5 --> s7["7 Output in its language"]
73 +```
75 +| # | Observable behavior | Modules touched | Verified by |
76 +| --- | --- | --- | --- |
77 +| 1 | A finished tool entry states how it ended beside what it acted on, and a collapsed entry keeps both | `bugabinga.pivi.tool`, `bugabinga.pivi.render`, `bugabinga.pivi.fold`, `bugabinga.pivi.session` | Outcome spec across edit, shell, search, and failure, plus a collapsed-line spec |
78 +| 2 | A completed edit shows its change with added and removed lines distinguished | `bugabinga.pivi.tool`, `bugabinga.pivi.render` | Diff presentation spec asserting distinct added and removed lines and unchanged buffer text |
79 +| 3 | Navigating from an edit lands on its first changed line | `bugabinga.pivi.navigate`, `bugabinga.pivi.tool` | Navigation spec over a recorded edit |
80 +| 4 | A change can be opened as a full editor comparison and left again | `bugabinga.pivi.diff`, `bugabinga.pivi.command` | Comparison spec asserting the working window survives and the transcript is unchanged |
81 +| 5 | Output of a running tool appears as it arrives rather than only at completion | `bugabinga.pivi.session`, `bugabinga.pivi.tool`, `bugabinga.pivi.entry` | Progressive-output spec asserting growth before completion and stable bounds |
82 +| 6 | A truncated result says so, and its full output is reachable | `bugabinga.pivi.tool`, `bugabinga.pivi.render`, `bugabinga.pivi.navigate` | Truncation spec asserting the notice and a reachable full output |
83 +| 7 | Output is presented in the language it came from when that language is known | `bugabinga.pivi.tool`, `bugabinga.pivi.render` | Language spec asserting a second language is parsed inside the transcript |
85 +Slice 1 is the walking skeleton: it establishes the interpretation every later slice reads.
87 +## Critical paths
89 +- Interpretation is derived only from what a tool reports; a tool that reports nothing degrades to today's behavior rather than to a guess.
90 +- Diff presentation is decoration over reported change text, so the transcript still yields message text when copied.
91 +- An editor comparison reconstructs the prior content from the reported change rather than re-reading a file that has already moved on.
92 +- Progressive output replaces the tail of its own entry; entry bounds stay extmark-backed and must survive repeated rewrites.
93 +- Presentation stays redraw-driven, so a tool that emits output continuously cannot force parsing per update.
95 +## Risks
97 +| Risk | Slice | Mitigation |
98 +| --- | --- | --- |
99 +| Tools differ in what they report | 1 | Interpretation is per tool with a plain fallback, asserted for a tool that reports nothing |
100 +| Diff decoration drifts from the text it marks | 2 | Anchor decoration to entry-relative rows and assert after later entries are appended |
101 +| A reconstructed comparison disagrees with the file on disk | 4 | Present it as a comparison of the recorded change, and state when the file has moved on |
102 +| Frequent progress updates cost too much | 5 | Rewrite only the entry tail, keep parsing redraw-driven, and hold the streaming budget spec |
103 +| A collapsed line grows unreadable | 1 | Bound subject and outcome, and assert a maximum collapsed width |

neovim/.system/specs/NL-SPEC-GMWDCMJZ-pivi-native-neovim-integration/index.md

Modified
129 129 Located --> Expanded: return
132 +## Tool presentation
134 +A tool call is work the user did not watch happen, so the transcript has to account for it.
136 +- A tool entry names what the tool acted on, and once it finishes, how it ended.
137 +- A completed edit presents its change as a diff, distinguishing added from removed lines, and that diff can be opened as a full editor comparison on request.
138 +- Navigating from an edit reaches its first changed line rather than the start of the file.
139 +- Output a tool produces while it runs appears as it arrives, not only at completion.
140 +- Output is presented in the language it came from when that language is known.
141 +- A result the agent could not keep in full says so, and its full output stays reachable.
142 +- An outcome stays legible while an entry is collapsed.
143 +- A tool that reports nothing about its own work degrades to naming its subject rather than to a guess.
145 +```mermaid
146 +stateDiagram-v2
147 + [*] --> Started: tool call
148 + Started --> Streaming: output arrives
149 + Streaming --> Completed: tool ends
150 + Started --> Completed: tool ends
151 + Completed --> Compared: open the change
152 + Compared --> Completed: return
153 +```
132 155 ## Agent activity
134 157 - Active edits may use signs, line highlights, extmarks, virtual text, or virtual lines.
184 207 - A Pi slash command can run through `:Pi command ...`; `/` invokes slash-command entry only at the first character of a Pi input buffer.
185 208 - A transcript renders message formatting, presents embedded code in its own language, and still yields the original text when copied.
209 +- A completed edit shows added and removed lines distinctly and can be opened as an editor comparison.
210 +- Navigating from an edit entry lands on its first changed line.
211 +- Output of a long-running tool appears progressively rather than only at completion.
212 +- A truncated result is marked as truncated and its full output stays reachable.
213 +- A collapsed tool entry still states what the tool acted on and how it ended.
186 214 - A tool result is collapsed on arrival, expands on request, and collapsing never changes session history.
187 215 - A user can move between transcript entries with ordinary motions and reach the location an entry names.
188 216 - Transcript presentation performs no Pi RPC, and a long streamed answer stays responsive.