@tduyng/pi-edit-path 0.0.2 → 0.0.4

package/README.md

@@ -1,34 +1,47 @@
 # @tduyng/pi-edit-path
 
-Two halves of one edit path. `then_run` fuses the validation command into the edit that needs it, and the edit hint names 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.
 
-## then_run
+## After a failed edit
 
-`then_run` is an optional parameter on `edit` and `write`: an object with `command` and `timeout` (seconds), or the command as a plain string. It runs after the mutation succeeds and is skipped if the mutation fails.
+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.
 
-A string carrying an object literal, `then_run: '{command: "npm test"}'`, is read for its `command` and `timeout` rather than handed to bash, which used to run the braces and answer `command not found`. A string with no key in it stays the command. 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.
+The hint appends the closest region as it reads on disk now, with line numbers and current text, so the retry copies real lines.
 
-Success and failure use sentinel markers. On success the command output is appended to the mutation result preceded by `[then_run:succeeded]`. On failure the mutation output is reported first, followed by `[then_run:failed]` and the error message, all wrapped in a single thrown error so the mutation result is not lost.
+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.
 
-The tool definitions are extended, not replaced: the built-in `edit` and `write` schemas keep their properties and gain an optional `then_run`. Each working directory gets its own cached tool definition.
+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.
 
-Two guidelines ride on the tool prompts. Pass `then_run` when the check follows from the same file the edit or write just changed. Use a separate `bash` call when the check does not follow from the edit, spans files not yet written, or when the model needs to read the edit result before deciding what to run.
+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 edit hint
+## Fusing the check
 
-On a `tool_result` where pi's own edit could not find the old text or matched 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 matches more than once. The retry copies old text from those lines.
+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.
 
-The hint reports, it never repairs. A miss that survives pi's fuzzy matching is a real mismatch, and silently applying a guess there would write code nobody asked for.
+`then_run` is an optional parameter on `edit` and `write`. It runs after the mutation succeeds.
 
-A region is found by line agreement, not by character count. Every distinctive line of 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.
+```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.
+
+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.
+
+`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.
 
-Agreement alone hides the commonest cause. On a miss where every distinctive line of a doc comment was present in the file, 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.
+## Cost and switches
 
-## Cost
+The hint adds no tool, no schema and no prompt text. It reads one file pi already named in its own error.
 
-The hint adds no tool, no schema and no prompt text. It reads the file pi already named in the error. A file over 2MB is not read. `then_run` costs two guideline bullets on the `edit` and `write` prompts and saves one provider round trip per fused check.
+`edit` gains four guideline bullets and `write` gains two. Those six bullets are the whole prompt cost of the fusion.
 
-`PI_HINT_EDIT_HINT=0` disables the hint. It accepts `false`, `no`, and `off` too.
+| 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 |
+
+`then_run` runs through the `bash` tool, so that tool has to be active.
 
 ## Install
 
@@ -37,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,7 +1,7 @@
 {
   "name": "@tduyng/pi-edit-path",
-  "version": "0.0.2",
-  "description": "Two halves of one edit path: fuse the validation command into the edit that needs it, and name the region on disk a failed edit meant so the retry lands without a re-read.",
+  "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",
     "pi-package",