Repository navigation
Releases
pi-snap-edit v5.3.0
pi-snap-edit v5.3.0
README-only maintenance release: announces the project's status and where new development happens.
Changes
- Added a prominent
IMPORTANTnotice at the top of the README: this is an experimental project, still functional, but superseded by a different Edit approach with far fewer errors. - New development now happens in pi-utils — check it out there.
- No code or behavior changes in this release.
Install
pi install npm:pi-snap-editVerification
npm run typecheckpassed.npm testpassed (0 failures).npm pack --dry-runpassed.git diff --checkpassed.
pi-snap-edit v5.2.0
pi-snap-edit v5.2.0
Teaching release, from an unplanned evaluation. A real-world 644-entry agent session (76 edit calls, all-green tests, zero corruption) still burned roughly 30% of its edit calls on retries and cleanup after ops landed in unexpected places. Diagnosis found three repeat op-construction mistakes; this release makes the tools narrate their own semantics at the exact moment an agent is about to make them. No matching or application behavior changed.
Changes
- Batch line-shift hints (
target_edit): when an earlier op in a batch changes the line count and a laterline/rangeselector misses, the error now reports the accumulated shift (earlier ops in this batch shifted line numbers by +5 - selectors apply to the state after earlier ops, so adjust them or split the batch) and, after verification, suggests the shifted line (exactly one occurrence intersecting), shifted range (at least one occurrence fully inside), or shifted line+range pair (both verified together). This unblocks the atomic-reject retry loop from the evaluated session, where the agent re-sent the same stale selector three times because the reject swallowed the feedback that would have explained the miss. - Range-selector misuse note (
target_edit): areplacewhoserangecovers more lines than the matched target while the replacement expands the match now notes that the range is an occurrence selector, not the replaced span (range 1-5 is an occurrence selector; only the matched target (line 3) was replaced - other lines in the range were left unchanged) and points toquick_editstart/endfor whole-span replaces. This was the session's dominant failure: the agent quoted a one-line target with a whole-block replacement and a wide range, then cleaned up the leftover old block six separate times. - Anchor-duplication notes (
target_edit+quick_edit):insert_after/insert_beforewarn when the edge adjacent to the anchor re-includes the anchor line (the anchor is kept, so it appears twice);quick_editEOF appends warn whenlines[0]duplicates the file's last line. Trim-equal comparison; blank edges skipped; far edges never checked (stacked closers are legitimate).
Compatibility
No API or tool-name changes. Success and failure output gained note/hint lines in the situations above; files are byte-identical to v5.1.0 for every input. Suggestions in structured error payloads are verified to round-trip (combined line+range suggestions are verified as a pair, per post-review fix) and are omitted when they cannot be verified.
Install
pi install npm:pi-snap-editVerification
npm run typecheckpassed.npm testpassed: 188 tests, up from 167 at v5.1.0.npm pack --dry-runpassed.- Live-verified by replaying the exact failing operations from the evaluated session: the stale line hint reports
shifted line numbers by +5(with the suggestion correctly omitted where the original agent's line was additionally off), the whole-block range replace emits the occurrence-selector note, and both anchor-duplication shapes emit their notes while negative cases stay silent. - Meta-evidence: while implementing these fixes the implementing agent itself hit anchor-duplication three times and the
lines-vs-replacementschema mix-up twice - each recognized and cleaned in a single turn, exactly the recovery profile the notes are designed to produce.
pi-snap-edit v5.1.0
pi-snap-edit v5.1.0
Reliability and ergonomics release. Trim matching gets an unescape parity fix and indentation adjustment, quick_edit no longer corrupts CRLF files when a replacement entry contains real newlines, and tool output was reworked around what three live agent evaluations showed agents actually struggle with. No API changes.
Changes
- Trim cascade parity: the automatic cascade now also tries the trimmed form of the unescaped target, so a target that is both escape-encoded and indentation-drifted resolves the same way as explicit
matchMode: "trim". Trim semantics are gated on the resolved occurrence shape, fixing doubled indentation onreplaceand orphaned indentation-only lines ondeletefor those matches. - Indentation adjustment on trim matches: when a multi-line replacement is written at a different indentation than the matched block, the uniform shift is applied to the remaining replacement lines so the whole block lands at the file's indentation. Non-uniform drift falls back to literal insertion.
- Leading blank lines in trim targets: whitespace-only lines are now trimmed from both edges of a target, not just the trailing edge. Blank lines inside a target still match literally.
quick_editnewline normalization: replacement entries containing real LF/CRLF newlines are split into separate lines before validation. Previously such an entry produced mixed line endings in a CRLF file and made reported line counts drift from the file.- Byte state is visible:
readoutput and edit output note CRLF line endings and missing trailing newlines when a file is not plain LF with a trailing newline.readonly claims trailing-newline state when the true end of file is visible in the result. Plain LF files are unchanged. - Guard failure recovery: guard mismatches now suggest a copy-paste
expectedStartLine/expectedEndLinewhose value is verified to round-trip through guard unescaping, and report the first differing column using whichever of the raw or unescaped guard form is closest to matching. When the guard is a prefix of the line, the missing tail is quoted instead of a column. TheexpectedStartLineMatch: "trim"hint is only printed when a trim match actually exists. - Doubled-indent warning: a raw
target_editreplacewhose match starts right after a line's indentation now warns when the replacement's first line begins with whitespace. Matching semantics are unchanged. - Diff headers use post-edit line numbers, matching the refreshed context below them; previously multi-line headers mixed pre- and post-edit coordinates and were wrong in both whenever an edit changed the line count. Operations that change more than one occurrence now report the count, and
target_editnotes moved above the diff. - Docs:
quick_editschema no longer implies a mid-file insert exists (line edits replace their span; EOF append is the only insert), and thetarget_edittargetdescription states that exact bytes are tried first so literal backslash sequences in files are matched verbatim.
Compatibility
No API or tool-name changes. Behavior differences worth knowing:
- A target with leading blank lines now matches content directly instead of requiring a preceding blank line in the file.
- Multi-line replacements through the trim tier may be re-indented to match the file instead of being inserted literally.
quick_editreplacement entries containing real newlines now produce multiple lines instead of one line with an embedded newline.- Success output gained note lines for non-default byte state, non-exact match tiers, multi-occurrence operations, and likely doubled indentation.
Install
pi install npm:pi-snap-editVerification
npm run typecheckpassed.npm testpassed: 167 tests, up from 111 at v5.0.0.npm pack --dry-runpassed.- Three live agent evaluations against fixture files (escape-heavy TypeScript, JSON, CRLF without trailing newline, tab-indented Makefile and Python) each completed 10/10 edits verified byte-exact, including one round where the agent was denied all byte inspection and relied only on tool output.
pi-snap-edit v5.0.0
pi-snap-edit v5.0.0
Breaking release. target_edit now cascades through match tiers automatically instead of requiring matchMode: "trim", and reports the tier whenever a match is not exact. Also removes substitute_edit entirely.
Changes
- Automatic match cascade for
target_edit: matching now falls through exact substring → unescaped target → whole-line trim. The trim tier only runs when both earlier tiers miss, so a unique exact hit is never diluted into an ambiguous reject. Indentation or trailing-whitespace drift succeeds without a retry, saving a read/edit round-trip. - Match tier reporting: when a match is not exact, the tool output states how it matched (
matched via trim (indentation or trailing whitespace differed)ormatched via unescape (escape sequences in target were normalized)), prefixed withop[N]in multi-op batches. Exact matches stay silent. Relaxed matching is deliberately visible so a wrong-but-plausible match can be caught rather than applied quietly. - Trim semantics gated on occurrence kind: trim behavior now keys off the resolved occurrence being a trim match rather than the caller's
matchMode. Onreplace, edge trimming keeps the file's original indentation; previously the auto path would double it. Auto-cascade and explicitmatchMode: "trim"produce byte-identical output for the same input, unless the target also matches exactly — then auto-cascade correctly resolves to the exact hit whilematchMode: "trim"ignores it by design. deleteon a trim match removes the whole line: previously it blanked the content and left an indentation-only line behind. Multi-line trim blocks remove all matched lines, and deleting the last line of a file without a trailing newline removes the preceding line terminator instead of leaving one dangling.deleteon an exact or unescaped match keeps literal substring semantics.matchModeunchanged in meaning: still accepted, still forces trim-only matching and ignores exact substring hits — useful when the target text also appears inside an indented line.- Removed
substitute_edit: unregistered as a callable tool since v3.0.0; its engine, schema, and exports are now gone. Thesubstitute_editfilter in active-tool preference is kept so saved state from older sessions is still cleaned up. - Docs: README,
target_editpromptGuidelines, and thematchModeschema description updated to describe the cascade instead of instructing callers to opt into trim.
Breaking
applySubstituteEditsand theSubstitutiontype are no longer exported.target_editsucceeds on some inputs that previously failed withtarget not found. Callers relying on strict exact-only matching should passmatchMode: "exact"-equivalent unique targets, or aline/rangeselector.target_editdeleteon a trim match now removes the whole line instead of blanking it. Callers that relied on the leftover indentation-only line must adjust.
Install
pi install npm:pi-snap-editVerification
npm run typecheckpassed.npm testpassed (106 tests).git diff --checkpassed.npm pack --dry-runpassed.- A/B verified against the previous release: exact-path behavior is unchanged across exact substring
delete,deletewith alineselector, unescapedelete, exact multi-line blockdelete, trimreplace, and triminsert_after; auto-cascade output matches explicitmatchMode: "trim"on single-line, no-indent replacement, multi-line block, and CRLF/no-trailing-newline cases; ambiguous trim matches still reject; a failing later operation still rolls back a valid earlier trim edit. - Live-tested through the registered Pi
read,quick_edit, andtarget_edittools ontmp/fixtures, verifying exact bytes for tab indentation, CRLF, no-trailing-newline, and UTF-8 content.
pi-snap-edit v4.2.1
pi-snap-edit v4.2.1
Patch release. Makes edit failures machine-readable via structured error payloads, and improves quick_edit usability with start="eof" appends, an indent_tolerant whitespace shortcut, and optional end-line/count guards — all without weakening fail-closed atomic semantics.
Changes
- Structured failures: new
SnapEditErrorwith stableerror_code, optionalcandidates/suggestedretry fields, and a trailing--- snap-edit-error ---JSON block. ExportsparseSnapEditError/SnapEditErrorfor engines, tools, and tests.quick_editandtarget_editvalidation/mismatch paths now route throughthrowEditError, keeping human diagnostic prose above the JSON. quick_editUX:- Prefer
start="eof"for appends (noexpectedStartLinerequired); legacystart=lineCount+1inserts still work. - New
whitespace="indent_tolerant"shortcut (trim guards +preserveIndent); explicitexpectedStartLineMatch/preserveIndentstill override. - Optional
expectedEndLineandexpectedLineCountguards for safer multi-line range edits. - Actionable
suggestedretry fields surfaced on errors (relocated start,indent_tolerant).
- Prefer
- Tool guidance: documented
eof, whitespace shortcut, range guards, and structured error parsing inquick_edit/target_editpromptGuidelines. - Tests: added coverage for structured parse paths,
eofappend,indent_tolerant, end/count guards, and target ambiguous/not-found structured payloads.
Install
pi install npm:pi-snap-editVerification
npm run typecheckpassed.npm testpassed (93 tests).git diff --checkpassed.npm pack --dry-runpassed.
pi-snap-edit v4.2.0
pi-snap-edit v4.2.0
Minor release. Adds matchMode=trim for whitespace-tolerant target matching, relaxes line/range selector rules for replace/delete, and surfaces multi-line diagnostic hints when a multi-line target fails to match.
Changes
matchMode: "exact" | "trim"fortarget_edit: opt-in line-level matching that compares content aftertrim()per line, preserving original indentation on replace/delete. Non-whitespace content must still match exactly; only leading/trailing line whitespace is forgiven. Match priority:exact > unescape > trim. Replaces/deletes are bounded to the trimmed content only — never consumes the line-terminating newline. Replacement leading/trailing whitespace is stripped in trim mode to avoid double-indent when agents copy indentation into the replacement.- Relaxed
line/rangeselector rules: four modes now allowed onreplace/delete—lineonly (1 occurrence intersect line),rangeonly (every occurrence in range), both (range selects + line is a validation hint: at least one occurrence must intersect it), neither (target must be unique in the file, else fail with a clear message). Removes the prior mutually-exclusive constraint that caused awkward agent errors. - Multi-line diagnostic hints: when a multi-line
target_edittarget fails to match, errors now include first/last line near matches (dice coefficient) and anchor block candidates where first + last lines match by trim. Diagnostic only; never auto-applied. Anchor block display capped at 10 lines (3 + ellipsis + 3) to keep output bounded. - Test infrastructure: added
test/eval-guidelines.tsstandalone eval harness to measure which prompt guidelines actually impact success rate (25 tasks × 12 categories × informed/naive variants). - README: aligned with the new target edit semantics and four selector modes.
Install
pi install npm:pi-snap-editVerification
npm run typecheckpassed.npm testpassed (76 tests).git diff --checkpassed.npm pack --dry-runpassed.
pi-snap-edit v4.1.0
pi-snap-edit v4.1.0
Minor release. Improves escape-heavy edit matching and preserves UTF-8 BOM across edit tools and numbered read output.
Changes
- Escaped edit targets:
quick_editexpectedStartLineandtarget_edittargettry raw match first, then JSON-style unescaped fallback (\n,\t,\\, etc.). Raw matches win over fallback to avoid double-apply on overlap. - UTF-8 BOM preservation: only one leading file-level BOM is tracked;
quick_edit,substitute_edit, andtarget_editpreserve it on write. Read hook hides the file BOM on line 1 while keeping content\uFEFFcharacters visible. - Tests: added coverage for escape guards, raw-over-fallback selectors, and byte-level BOM cases.
Install
pi install npm:pi-snap-editVerification
npm run typecheckpassed.npm testpassed (56 tests).git diff --checkpassed.npm pack --dry-runpassed.- Live-tested
read,quick_edit, andtarget_editafter Pi reload.
pi-snap-edit v4.0.0
pi-snap-edit v4.0.0
Breaking API cleanup release. Simplifies target_edit selectors and op types, improves quick_edit guard flexibility, and adds diagnostic fuzzy hints on edit failures.
Changes
target_editbreaking cleanup: removedoccurrence/count/positionparams. Replaced withline/rangeselectors andinsert_before/insert_afterop types. Removed top-levelscope.quick_edittrim guard: addedexpectedStartLineMatch: "trim"andpreserveIndent: trueto handle whitespace uncertainty without failing.- Diagnostic fuzzy hints: when
quick_editguard ortarget_edittarget fails to match, the tool now lists close matches with line numbers and snippets for faster retry. - Runtime validation:
lineandrangeselectors now validate integer/min/bounds/order. Unknown op types are explicitly rejected.
Breaking Changes
target_editno longer supportsoccurrence,count,position, or top-levelscope.target_editinsert+positionreplaced byinsert_beforeandinsert_after.
Install
pi install npm:pi-snap-editVerification
npm run typecheckpassed.npm testpassed (44 tests).git diff --checkpassed.npm pack --dry-runpassed.
pi-snap-edit v3.0.3
pi-snap-edit v3.0.3
Patch release. Fixes read hook line numbering for CRLF files so quick_edit guards copied from read output do not include hidden carriage returns.
Changes
- Normalized
readhook line splitting through the sharedsplitLineshelper. - Fixed CRLF read output so numbered lines no longer retain hidden
\rcharacters. - Preserved continuation notice handling for CRLF read output.
- Added regression tests for CRLF numbered reads and
quick_editexpectedStartLine guards copied from read output.
Install
pi install npm:pi-snap-editVerification
npm run typecheckpassed.npm testpassed (33 tests).git diff --checkpassed.npm pack --dry-runpassed.
pi-snap-edit v3.0.0
pi-snap-edit v3.0.0
Breaking release. Temporarily disables the callable substitute_edit tool while keeping its engine/export available for compatibility and rollback.
Changes
- Removed
substitute_editfrom Pi tool registration. - Removed
substitute_editfrom preferred active tools and actively filters stale activesubstitute_editentries on session start. - Kept
applySubstituteEditsexport and engine tests intact. - Updated README, AGENTS, and active-tool tests to reflect the active tool set:
quick_editandtarget_edit.
Breaking Changes
substitute_editis no longer available as a callable Pi tool.
Install
pi install npm:pi-snap-editVerification
npm run typecheckpassed.npm testpassed (31 tests).git diff --checkpassed.npm pack --dry-runpassed.