@tduyng/pi-edit-path 0.0.3 → 0.0.4

package/README.md

@@ -1,44 +1,47 @@
 # @tduyng/pi-edit-path
 
-Fix the edit path instead of walking it twice. Fuse the check into the edit that needs it, and name the region on disk a failed edit meant, so the retry lands without a re-read.
+Two round trips on the edit path are avoidable. One follows a failed edit, the other follows a successful one.
 
-## What it costs
+## After a failed edit
 
-`then_run` adds two guideline bullets to the `edit` and `write` prompts, and the edit hint adds nothing at all: no tool, no schema, no prompt text. It reads the file pi already named in its own error.
+When pi's own edit cannot find the old text, or finds it more than once, it reports the miss and nothing else. The retry usually starts with a re-read, and often misses again because the old text was written from memory.
 
-What it saves is a round trip per check and a read per failed edit. A rejected edit that comes back with the closest region on disk costs one retry instead of a re-read plus a retry.
+The hint appends the closest region as it reads on disk now, with line numbers and current text, so the retry copies real lines.
 
-## then_run
+Matching is by line agreement, not character similarity. Every distinctive line of the old text is looked up in the file the way pi's own matcher would read it, counting only lines of four characters or more, so a lone `}` never votes. The window of the old text's height holding the most of them wins. Under half agreeing means no region is shown, because a weak guess invites an edit against the wrong lines.
 
-`then_run` is an optional parameter on `edit` and `write`: an object with `command` and `timeout` in seconds, or the command as a plain string. It runs after the mutation succeeds and is skipped when the mutation fails.
+Line agreement hides the commonest cause. On one miss every distinctive line of a doc comment was present, because the model had re-wrapped the paragraph and written one word from memory. A line search cannot see a re-wrap, so the hint also names the lines that are not on disk at all.
 
-```text
-edit(path: "src/retry.ts", edits: [...], then_run: {command: "bun test src/retry", timeout: 120})
-```
+The hint reports and never repairs. A miss that survives pi's fuzzy matching is a real mismatch, and applying a guess would write code nobody asked for.
 
-The tool definitions are extended, not replaced. The built-in `edit` and `write` schemas keep their properties and gain an optional `then_run`, and each working directory gets its own cached definition.
+## Fusing the check
 
-Result markers are sentinels. On success the command output is appended after `[then_run:succeeded]`. On failure the mutation output is reported first, then `[then_run:failed]` and the error, all inside one thrown error, so the mutation result is never lost.
+The other round trip is the one after the write. Edit a file, call `bash` to run the test, and that is a whole provider request to learn something the edit already implied.
 
-A string carrying an object literal, `then_run: '{command: "npm test"}'`, is read for its `command` and `timeout` instead of being handed to bash, which used to run the braces and answer `command not found`. A literal naming no command is reported as a `then_run` failure after the mutation has landed, so the model is told the file changed and what the argument should have been.
+`then_run` is an optional parameter on `edit` and `write`. It runs after the mutation succeeds.
 
-Pass `then_run` when the check follows from the file the edit just changed. Use a separate `bash` call when the check spans files not yet written, or when you need to read the edit result before deciding what to run.
+```text
+edit(path: "src/retry.ts", edits: [...], then_run: {command: "bun test src/retry", timeout: 120})
+```
+
+It takes `{command, timeout}` in seconds, or the command as a plain string. On success `then_run` appends the output after `[then_run:succeeded]`. On failure it reports the mutation output first, then `[then_run:failed]` and the error, inside one thrown error, so the edit result is never lost.
 
-## The edit hint
+When the check follows from the file the edit just changed, pass `then_run`. Use a separate `bash` call when the check spans files not yet written, or when the edit result has to be read before deciding what to run.
 
-When pi's own edit cannot find the old text, or finds it more than once, the hint appends what the read was for: the closest region as it reads on disk now, with line numbers and current text, or the line of every match when the old text matched more than once. The retry copies old text out of those lines.
+`then_run` is a parameter rather than a tool because the built-in definition is spread into the extension's own. Every property pi had stays, and one optional field is added. A second tool would need its own schema, its own permission story, and a model deciding between two ways to change a file.
 
-The hint reports and never repairs. A miss that survives pi's fuzzy matching is a real mismatch, and silently applying a guess would write code nobody asked for.
+## Cost and switches
 
-A region is found by line agreement, not by character count. Every distinctive line of the old text (at least four characters, so a lone `}` never votes) is looked up in the file as pi's own matcher would read it, and the window of oldText's height holding the most of them wins. Under half agreeing means no region is shown, because a weak guess invites an edit against the wrong lines.
+The hint adds no tool, no schema and no prompt text. It reads one file pi already named in its own error.
 
-Agreement alone hides the commonest cause. On a miss where every distinctive line of a doc comment was present, the model had re-wrapped a paragraph at a different column and written one word from memory. A line-for-line search cannot see a re-wrap, so the lines that are in no way on disk are listed by name next to the region.
+`edit` gains four guideline bullets and `write` gains two. Those six bullets are the whole prompt cost of the fusion.
 
-## Cost
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `PI_HINT_EDIT_HINT` | `1` | `0`, `false`, `no` or `off` disables the hint |
+| `PI_ACTION_FUSION` | `1` | `0` disables the `then_run` parameter |
 
-- The hint reads one file that pi already named, and refuses anything over 2 MB.
-- `then_run` costs two guideline bullets on the `edit` and `write` prompts and saves one provider round trip per fused check.
-- `PI_HINT_EDIT_HINT=0` disables the hint, and accepts `false`, `no`, and `off`.
+`then_run` runs through the `bash` tool, so that tool has to be active.
 
 ## Install
 
@@ -47,3 +50,9 @@ pi install npm:@tduyng/pi-edit-path
 ```
 
 Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-edit-path`
+
+## Limits
+
+- `then_run` output keeps the last 12,000 characters, and the result says it was cut.
+- The hint refuses files over 2 MB, lists at most 80 region lines and 10 match lines.
+- The hint reads the file as it is now, which is not always what it was when the edit failed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tduyng/pi-edit-path",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Fuse the validation command into the edit that needs it, and name the region on disk a failed edit meant.",
   "keywords": [
     "pi",