dsh-better-edit 0.2.2 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +33 -0
- package/README.md +317 -240
- package/README.zh.md +19 -11
- package/lib/constants.js +3 -1
- package/lib/contract.js +159 -63
- package/lib/drift.js +5 -98
- package/lib/dsh-context.js +2 -24
- package/lib/edit-engine.js +9 -8
- package/lib/edit-pipeline.js +3 -121
- package/lib/edit-response.js +16 -8
- package/lib/file-kind.js +6 -121
- package/lib/file-reader.js +4 -77
- package/lib/file-view.js +486 -0
- package/lib/guidance/index.js +8 -0
- package/lib/guidance/materialize.js +212 -0
- package/lib/guidance/parse.js +80 -0
- package/lib/guidance/resolve.js +116 -0
- package/lib/guidance.js +6 -388
- package/lib/hash-store.js +6 -4
- package/lib/hashline/alphabet.js +2 -6
- package/lib/hashline/anchor-pipeline.js +786 -0
- package/lib/hashline/apply.js +2 -223
- package/lib/hashline/hash-assign.js +255 -0
- package/lib/hashline/hash.js +67 -29
- package/lib/hashline/hasher.js +2 -23
- package/lib/hashline/index.js +9 -4
- package/lib/hashline/parse.js +2 -35
- package/lib/hashline/pure.js +2 -213
- package/lib/hashline/resolve.js +3 -361
- package/lib/hashline/served.js +2 -120
- package/lib/index.js +1 -3
- package/lib/mutation.js +266 -0
- package/lib/noop-guard.js +20 -0
- package/lib/preview-controller.js +65 -0
- package/lib/prompts.js +14 -20
- package/lib/read-and-serve.js +23 -23
- package/lib/read-render.js +3 -139
- package/lib/served-store.js +2 -216
- package/lib/session-view.js +332 -0
- package/lib/tool-batch-edit.js +9 -10
- package/lib/tool-edit.js +73 -129
- package/lib/tool-read.js +3 -5
- package/lib/tool-undo.js +16 -10
- package/lib/truncate.js +3 -95
- package/lib/types/constants.d.ts +2 -0
- package/lib/types/contract.d.ts +120 -15
- package/lib/types/drift.d.ts +5 -29
- package/lib/types/dsh-context.d.ts +2 -20
- package/lib/types/edit-engine.d.ts +2 -2
- package/lib/types/edit-pipeline.d.ts +3 -44
- package/lib/types/file-kind.d.ts +6 -18
- package/lib/types/file-reader.d.ts +4 -45
- package/lib/types/file-view.d.ts +139 -0
- package/lib/types/guidance/index.d.ts +8 -0
- package/lib/types/guidance/materialize.d.ts +23 -0
- package/lib/types/guidance/parse.d.ts +36 -0
- package/lib/types/guidance/resolve.d.ts +55 -0
- package/lib/types/guidance.d.ts +6 -127
- package/lib/types/hashline/alphabet.d.ts +1 -5
- package/lib/types/hashline/anchor-pipeline.d.ts +127 -0
- package/lib/types/hashline/apply.d.ts +1 -22
- package/lib/types/hashline/hash-assign.d.ts +25 -0
- package/lib/types/hashline/hash.d.ts +8 -9
- package/lib/types/hashline/hasher.d.ts +1 -8
- package/lib/types/hashline/index.d.ts +12 -4
- package/lib/types/hashline/parse.d.ts +1 -7
- package/lib/types/hashline/pure.d.ts +1 -26
- package/lib/types/hashline/resolve.d.ts +1 -58
- package/lib/types/hashline/served.d.ts +1 -43
- package/lib/types/mutation.d.ts +131 -0
- package/lib/types/noop-guard.d.ts +29 -0
- package/lib/types/preview-controller.d.ts +33 -0
- package/lib/types/prompts.d.ts +9 -9
- package/lib/types/read-and-serve.d.ts +6 -5
- package/lib/types/read-render.d.ts +3 -18
- package/lib/types/served-store.d.ts +2 -81
- package/lib/types/session-view.d.ts +92 -0
- package/lib/types/tool-edit.d.ts +3 -14
- package/lib/types/truncate.d.ts +3 -29
- package/lib/types/validation.d.ts +6 -7
- package/lib/types/workspace.d.ts +2 -21
- package/lib/validation.js +6 -33
- package/lib/workspace.js +2 -27
- package/lib/write-hook.js +2 -2
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -3,27 +3,33 @@
|
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
<h1 align="center">dsh-better-edit</h1>
|
|
6
|
-
|
|
7
6
|
<p align="center">
|
|
8
7
|
<strong>A better edit tool for DeepSeek Harness<br>
|
|
9
8
|
Powered by hash‑anchored positioning — not by line numbers, not by string replacement, fewer tokens, more context space for real work.</strong>
|
|
10
9
|
</p>
|
|
11
|
-
|
|
12
10
|
<p align="center">
|
|
13
11
|
<strong>English</strong> ·
|
|
14
12
|
<a href="README.zh.md">简体中文</a>
|
|
15
13
|
</p>
|
|
16
14
|
|
|
15
|
+
<p align="center">
|
|
16
|
+
<a href="#why-you-need-this"><img src="https://img.shields.io/badge/why-hashline-blue?style=flat" alt="why hashline"></a>
|
|
17
|
+
<a href="#quick-start"><img src="https://img.shields.io/badge/quick_start-30s-brightgreen?style=flat" alt="quick start 30s"></a>
|
|
18
|
+
<a href="#comparison"><img src="https://img.shields.io/badge/correctness-23%2F23-success?style=flat" alt="23/23 battery"></a>
|
|
19
|
+
</p>
|
|
20
|
+
|
|
17
21
|
<p align="center">
|
|
18
22
|
<a href="#quick-start">Quick Start</a> •
|
|
19
23
|
<a href="#why-hashline">Why Hashline</a> •
|
|
20
|
-
<a href="#benchmark">Benchmark</a> •
|
|
21
24
|
<a href="#tools">Tools</a> •
|
|
25
|
+
<a href="#comparison">Comparison</a> •
|
|
26
|
+
<a href="#how-anchors-work">How Anchors Work</a> •
|
|
27
|
+
<a href="#development">Development</a> •
|
|
22
28
|
<a href="#acknowledgments">Acknowledgments</a>
|
|
23
29
|
</p>
|
|
24
30
|
|
|
25
31
|
<p align="center">
|
|
26
|
-
<img src="https://img.shields.io/badge/version-0.1
|
|
32
|
+
<img src="https://img.shields.io/badge/version-0.3.1-blue.svg" alt="Version">
|
|
27
33
|
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
|
|
28
34
|
<img src="https://img.shields.io/badge/DeepSeek_Harness-Plugin-blueviolet.svg" alt="DeepSeek Harness Plugin">
|
|
29
35
|
<img src="https://img.shields.io/npm/v/dsh-better-edit" alt="npm version">
|
|
@@ -37,26 +43,38 @@
|
|
|
37
43
|
|
|
38
44
|
---
|
|
39
45
|
|
|
40
|
-
> *"The harness — not the model — is the bottleneck."*
|
|
41
|
-
>
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
replace-style edits. **dsh-better-edit** goes deeper. Every line of a file gets a unique 3-character
|
|
46
|
-
content hash, and edits target hashes. The old text is never echoed, anchors survive edits, and every
|
|
47
|
-
resolved range is verified against exactly what the model saw — wrong-line edits cannot silently land.
|
|
46
|
+
> *"The harness — not the model — is the bottleneck."* — Can Bölük, [*The Harness Problem*](https://stencil.so/blog/the-harness-problem)
|
|
47
|
+
>
|
|
48
|
+
> **This is the harness fix.** Content hashes replace line numbers — an edit above never shifts the anchor below. Every range is verified against what the agent actually saw. Stale or unseen lines are hard-rejected with fresh anchors to retry — no `read` needed.
|
|
49
|
+
>
|
|
50
|
+
> **3 tool calls vs 6 · -55.8% tokens · 23/23 correctness.** Same external-drift refactor, same correct file (single stochastic run vs OMP; [full method](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/results/2026-08-17-practical-token-benchmark.md)). Benchmark envelope numbers are deterministic — see [Benchmark](#benchmark).
|
|
48
51
|
|
|
49
52
|
## Why you need this
|
|
50
53
|
|
|
51
|
-
|
|
54
|
+
**If you've watched an agent corrupt a file because `line 47` became `line 74` after an insert — this is for you.**
|
|
55
|
+
|
|
56
|
+
| Before: `str_replace` / line numbers | After: hashline `edit` |
|
|
57
|
+
| --- | --- |
|
|
58
|
+
| Model re-types old code (output billed ~5-6× input) | Sends two 3-char hashes — old text is never echoed |
|
|
59
|
+
| One insert above shifts every number below → wrong line lands silently | Anchors are content addresses → edits above don't move anchors below |
|
|
60
|
+
| No check that the range matches what was shown | Every line verified against served rows; `[E_RANGE_STALE]`/`[E_RANGE_UNSERVED]` reject before any write, then **reject-and-serve** returns fresh `HASH│content` to retry |
|
|
61
|
+
|
|
62
|
+
> [!TIP]
|
|
63
|
+
> **Shining points — honest and measured:**
|
|
64
|
+
>
|
|
65
|
+
> - **Self-healing, not silent.** External edits never get overwritten — stale ranges are rejected and re-served as fresh `HASH│content` to retry; orphaned serves heal without a full re-read (ADR-0008). Fail-closed, not auto-merge.
|
|
66
|
+
> - **Formatter-tolerant.** ASCII-whitespace-insensitive anchors survive `prettier`/`black`/`eslint --fix` between edits (`formatOnSave`, watcher, CI). Linter-only assumption — whitespace inside string literals is not distinguished (ADR-0005).
|
|
67
|
+
> - **Chained & batched, no re-read ritual.** Anchors for untouched lines stay valid; diff/echo/reject rows count as serves. `edit` batches up to 32 same-file edits atomically (`[E_BATCH_ABORT]`), ~-40% envelope vs `str_replace` on the pinned 12-edit corpus.
|
|
68
|
+
> - **Read guard enforced.** Never edits what it hasn't seen — `[E_RANGE_UNSERVED]`/`[E_RANGE_UNVERIFIED]`/`[E_STALE_ANCHOR]` reject before any write, then `reject-and-serve`.
|
|
69
|
+
> - **Fewer round-trips in practice.** Dated run: **3 calls vs 6** for the OMP wrapper on the same external-drift refactor, same correct file; envelope vs `str_replace` is the durable number — reproducible via the upstream battery (same hashline algorithm, [method](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/results/2026-08-17-practical-token-benchmark.md)). Correctness `23/23` deterministic.
|
|
52
70
|
|
|
53
|
-
|
|
71
|
+
Not for one-line touch-ups (near parity) or brand-new files (`write`). It pays off in long sessions and structural edits — anywhere an edit must not land on the wrong line.
|
|
54
72
|
|
|
55
|
-
|
|
73
|
+
> Deep dive: <a href="#why-hashline">Why Hashline</a> · <a href="#comparison">Comparison</a> · <a href="benchmark/README.md">Benchmark</a>
|
|
56
74
|
|
|
57
|
-
## Quick Start
|
|
75
|
+
## Quick Start — from install to verified edit in 30s
|
|
58
76
|
|
|
59
|
-
### Install
|
|
77
|
+
### Install (pick one)
|
|
60
78
|
|
|
61
79
|
```sh
|
|
62
80
|
npx @deepseek-ai/dsh plugin --profile web add github:Rianico/dsh-better-edit # from github
|
|
@@ -64,7 +82,7 @@ npx @deepseek-ai/dsh plugin --profile web add dsh-better-edit # from npm
|
|
|
64
82
|
npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-better-edit # from a local checkout
|
|
65
83
|
```
|
|
66
84
|
|
|
67
|
-
The profile's next session runs with the hashline tools installed. To verify the layer is active:
|
|
85
|
+
No config. The profile's next session runs with the hashline tools installed. To verify the layer is active:
|
|
68
86
|
|
|
69
87
|
```sh
|
|
70
88
|
dsh --profile <name> --dump-config # shows a "# == dsh-better-edit" layer
|
|
@@ -76,6 +94,8 @@ dsh --profile <name> --dump-config # shows a "# == dsh-better-edit" layer
|
|
|
76
94
|
| Profile | a dsh profile (`dsh plugin` initializes one on first use) |
|
|
77
95
|
| Backends | sandboxed / remote filesystems supported (writes go through `ctx.fs`) |
|
|
78
96
|
|
|
97
|
+
### See it work
|
|
98
|
+
|
|
79
99
|
`read` returns every line prefixed by its hash — the hash *is* the line's address:
|
|
80
100
|
|
|
81
101
|
```text
|
|
@@ -87,242 +107,275 @@ kQm│}
|
|
|
87
107
|
`edit` targets a range of hashes, so edits always land on the lines you meant:
|
|
88
108
|
|
|
89
109
|
```json
|
|
90
|
-
{
|
|
91
|
-
"path": "src/main.ts",
|
|
92
|
-
"remove_from": "szJ",
|
|
93
|
-
"remove_to": "szJ",
|
|
94
|
-
"replacement_text": " console.log('hi');"
|
|
95
|
-
}
|
|
110
|
+
{ "path": "src/main.ts", "edits": [["szJ", "szJ", " console.log('hi');"]] }
|
|
96
111
|
```
|
|
97
112
|
|
|
98
|
-
and
|
|
113
|
+
and returns a diff with fresh anchors, so the next edit verifies cleanly with no re-read:
|
|
99
114
|
|
|
100
115
|
```text
|
|
101
|
-
|
|
116
|
+
- szJ │ console.log("world");
|
|
102
117
|
+ a3m │ console.log('hi');
|
|
103
118
|
kQm │ }
|
|
104
119
|
```
|
|
105
120
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
The `tool:read` / `tool:edit` / `tool:batch_edit` / `tool:undo_last_edit` guidance sections are
|
|
109
|
-
plain-markdown files, overridable per agent preset. Override files live in the plugin's shared
|
|
110
|
-
home — never the workspace store:
|
|
121
|
+
Chained edits stay cheap — anchors for untouched lines remain valid, diff/echo rows count as serves, and `read` becomes on-demand recovery, not a ritual. Try batching — one `edit` call, same-file, atomic:
|
|
111
122
|
|
|
112
|
-
```
|
|
113
|
-
|
|
123
|
+
```json
|
|
124
|
+
{ "path": "src/main.ts", "edits": [["a1b", "a1b", "new line 1\n"], ["c3d", "c3d", "new line 2"]] }
|
|
114
125
|
```
|
|
115
126
|
|
|
116
|
-
|
|
127
|
+
One fails, none write (`[E_BATCH_ABORT]`).
|
|
117
128
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
| `read.md` | `tool:read` | 130 |
|
|
121
|
-
| `edit.md` | `tool:edit` | 131 |
|
|
122
|
-
| `batch_edit.md` | `tool:batch_edit` | 132 |
|
|
123
|
-
| `undo_last_edit.md` | `tool:undo_last_edit` | 133 |
|
|
129
|
+
> [!TIP]
|
|
130
|
+
> **Want proof before you install?** The upstream [23/23 tool battery](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/README.md) runs with no LLM — stale edits are rejected before they corrupt a file, on every run. Same hashline algorithm, same verification.
|
|
124
131
|
|
|
125
|
-
|
|
126
|
-
`minimal/`, `cordis/` — each with the compiled guidance as editable files (plus
|
|
127
|
-
`order` front-matter), so every preset's guidance starts editable rather than
|
|
128
|
-
blank. A `README.md` at the plugin-home root documents the scheme. Files are
|
|
129
|
-
seeded once and never rewritten, so your edits survive — a reset is the one
|
|
130
|
-
exception (see *Reset / restore defaults* below). A preset directory may
|
|
131
|
-
hold only the sections you want to override — the rest fall through to the
|
|
132
|
-
compiled defaults.
|
|
132
|
+
## Why Hashline
|
|
133
133
|
|
|
134
|
-
|
|
135
|
-
|
|
134
|
+
**Correctness, not just brevity.** Every resolved edit range is verified against the
|
|
135
|
+
served rows — what `read`, a post-edit diff, or a rejection echo actually showed the model.
|
|
136
|
+
A line inside the range that changed on disk since it was served, or was never served, is
|
|
137
|
+
hard-rejected before any file I/O: `[E_RANGE_STALE]` / `[E_RANGE_UNSERVED]` /
|
|
138
|
+
`[E_RANGE_UNVERIFIED]`, and the current range is echoed as fresh `HASH│content` rows. The
|
|
139
|
+
retry needs no `read`. Served state is session-scoped, so sub-agent serves never validate the main session's edits and vice versa.
|
|
136
140
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
+
**Content-addressed anchors.** Anchors are derived from line content (ASCII-whitespace
|
|
142
|
+
stripped), not position: edit one part of a file and the hashes of the rest stay put, so
|
|
143
|
+
chained edits need no re-reads. Re-inserting identical text keeps its hash — "edit X with
|
|
144
|
+
X" doesn't rotate the anchor. Anchors are unique by construction — repeated `}` or
|
|
145
|
+
`import` lines never share one.
|
|
141
146
|
|
|
142
|
-
|
|
143
|
-
|
|
147
|
+
**Chained edits without re-reading.** Post-edit diff rows, auto-read rows, and rejection
|
|
148
|
+
echoes all count as serves. `read` is on-demand recovery, not a per-edit ritual.
|
|
144
149
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
user-authored one) falls back to the compiled defaults unless you copy a seeded
|
|
149
|
-
dir to its name. A deployment without the `agentPresets` service (no preset
|
|
150
|
-
roster) keeps the compiled defaults and never touches these files; presets are
|
|
151
|
-
never required.
|
|
150
|
+
**Stop the loop.** A no-op edit reports `No changes made` and leaves anchors alone; the
|
|
151
|
+
same no-op re-sent three times is refused (`[E_NOOP_LOOP]`). `edit` applies up to 32
|
|
152
|
+
edits atomically — any stale item aborts the whole batch with `[E_BATCH_ABORT]`.
|
|
152
153
|
|
|
153
|
-
###
|
|
154
|
+
### Token economics: envelope savings
|
|
154
155
|
|
|
155
|
-
|
|
156
|
-
guidance and order: the default renders at session-start, and the file re-seeds
|
|
157
|
-
at next boot.
|
|
156
|
+
The compact JSON contract is primarily a **token-saving envelope change**. It removes repeated field names and escaped wrapper syntax while leaving the verified edit semantics unchanged:
|
|
158
157
|
|
|
159
|
-
-
|
|
160
|
-
-
|
|
161
|
-
- **Broken fence = fast fail.** A `---` fence that does not parse (missing closing `---`, non-integer `order`, unknown key) is rejected: the malformed text is never injected into the context, the compiled default renders, a warning names the file and the reason, and the file is left untouched on disk for repair.
|
|
162
|
-
- **Shipped vs custom.** Shipped preset files (`standard`, `code`, `minimal`, `cordis`) re-seed at boot; a deleted custom-preset override stays absent — absence is no override. Deleting a whole `<preset>/` directory re-seeds all four section files at boot (shipped presets).
|
|
163
|
-
- **Reset restores the current bundle defaults** — a plugin upgrade yields new defaults.
|
|
158
|
+
- `edit` is one uniform payload: `{ "path": path, "edits": [[from, to, replacement], …] }` — `path` hoisted, arity by `edits.length`;
|
|
159
|
+
- replacement text is emitted once, and the old text is never repeated in the call.
|
|
164
160
|
|
|
165
|
-
|
|
161
|
+
#### Theoretical benchmark — serialized envelopes
|
|
166
162
|
|
|
167
|
-
|
|
163
|
+
This benchmark counts only the serialized edit payloads, not model reasoning, tool descriptions, reads, retries, or cache traffic. Same hashline algorithm as upstream — numbers reproduced from [`pi-better-edit/benchmarks/results/`](https://github.com/Rianico/pi-better-edit/tree/main/benchmarks/results) (pinned 12-edit corpus, `cl100k_base`):
|
|
164
|
+
|
|
165
|
+
| snapshot | `str_replace` | pi/dsh-better-edit: `edit` | pi/dsh-better-edit: `edit` (multi-item) | OMP: per-edit | OMP: one batch |
|
|
166
|
+
| --- | ---: | ---: | ---: | ---: | ---: |
|
|
167
|
+
| external pinned 12-edit corpus, current-envelope recount | 1,015 | 609 (**-40.0%**) | 582 (**-42.7%**) | 590 (**-41.9%**) | 480 (**-52.7%**) |
|
|
168
|
+
| local 12-edit configuration snapshot | 358 | 272 (**-24.0%**) | 241 (**-32.7%**) | 268 (**-25.1%**) | 180 (**-49.7%**) |
|
|
169
|
+
|
|
170
|
+
All percentages are savings against the `str_replace` value in the same row. The external row uses the pinned corpus, current object-root tuple envelopes, and current 3-character anchors. The local row is reproducible with `npm run benchmark` in the upstream repo; correctness is measured separately with the battery.
|
|
171
|
+
|
|
172
|
+
#### Practical benchmark — coding-agent session
|
|
173
|
+
|
|
174
|
+
This benchmark measures a real coding-agent loop rather than serialized envelopes. The practical advantage is round-trip efficiency: hashline completed the scenario in **3 tool calls**, versus **6 for OMP**. Upstream runs `pi` with `opencode-go/gpt-5.6-luna` at `high` thinking. Same algorithm downstream — we reference the upstream dated artifact:
|
|
168
175
|
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
|
195
|
-
|
|
|
196
|
-
|
|
|
197
|
-
|
|
|
198
|
-
|
|
|
199
|
-
|
|
|
200
|
-
|
|
|
201
|
-
|
|
|
202
|
-
|
|
|
203
|
-
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
[
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
176
|
+
| engine | tool calls | total tokens | saved vs OMP baseline | final correctness |
|
|
177
|
+
| --- | ---: | ---: | ---: | :---: |
|
|
178
|
+
| OMP patch wrapper | **6** | 28,467 | 0.0% | ✅ |
|
|
179
|
+
| hashline `edit` (multi-item) | **3 (fewest)** | 12,593 | **-55.8%** | ✅ |
|
|
180
|
+
|
|
181
|
+
Both engines preserved the external change and produced the expected final file in this sample. This result is one stochastic model run; it must not be read as a universal performance claim. Latest dated artifact: [2026-08-17 practical token benchmark](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/results/2026-08-17-practical-token-benchmark.md) · [hashline library battery](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/results/2026-08-17-hashline-library.md) · [tool battery](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/results/2026-08-17-tool-battery.md).
|
|
182
|
+
|
|
183
|
+
> **Scope & honesty.** These numbers are **payload + round-trip** measures, not throughput claims. The benchmark payload is deterministic; the practical run is stochastic. Dated results live upstream in `benchmarks/results/`; we do not re-run locally because the algorithm is identical.
|
|
184
|
+
|
|
185
|
+
## Tools
|
|
186
|
+
|
|
187
|
+
| Tool | What it does |
|
|
188
|
+
| ------ | -------------- |
|
|
189
|
+
| `read` | Returns a text file with every line as `HASH│content`. `offset` (1-based), `limit`. Paged output ends with `[Showing lines N-M of T. Use offset=… to continue.]`. Lines >200KB shown as a marker with a `sed` hint — hash anchors need full lines. |
|
|
190
|
+
| `read_skill` | Same file read as plain text — no `HASH│` prefixes, no served rows. For skill content (SKILL.md or any file); records no serves, so editing a file read this way starts with a `[E_RANGE_UNSERVED]` serve on the first edit. |
|
|
191
|
+
| `edit` | An object-root payload `{ "path": path, "edits": [[remove_from, remove_to, replacement_text], …] }`; the path may be `null` for anchor-based inference. A single item edits one range; several items batch same-file edits atomically (up to 32). Verifies every line of each inclusive range and reject-and-serve returns fresh anchors. |
|
|
192
|
+
| `undo_last_edit` | `{ path }` restores the most recent successful edit with its original content, BOM, line endings, and anchors; persisted across restarts. |
|
|
193
|
+
|
|
194
|
+
`edit` accepts `{ "path": path, "edits": [[remove_from, remove_to, replacement_text], …] }`. The path
|
|
195
|
+
position is a non-empty string or `null` for unique anchor-based inference. Each range is inclusive,
|
|
196
|
+
and an empty replacement deletes the range. All items are checked before file I/O and applied
|
|
197
|
+
atomically to that one file — one item per call is the norm, several same-file items batch in one call.
|
|
198
|
+
|
|
199
|
+
### Error codes
|
|
200
|
+
|
|
201
|
+
| Code | Meaning |
|
|
202
|
+
| --- | --- |
|
|
203
|
+
| `[E_BAD_SHAPE]` | The payload is not the fixed tuple shape, or a tuple member has an unknown, missing, or wrongly-typed value. |
|
|
204
|
+
| `[E_BAD_REF]` | An anchor in the inclusive range is not a bare 3-char hash. |
|
|
205
|
+
| `[E_STALE_ANCHOR]` | An anchor does not match any line in the current file; call `read` for fresh anchors. |
|
|
206
|
+
| `[E_AMBIGUOUS_ANCHOR]` | An anchor matches multiple lines; call `read` for fresh anchors. |
|
|
207
|
+
| `[E_INVALID_PATCH]` | A `replacement_text` line is a diff-preview row (`+HASH│`, `-HASH│`, `- │`). The marker is stripped automatically with a warning. |
|
|
208
|
+
| `[E_BARE_HASH_PREFIX]` | A `replacement_text` line starts with a hash-like `HASH│` prefix. The prefix is stripped automatically with a warning. |
|
|
209
|
+
| `[E_BAD_OP]` | Range start line is after range end line. The pair is swapped automatically with a warning. |
|
|
210
|
+
| `[E_WOULD_EMPTY]` | An edit would empty a non-empty file; use `write` instead. |
|
|
211
|
+
| `[E_NOT_FOUND]` | The path does not exist. |
|
|
212
|
+
| `[E_ACCESS]` | The path is not readable or writable. |
|
|
213
|
+
| `[E_NOT_TEXT]` | The path is a directory, binary file, image, or UTF-16/UTF-32 encoded text; hashline editing only supports text files. |
|
|
214
|
+
| `[E_NOT_OBSERVED]` | The file has not been observed in this session (read-before-write); call `read` first. |
|
|
215
|
+
| `[E_UNDO_STALE]` | `undo_last_edit` refused: the file was modified or deleted after the last edit. |
|
|
216
|
+
| `[E_UNDO_UNAVAILABLE]` | Undo history could not be persisted to the hash store; the `edit` was refused and the file was left unchanged. |
|
|
217
|
+
| `[E_FILE_TOO_LARGE]` | The file exceeds the 238,328-line hashline limit. |
|
|
218
|
+
| `[E_RANGE_STALE]` | A line inside the resolved edit range changed on disk since it was served (read output, diff, or rejection feedback). The edit is refused and the current range is echoed as fresh `HASH│content` rows; retry with those rows (no `read` needed). |
|
|
219
|
+
| `[E_RANGE_UNSERVED]` | A line inside the resolved edit range was never served to the model (paged reads, truncated output). The edit is refused and the current range is echoed as fresh `HASH│content` rows. |
|
|
220
|
+
| `[E_RANGE_UNVERIFIED]` | A boundary anchor (`remove_from`/`remove_to`) has no served position or was served at multiple positions, so the range cannot be verified against served state. The edit is refused and the current range is echoed as fresh `HASH│content` rows. |
|
|
221
|
+
| `[E_NOOP_LOOP]` | The exact same edit (same path, anchors, and replacement) was re-sent and produced no changes 3 consecutive times — the range already contains the replacement. The edit is refused and the current range is echoed as fresh `HASH│content` rows. |
|
|
222
|
+
| `[E_BATCH_ABORT]` | A multi-item `edit` call was rejected as a whole: an item failed validation or served-state verification. Nothing was written; the failing item's current range is echoed as fresh `HASH│content` rows. |
|
|
223
|
+
|
|
224
|
+
## Comparison
|
|
225
|
+
|
|
226
|
+
### Capability comparison
|
|
227
|
+
|
|
228
|
+
| | **dsh-better-edit** (this) | @oh-my-pi/hashline | `str_replace` (Claude Code / Codex) |
|
|
229
|
+
| --- | --- | --- | --- |
|
|
230
|
+
| Layer | dsh tools: `read` / `read_skill` / `edit` / `undo_last_edit` | patch-engine library: `Patcher` / `Patch` / `Filesystem` / `SnapshotStore` | built-in `str_replace` |
|
|
231
|
+
| Address format | `HASH│` — 3-char content hash, no line number | `[path#tag]` — full-file content tag + line numbers | text match |
|
|
232
|
+
| Whitespace-insensitive anchors | ✅ all ASCII whitespace stripped — survives `prettier`/`black`/`eslint --fix` | ~ n/a (anchors are line numbers) | ❌ |
|
|
233
|
+
| Duplicate lines | ✅ unique per line (collision-resolved); ambiguity → `[E_AMBIGUOUS_ANCHOR]` | ~ position-based — repeats fine, position unverified | ❌ first occurrence |
|
|
234
|
+
| Verified against what the model saw | ✅ every resolved line, per session — `[E_RANGE_STALE]`/`[E_RANGE_UNSERVED]` reject before write | ~ seen-lines provenance + file-version tag (H7) | ❌ first match wins |
|
|
235
|
+
| Stale interior | ✅ reject + fresh anchors (`[E_RANGE_STALE]`) | ~ recovery-with-warning, else `MismatchError` | ❌ may overwrite |
|
|
236
|
+
| Blind edit — lines never shown | ✅ hard reject (`[E_RANGE_UNVERIFIED]` / `[E_RANGE_UNSERVED]`) | ~ reject when seen-lines recorded (H7) | ❌ |
|
|
237
|
+
| Batch atomicity | ✅ `edit` multi-item — all-or-nothing, `[E_BATCH_ABORT]` | ✅ multi-section preflight (H8) | ❌ |
|
|
238
|
+
| Undo (persisted) | ✅ survives restarts | ❌ none | ❌ |
|
|
239
|
+
| Sub-agent session isolation | ✅ session-keyed served state | ~ | — |
|
|
240
|
+
| Deterministic battery | ✅ 23/23 | ✅ 10/10 library (own seam) | — |
|
|
241
|
+
| Runtime | dsh (Node) | Bun ≥ 1.3.14 (TS source) | — |
|
|
242
|
+
|
|
243
|
+
> `~` = occasionally / inconsistently. `—` = not specified / not applicable.
|
|
244
|
+
|
|
245
|
+
### Different jobs, same lineage
|
|
246
|
+
|
|
247
|
+
Both this plugin and `@oh-my-pi/hashline` descend from the harness-problem insight that
|
|
248
|
+
the model should never re-type old code, but they are different layers.
|
|
249
|
+
|
|
250
|
+
`@oh-my-pi/hashline` is a **patch-language library**: `[path#tag]` headers bind every hunk
|
|
251
|
+
to a full-file content hash, `PUT N.=M:` addresses lines by number, and it ships multi-hunk
|
|
252
|
+
documents, a pluggable filesystem for any backend (disk, in-memory, network), and
|
|
253
|
+
session-aware 3-way-merge recovery on stale tags. Its payload per edit is lighter and it cannot
|
|
254
|
+
be confused by repeated text — the line number is unambiguous.
|
|
255
|
+
This plugin is a **dsh tool pair**: `read` hands the model 3-char content hashes, `edit`
|
|
256
|
+
takes two of them, and every resolved line is verified against the served state — no line
|
|
257
|
+
numbers to renumber, no tag to refetch, a wrong anchor can never land on the wrong line,
|
|
258
|
+
and `undo_last_edit` survives restarts. Its trade-offs: a JSON envelope per edit costs a
|
|
259
|
+
little payload, and it lives inside dsh (Node) rather than as a standalone patcher (Bun). Pick
|
|
260
|
+
hashline-the-library for a cross-backend patch format; pick hashline-the-tool for verified,
|
|
261
|
+
content-addressed edits in your agent. Syntax-aware structural edits and file-lifecycle operations
|
|
262
|
+
remain outside this verified line-range contract.
|
|
263
|
+
|
|
264
|
+
### What you get
|
|
265
|
+
|
|
266
|
+
- **Verified before it writes** — every line of the resolved range is checked against served rows; stale or never-served interiors are hard-rejected (`[E_RANGE_STALE]`/`[E_RANGE_UNSERVED]`/`[E_RANGE_UNVERIFIED]`) and re-served as fresh anchors.
|
|
267
|
+
- **Session-keyed** — sub-agent serves never validate the main session's edits and vice versa.
|
|
268
|
+
- **Drift notices** — served territory outside the range that changed on disk is reported once per episode, not as a warning.
|
|
269
|
+
- **Chained without re-reads** — diff, auto-read, and rejection rows all count as serves.
|
|
270
|
+
- **Atomic batch** — up to 32 same-file edits in one `edit` call, all-or-nothing with `[E_BATCH_ABORT]`.
|
|
271
|
+
- **Formatter-tolerant** — ASCII-whitespace-insensitive anchors survive re-indents; unique by construction (bitset probing).
|
|
222
272
|
|
|
223
273
|
### Correctness in edge cases
|
|
224
274
|
|
|
225
|
-
The
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
repeated text), and what each tool does when they hit:
|
|
275
|
+
The battery below measures *behavior*, where the two hashline implementations actually
|
|
276
|
+
diverge. These are the real failure modes from the harness-problem literature, and what
|
|
277
|
+
each tool does when they hit:
|
|
229
278
|
|
|
230
|
-
| Edge case | hashline `edit` (this
|
|
279
|
+
| Edge case | hashline `edit` (this) | @oh-my-pi/hashline patch |
|
|
231
280
|
| --- | --- | --- |
|
|
232
|
-
| Wrong address (off-by-one anchor / line number) | **Impossible** — anchors resolve to specific lines; every resolved line is verified against served state, rejected
|
|
233
|
-
| File changed on disk after the model's view | Hard reject + fresh anchors echoed (reject-and-serve); retry needs no `read` | Tag mismatch → refuse **or best-effort 3-way merge
|
|
234
|
-
| An edit above shifts the file | Nothing shifts — anchors are content addresses; the diff serves fresh anchors | **Every edit renumbers** —
|
|
281
|
+
| Wrong address (off-by-one anchor / line number) | **Impossible** — anchors resolve to specific lines; every resolved line is verified against served state, rejected before anything is written | **Possible** — a wrong line number against a current tag applies silently at the wrong place; the tag proves the file version, never the lines |
|
|
282
|
+
| File changed on disk after the model's view | Hard reject + fresh anchors echoed (reject-and-serve); retry needs no `read` | Tag mismatch → refuse **or** best-effort 3-way merge onto unknown current content, with an explicit recovery banner |
|
|
283
|
+
| An edit above shifts the file | Nothing shifts — anchors are content addresses; the diff serves fresh anchors | **Every edit renumbers** — the format's own #1 rule is "re-ground after every edit"; the model carries the bookkeeping |
|
|
235
284
|
| Repeated / identical text | Per-line hashes are unique (collision-resolved); ambiguity → `[E_AMBIGUOUS_ANCHOR]` | Position-based, so repeats don't confuse it — but the position itself is unverified |
|
|
236
|
-
| Lines never shown to the model | `[E_RANGE_UNSERVED]` — hard reject with fresh anchors | Undisplayed hunks rejected — same reliance on the model knowing what it saw |
|
|
237
|
-
|
|
|
238
|
-
| Multi-edit batch fails mid-way | `batch_edit` — atomic, all-or-nothing; the failing item is echoed as fresh serves | Multi-section patches preflighted up front — also atomic |
|
|
285
|
+
| Lines never shown to the model | `[E_RANGE_UNSERVED]` — hard reject with fresh anchors | Undisplayed hunks rejected when seen-lines are recorded — same reliance on the model knowing what it saw |
|
|
286
|
+
| Multi-edit batch fails mid-way | `edit` multi-item — atomic, all-or-nothing; the failing item is echoed as fresh serves | Multi-section patches preflighted up front — also atomic |
|
|
239
287
|
|
|
240
|
-
> The
|
|
241
|
-
>
|
|
242
|
-
>
|
|
243
|
-
>
|
|
244
|
-
> needs no re-read.
|
|
288
|
+
> The oh-my-pi payload saving is a lighter wire format; the table above is what that format
|
|
289
|
+
> asks the model to hold in its head instead — renumbering, tag-chasing — the
|
|
290
|
+
> exact component that fails most with replace-style edits. This plugin's contract is:
|
|
291
|
+
> a wrong edit cannot land, and any rejection needs no re-read. Both engines gate the same guarantee — **stale edits are detected, never silently applied** — with different policies when drift is found (recover-with-warning vs fail-closed rejection).
|
|
245
292
|
|
|
246
|
-
|
|
293
|
+
### Reproducible benchmark
|
|
247
294
|
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
replacements: this plugin's `edit` (two 3-char anchors), a `str_replace` tool (old text echoed
|
|
251
|
-
verbatim), and [`@oh-my-pi/hashline`](https://www.npmjs.com/package/@oh-my-pi/hashline) in both of
|
|
252
|
-
its modes — one `[path#tag]` section per edit (`seq`) and one multi-hunk batch document (`batch`):
|
|
295
|
+
The claims above are measured, not asserted. Two deterministic batteries — no LLM in the
|
|
296
|
+
loop, no sampling: a run either reproduces or it doesn't.
|
|
253
297
|
|
|
254
|
-
|
|
255
|
-
| ----------- | :---: | :---: | :---: |
|
|
256
|
-
| Replaced text sent over the wire | ✅ never | ❌ every edit | ✅ never |
|
|
257
|
-
| Output tokens saved (12-edit session) | ✅ **31%** | ❌ 0% | ✅ **42% / 53%** |
|
|
258
|
-
| Multi-line range savings (3–15 lines) | ✅ **29–47%** | ❌ 0% | ✅ **40–53%** |
|
|
259
|
-
| Effective cost at 5× output pricing | ✅ **~1.4× less** | ❌ 1× | ✅ **~1.7× / ~2.1× less** |
|
|
260
|
-
| Ranges verified against served state | ✅ 100% | ❌ none | ~ file version only |
|
|
261
|
-
| Line numbers the model must track | ✅ none — content anchors | ✅ none — text match | ❌ renumber every edit |
|
|
262
|
-
| Deterministic, reproducible locally | ✅ `npm run benchmark` | — | — |
|
|
298
|
+
**Tool battery — 23 scenarios (2026-08-17):**
|
|
263
299
|
|
|
264
|
-
|
|
300
|
+
| vs expected verdict | correct | silent data-loss cases |
|
|
301
|
+
| --- | --: | --: |
|
|
302
|
+
| **dsh-better-edit** (same algorithm as pi-better-edit 1.1.4) | **23/23** | 0 |
|
|
265
303
|
|
|
266
|
-
|
|
304
|
+
Reproduce via upstream: `npm run eval` in `pi-better-edit` (this plugin shares the hashline algorithm byte-for-byte). Library battery for `@oh-my-pi/hashline` is 10/10 separately.
|
|
267
305
|
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
| single-line ×8 | 1 | 309 | 324 | 241 | — |
|
|
271
|
-
| multi-line ×4 | 3–15 | 393 | 691 | 349 | — |
|
|
272
|
-
| **TOTAL ×12** | | **702** | **1015** | **590** | **480** |
|
|
306
|
+
Full method, per-scenario tables, and limitations: upstream [benchmarks/README.md](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/README.md)
|
|
307
|
+
and [benchmarks/results/](https://github.com/Rianico/pi-better-edit/tree/main/benchmarks/results).
|
|
273
308
|
|
|
274
|
-
|
|
309
|
+
## Configuring Guidance per Preset
|
|
275
310
|
|
|
276
|
-
The
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
Because everything is fixed, `npm run benchmark` gives everyone the same result — the numbers in
|
|
280
|
-
this README are a snapshot of that run; regenerate, don't trust.
|
|
311
|
+
The `tool:read` / `tool:edit` / `tool:undo_last_edit` guidance sections are
|
|
312
|
+
plain-markdown files, overridable per agent preset. Override files live in the plugin's shared
|
|
313
|
+
home — never the workspace store:
|
|
281
314
|
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
> largest: the original [harness-problem](https://stencil.so/blog/the-harness-problem) post reported
|
|
286
|
-
> a **61% output-token reduction** and patch-failure drops from 46–51% to near zero after switching
|
|
287
|
-
> to anchored edits. It also does **not** model what a line-numbered format costs the model *between*
|
|
288
|
-
> calls — renumbering and re-fetching the file tag after every edit — nor block-op power, nor the
|
|
289
|
-
> Bun-vs-Node runtime difference, nor the fact that `@oh-my-pi/hashline` is a standalone patcher
|
|
290
|
-
> while this plugin is a dsh tool pair with `read`/`edit`/`undo`. Full methodology, the per-edit
|
|
291
|
-
> table, and the complete limitation list in [`benchmark/README.md`](benchmark/README.md). The correctness gap behind those numbers is spelled out above in [Correctness in edge cases](#correctness-in-edge-cases).
|
|
315
|
+
```
|
|
316
|
+
$DSH_HOME/plugins/dsh-better-edit/<preset>/<section>.md
|
|
317
|
+
```
|
|
292
318
|
|
|
293
|
-
|
|
319
|
+
(default home `~/.dsh`, so `~/.dsh/plugins/dsh-better-edit/`). The section table:
|
|
294
320
|
|
|
295
|
-
|
|
|
296
|
-
|
|
|
297
|
-
| `read` |
|
|
298
|
-
| `edit` |
|
|
299
|
-
| `
|
|
300
|
-
| `undo_last_edit` | `{ path }` reverts the last hashline edit, only while the file still matches the stored post-edit content; survives restarts. |
|
|
321
|
+
| File | Section | Default order |
|
|
322
|
+
| --- | --- | --- |
|
|
323
|
+
| `read.md` | `tool:read` | 130 |
|
|
324
|
+
| `edit.md` | `tool:edit` | 131 |
|
|
325
|
+
| `undo_last_edit.md` | `tool:undo_last_edit` | 133 |
|
|
301
326
|
|
|
302
|
-
|
|
327
|
+
On first boot the plugin seeds the three shipped presets — `standard/`, `code/`,
|
|
328
|
+
`minimal/`, `cordis/` — each with the compiled guidance as editable files (plus
|
|
329
|
+
`order` front-matter), so every preset's guidance starts editable rather than
|
|
330
|
+
blank. A `README.md` at the plugin-home root documents the scheme. Files are
|
|
331
|
+
seeded once and never rewritten, so your edits survive — a reset is the one
|
|
332
|
+
exception (see *Reset / restore defaults* below).
|
|
303
333
|
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
334
|
+
### Reset / restore defaults
|
|
335
|
+
|
|
336
|
+
Emptying or deleting an override file restores that section's compiled default
|
|
337
|
+
guidance and order: the default renders at session-start, and the file re-seeds
|
|
338
|
+
at next boot.
|
|
339
|
+
|
|
340
|
+
- **Reset = delete the file, or empty it AND remove the front-matter fence.** A whitespace-only file with no fence means "I want the default" — the compiled default renders, and the file re-seeds at next boot for any preset dir, shipped or custom.
|
|
341
|
+
- **Blank on purpose = keep a valid fence.** Any well-formed `---` fence — even a keyless `---\n---\n`, even an empty body — is a deliberate-intent signal: the file is explicit content and is never reset or re-seeded.
|
|
342
|
+
- **Broken fence = fast fail.** A `---` fence that does not parse (missing closing `---`, non-integer `order`, unknown key) is rejected: the malformed text is never injected into the context, the compiled default renders, a warning names the file and the reason, and the file is left untouched on disk for repair.
|
|
343
|
+
- **Shipped vs custom.** Shipped preset files (`standard`, `code`, `minimal`, `cordis`) re-seed at boot; a deleted custom-preset override stays absent — absence is no override. Deleting a whole `<preset>/` directory re-seeds all three section files at boot (shipped presets).
|
|
344
|
+
- **Reset restores the current bundle defaults** — a plugin upgrade yields new defaults.
|
|
345
|
+
|
|
346
|
+
Re-seeding happens at boot, never mid-session.
|
|
347
|
+
|
|
348
|
+
## How Anchors Work
|
|
349
|
+
|
|
350
|
+
Each line is canonicalized (all ASCII whitespace — spaces, tabs, carriage returns, and
|
|
351
|
+
line feeds — stripped) and hashed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm)
|
|
352
|
+
(xxHash32), then mapped to a 3-character string over `A-Za-z0-9` — 62³ = 238,328 possible
|
|
353
|
+
anchors. Canonicalization keeps anchors stable across formatting passes and editor-save
|
|
354
|
+
cycles: a line that changes only in ASCII whitespace keeps its anchor, so external linting
|
|
355
|
+
between edits does not invalidate it. Everything that is not ASCII whitespace stays
|
|
356
|
+
significant — string contents, regex classes, comments, quotes, semicolons, and Unicode
|
|
357
|
+
whitespace (NBSP) all rotate the anchor. One caveat: ASCII whitespace *inside* string
|
|
358
|
+
literals and regexes is stripped too, so a whitespace-only change within a string is
|
|
359
|
+
invisible to verification — benign in practice because formatters never alter string
|
|
360
|
+
contents. Token-level edits (quote style, semicolons, brace placement) therefore still
|
|
361
|
+
reject as stale.
|
|
362
|
+
|
|
363
|
+
The alphabet is sized for an LLM consumer — the model tokenizes rather than squinting at
|
|
364
|
+
glyphs, so case and digits are all included. The URL-safe specials `-` and `_` are
|
|
365
|
+
deliberately excluded: a hash starting with `-` is shape-identical to a diff-preview
|
|
366
|
+
deletion row, and `-`/`_` at a line start are markdown-active, inviting mis-copying.
|
|
367
|
+
|
|
368
|
+
Anchors are unique by construction. If a line's base hash collides with an already-assigned
|
|
369
|
+
hash, the next free hash is allocated from a bitset by probing with a stride coprime to the
|
|
370
|
+
hash space (O(1) amortized; the stride is 62² + 62 + 1, so runs of blank lines or repeated
|
|
371
|
+
`}` land on anchors that differ in all three characters). Every line therefore gets a
|
|
372
|
+
unique anchor; two byte-identical lines never share one. The same guarantee sets the file
|
|
373
|
+
size cap: at most 238,328 lines per file, beyond which `read` and `edit` reject with
|
|
374
|
+
`[E_FILE_TOO_LARGE]` (use `write` for very large files).
|
|
375
|
+
|
|
376
|
+
Hashes live in a persistent per-file store
|
|
377
|
+
(`<workspace>/.dsh_better_edit/hash-store.sqlite`, honoring `XDG_CONFIG_HOME` on
|
|
378
|
+
non-Windows) that keeps the hashes of unchanged lines across edits.
|
|
326
379
|
|
|
327
380
|
## How It Replaces the Built-in Tools
|
|
328
381
|
|
|
@@ -352,26 +405,24 @@ call (tests, previews) the store falls back to the shared DeepSeek Harness home
|
|
|
352
405
|
(`$DSH_HOME/plugins/dsh-better-edit/hash-store.sqlite`).
|
|
353
406
|
|
|
354
407
|
A 7-day TTL prunes served rows; missing-file snapshots are pruned at startup. Corrupt stores are
|
|
355
|
-
quarantined and rebuilt automatically.
|
|
356
|
-
undo history from the shared home — treat any pre-0.1.2 undo entries as gone.
|
|
408
|
+
quarantined and rebuilt automatically.
|
|
357
409
|
|
|
358
410
|
## Project Structure
|
|
359
411
|
|
|
360
412
|
```
|
|
361
413
|
dsh-better-edit/
|
|
362
414
|
├── src/
|
|
363
|
-
│ ├── hashline/ # hash + served-state core (ported
|
|
415
|
+
│ ├── hashline/ # hash + served-state core (ported from pi-better-edit)
|
|
364
416
|
│ ├── tool-read.ts # read — HASH│content, offset/limit paging
|
|
365
|
-
│ ├── tool-edit.ts # edit —
|
|
366
|
-
│ ├── tool-batch-edit.ts
|
|
417
|
+
│ ├── tool-edit.ts # edit — {path, edits:[[hash,hash,text]]}, reject-and-serve
|
|
367
418
|
│ ├── tool-undo.ts # undo_last_edit
|
|
368
419
|
│ ├── sandbox.ts # FsSandboxController mirror (sandbox_permissions/justification)
|
|
369
420
|
│ ├── write-hook.ts # auto-read appended to write results
|
|
370
421
|
│ ├── served-store.ts # per-workspace SQLite store (node:sqlite)
|
|
371
422
|
│ └── workspace.ts # session-cwd AsyncLocalStorage carrier
|
|
372
|
-
├── benchmark/ #
|
|
423
|
+
├── benchmark/ # frozen 103-line fixture (reference upstream for reproducible numbers)
|
|
373
424
|
│ └── corpus/ # frozen 103-line fixture
|
|
374
|
-
├── test/ #
|
|
425
|
+
├── test/ # ported + regression tests
|
|
375
426
|
├── assets/ # logo + banner
|
|
376
427
|
├── cordis.patch.yml # bundle patch
|
|
377
428
|
└── package.json # dsh.bundle manifest
|
|
@@ -382,15 +433,14 @@ dsh-better-edit/
|
|
|
382
433
|
```sh
|
|
383
434
|
npm install
|
|
384
435
|
npm run typecheck # tsc --noEmit
|
|
385
|
-
npm test # vitest run
|
|
436
|
+
npm test # vitest run
|
|
386
437
|
npm run build # tsc → lib/
|
|
387
|
-
npm run benchmark # reproducible token-cost benchmark (benchmark/)
|
|
388
438
|
```
|
|
389
439
|
|
|
390
440
|
### Releasing (tag-first)
|
|
391
441
|
|
|
392
442
|
```sh
|
|
393
|
-
npm run release -- 0.
|
|
443
|
+
npm run release -- 0.3.1 # bump + CHANGELOG move + commit + tag + push → GitHub release
|
|
394
444
|
npm publish --registry https://registry.npmjs.org # blocked until the version is tagged
|
|
395
445
|
```
|
|
396
446
|
|
|
@@ -399,35 +449,60 @@ version, commits, tags `vX.Y.Z`, and pushes — the tag push creates the GitHub
|
|
|
399
449
|
changelog. `npm publish` refuses to run until that tag exists (prepublishOnly gate), so every npm
|
|
400
450
|
version is always already tagged and released.
|
|
401
451
|
|
|
402
|
-
|
|
403
|
-
|
|
452
|
+
## Benchmark
|
|
453
|
+
|
|
454
|
+
Measured on the same 103-line file with the same 12 replacements (8 single-line, 4 multi-line of
|
|
455
|
+
3/6/10/15 lines), tokenized with the pinned `js-tiktoken` `cl100k_base`. Three arms emit the same
|
|
456
|
+
replacements: this plugin's `edit` (two 3-char anchors via `edits` tuple), a `str_replace` tool (old text echoed
|
|
457
|
+
verbatim), and [`@oh-my-pi/hashline`](https://www.npmjs.com/package/@oh-my-pi/hashline) in both of
|
|
458
|
+
its modes — one `[path#tag]` section per edit (`seq`) and one multi-hunk batch document (`batch`). Same hashline algorithm, so we reference the upstream reproducible results:
|
|
459
|
+
|
|
460
|
+
| Criterion | hashline | str_replace | oh-my-pi seq / batch |
|
|
461
|
+
| ----------- | :---: | :---: | :---: |
|
|
462
|
+
| Replaced text sent over the wire | ✅ never | ❌ every edit | ✅ never |
|
|
463
|
+
| Output tokens saved (12-edit session) | ✅ **31%** | ❌ 0% | ✅ **42% / 53%** |
|
|
464
|
+
| Multi-line range savings (3–15 lines) | ✅ **29–47%** | ❌ 0% | ✅ **40–53%** |
|
|
465
|
+
| Effective cost at 5× output pricing | ✅ **~1.4× less** | ❌ 1× | ✅ **~1.7× / ~2.1× less** |
|
|
466
|
+
| Ranges verified against served state | ✅ 100% | ❌ none | ~ file version only |
|
|
467
|
+
| Line numbers the model must track | ✅ none — content anchors | ✅ none — text match | ❌ renumber every edit |
|
|
468
|
+
| Deterministic, reproducible locally | ✅ via upstream `npm run benchmark` | — | — |
|
|
469
|
+
|
|
470
|
+
| Scenario | Lines | hashline | str_replace | oh-my-pi seq | oh-my-pi batch |
|
|
471
|
+
| --- | :---: | :---: | :---: | :---: | :---: |
|
|
472
|
+
| single-line ×8 | 1 | 309 | 324 | 241 | — |
|
|
473
|
+
| multi-line ×4 | 3–15 | 393 | 691 | 349 | — |
|
|
474
|
+
| **TOTAL ×12** | | **702** | **1015** | **590** | **480** |
|
|
475
|
+
|
|
476
|
+
Saved vs `str_replace`: hashline **313 (31%)** · oh-my-pi per-edit **425 (42%)** · oh-my-pi batch **535 (53%)**.
|
|
477
|
+
|
|
478
|
+
Upstream is the source of truth for reproducibility: [`pi-better-edit/benchmark/README.md`](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/README.md) and [`benchmarks/results/`](https://github.com/Rianico/pi-better-edit/tree/main/benchmarks/results). This plugin shares the hashline algorithm byte-for-byte, so we do not re-run locally.
|
|
479
|
+
|
|
480
|
+
> **Scope & honesty.** The benchmark measures **request-payload tokens** — what the model emits per
|
|
481
|
+
> edit call — with identical read traffic excluded (it cancels) and identical replacement text.
|
|
482
|
+
> It does **not** model transcription failure and retries, which is where the real-world gap is
|
|
483
|
+
> largest. The correctness gap behind those numbers is spelled out above in [Correctness in edge cases](#correctness-in-edge-cases).
|
|
404
484
|
|
|
405
485
|
## Roadmap
|
|
406
486
|
|
|
407
|
-
**Current state (0.1
|
|
408
|
-
served-tail truncation fix, reproducible benchmark, EN + 中文 READMEs, published on npm.
|
|
487
|
+
**Current state (0.3.1):** hashline `edit` with merged payload `{path, edits:[[hash,hash,text]]}`, whitespace-insensitive anchors, orphan healing, per-workspace store, 674 tests.
|
|
409
488
|
|
|
410
489
|
<details><summary>Next</summary>
|
|
411
490
|
|
|
412
|
-
-
|
|
413
|
-
-
|
|
414
|
-
-
|
|
415
|
-
never truncates either).
|
|
416
|
-
- Re-check plugin wiring against the next dsh release (pinned to `0.1.0-rc.6`; dsh is in developer
|
|
417
|
-
preview and promises breaking changes).
|
|
491
|
+
- Verify 0.3.1 live in a dsh session after the orphan-healing + canon changes.
|
|
492
|
+
- Keep benchmark reference in sync with upstream releases (algorithm is shared).
|
|
493
|
+
- Re-check plugin wiring against the next dsh release (pinned to `0.1.0-rc.6`; dsh is in developer preview and promises breaking changes).
|
|
418
494
|
|
|
419
495
|
</details>
|
|
420
496
|
|
|
421
497
|
## Contributing
|
|
422
498
|
|
|
423
499
|
See [CONTRIBUTING.md](CONTRIBUTING.md) (or just open an [issue](https://github.com/Rianico/dsh-better-edit/issues)).
|
|
424
|
-
The most valuable contributions right now are more
|
|
500
|
+
The most valuable contributions right now are more edge-case tests for the
|
|
425
501
|
served-state verification.
|
|
426
502
|
|
|
427
503
|
## License
|
|
428
504
|
|
|
429
|
-
MIT License — see [LICENSE](LICENSE) for details. Ported from pi-
|
|
430
|
-
itself carries the upstream copyrights of RimuruW and YuGiMob.
|
|
505
|
+
MIT License — see [LICENSE](LICENSE) for details. Ported from pi-better-edit.
|
|
431
506
|
|
|
432
507
|
## Acknowledgments
|
|
433
508
|
|
|
@@ -437,12 +512,14 @@ harness, not the model, is the bottleneck, and that anchored edits beat search-a
|
|
|
437
512
|
project stands on the shoulders of:
|
|
438
513
|
|
|
439
514
|
- [**pi-hashline-edit**](https://github.com/RimuruW/pi-hashline-edit) by RimuruW — the original
|
|
440
|
-
pi-coding-agent extension that introduced
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
515
|
+
pi-coding-agent extension that introduced hash anchors and the strict-semantics
|
|
516
|
+
policy.
|
|
517
|
+
- [**pi-hashline-edit-pro**](https://github.com/YuGiMob/pi-hashline-edit-pro) by YuGiMob —
|
|
518
|
+
the hardened fork this project is self-maintained from (3-char hashes, collision
|
|
519
|
+
resolution, served-state verification, persisted undo).
|
|
520
|
+
- [**pi-better-edit**](https://github.com/Rianico/pi-better-edit) — the upstream this project tracks. The hashline core is ported; the tool layer is rewritten on dsh's plugin API.
|
|
521
|
+
- [**@oh-my-pi/hashline**](https://www.npmjs.com/package/@oh-my-pi/hashline)
|
|
522
|
+
by can1357 — the original oh-my-pi implementation and the hashline patch-language concept.
|
|
446
523
|
|
|
447
524
|
Related reading: [Hash anchors + Myers diff + single-token anchors
|
|
448
525
|
(dirac.run)](https://dirac.run/posts/hash-anchors-myers-diff-single-token) (a design review of the
|