dsh-better-edit 0.1.4 → 0.1.5
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/README.md +155 -63
- package/package.json +6 -4
package/README.md
CHANGED
|
@@ -2,75 +2,102 @@
|
|
|
2
2
|
|
|
3
3
|
Hash-anchored `read` / `edit` / `batch_edit` / `undo_last_edit` tools for
|
|
4
4
|
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`).
|
|
5
|
-
Every line of a file gets a unique 3-character hash
|
|
6
|
-
line numbers, no fuzzy matching, no edits landing on
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
- **
|
|
17
|
-
the
|
|
18
|
-
- **
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
dsh's tool registry resolves per scope: an agent sees `agent → preset →
|
|
36
|
-
global`, and its **own** layer always wins. The built-in `read`/`edit` live on
|
|
37
|
-
the agent-preset layer, so a plain global registration cannot replace them.
|
|
38
|
-
This plugin:
|
|
39
|
-
|
|
40
|
-
1. Mounts as a host-plane Cordis plugin via its `cordis.patch.yml` bundle
|
|
41
|
-
patch.
|
|
42
|
-
2. On `agent/session-start`, registers the hashline tools **and** the
|
|
43
|
-
`tool:read` / `tool:edit` prompt sections on the agent's own scope layer —
|
|
44
|
-
they shadow the preset's built-ins for that agent and unwind automatically
|
|
45
|
-
when the agent is disposed.
|
|
46
|
-
3. Leaves the built-in `write` in place, but a scoped `tools/post-execute`
|
|
47
|
-
listener appends the hashline auto-read to write results.
|
|
48
|
-
|
|
49
|
-
## Installation
|
|
50
|
-
|
|
51
|
-
From npm:
|
|
52
|
-
|
|
53
|
-
```sh
|
|
54
|
-
dsh plugin --profile <name> add dsh-better-edit
|
|
5
|
+
Every line of a file gets a unique 3-character hash — a **content address** —
|
|
6
|
+
and you edit by hash. No line numbers, no fuzzy matching, no edits landing on
|
|
7
|
+
the wrong line.
|
|
8
|
+
|
|
9
|
+
Three things this plugin is built around:
|
|
10
|
+
|
|
11
|
+
- **Token-saving.** An edit call carries `remove_from` / `remove_to` (two
|
|
12
|
+
3-char hashes) plus the replacement text — it never echoes the text being
|
|
13
|
+
replaced. A `str_replace` call must reproduce that text verbatim. On a
|
|
14
|
+
12-edit session over a realistic file this is **28% fewer output tokens**
|
|
15
|
+
(40% on multi-line ranges) — see the [benchmark](#benchmark--reproducible).
|
|
16
|
+
- **Correctness.** Every resolved edit range is verified against the exact
|
|
17
|
+
lines the model was shown. A stale, never-served, or ambiguous range is
|
|
18
|
+
hard-rejected **before anything is written**, and the current range is
|
|
19
|
+
echoed back as fresh anchors (reject-and-serve). Wrong-line edits cannot
|
|
20
|
+
silently land.
|
|
21
|
+
- **A modern edit pattern for agents.** Content-addressed anchors are
|
|
22
|
+
line-number-agnostic: edit one part of a file and the hashes of the rest
|
|
23
|
+
stay put, so chained edits need no re-reads. The model pins a line by what
|
|
24
|
+
it *is*, not by where it used to sit.
|
|
25
|
+
|
|
26
|
+
## Core concepts
|
|
27
|
+
|
|
28
|
+
```mermaid
|
|
29
|
+
flowchart LR
|
|
30
|
+
F["file.ts"] --> R["read"]
|
|
31
|
+
R --> A["ve7 │ function hello()<br/>szJ │ const x = 1<br/>kQm │ return x<br/>9xR │ }"]
|
|
32
|
+
A --> E["edit by hash<br/>remove_from : szJ<br/>remove_to : kQm<br/>replacement_text : …"]
|
|
33
|
+
E --> D["diff, fresh anchors<br/>− szJ │ const x = 1<br/>+ a3m │ const x = 2<br/> kQm │ return x"]
|
|
55
34
|
```
|
|
56
35
|
|
|
57
|
-
|
|
36
|
+
- **Every line is addressed by its content, not its position.** `read`
|
|
37
|
+
returns `HASH│content`; the hash is a stable address for that line. Change
|
|
38
|
+
the line and it gets a new hash; leave it alone and it keeps the hash even
|
|
39
|
+
as the lines around it move.
|
|
58
40
|
|
|
59
|
-
```
|
|
60
|
-
|
|
41
|
+
```mermaid
|
|
42
|
+
flowchart TB
|
|
43
|
+
B["before<br/>ve7 │ const a = 1<br/>szJ │ const b = 2<br/>kQm │ const c = 3"] --> X["insert 3 lines above const c"]
|
|
44
|
+
X --> C["after<br/>ve7 │ const a = 1<br/>szJ │ const b = 2<br/>x4n │ const d = 4<br/>r7p │ const e = 5<br/>kQm │ const c = 3"]
|
|
45
|
+
C --> N["kQm still names const c = 3<br/>line numbers would have shifted"]
|
|
61
46
|
```
|
|
62
47
|
|
|
63
|
-
|
|
64
|
-
|
|
48
|
+
- **Anchors survive edits.** Insert or delete lines above a target and its
|
|
49
|
+
hash is unchanged — a later `edit` by that hash still lands on it. With
|
|
50
|
+
line numbers, every edit above shifts everything below and forces a
|
|
51
|
+
re-read.
|
|
52
|
+
- **Reject-and-serve.** A stale or never-served range is hard-rejected with
|
|
53
|
+
the current `HASH│content` rows echoed back, so the retry needs no `read`.
|
|
54
|
+
|
|
55
|
+
## Why not `str_replace`?
|
|
56
|
+
|
|
57
|
+
Traditional edit tools ask the model to echo the old code token-for-token
|
|
58
|
+
before stating the replacement (`old_string` + `new_string`). That costs
|
|
59
|
+
`O(replaced text)` tokens per edit **and** is where models fail: the original
|
|
60
|
+
[harness-problem](https://stencil.so/blog/the-harness-problem) post reported
|
|
61
|
+
patch-format failure rates of 46–51% for several models with replace-style
|
|
62
|
+
edits, and a **61% output-token reduction** after switching to anchored
|
|
63
|
+
edits. hashline sends two 3-char anchors instead:
|
|
64
|
+
|
|
65
|
+
| | `str_replace` | hashline `edit` |
|
|
66
|
+
| --- | --- | --- |
|
|
67
|
+
| request | `{ path, old_string, new_string }` | `{ path, remove_from, remove_to, replacement_text }` |
|
|
68
|
+
| replaced text | reproduced verbatim | never sent |
|
|
69
|
+
| range verification | none (first match wins) | every line checked against served state |
|
|
70
|
+
| stale file | old_string may still match — and hit the wrong occurrence | rejected with fresh anchors (`E_RANGE_STALE`) |
|
|
71
|
+
| ambiguous text | first occurrence, silently | boundary anchors verified — call `read` for fresh anchors |
|
|
72
|
+
|
|
73
|
+
## Benchmark — reproducible
|
|
74
|
+
|
|
75
|
+
`benchmark/run.mjs` measures the model-side token cost of the two patterns on
|
|
76
|
+
the same 103-line file with the same 12 replacements (8 single-line, 4
|
|
77
|
+
multi-line of 3/6/10/15 lines), tokenized with the pinned `js-tiktoken`
|
|
78
|
+
`cl100k_base`:
|
|
79
|
+
|
|
80
|
+
| scenario | lines | hashline | str_replace | saved | % |
|
|
81
|
+
| --- | --- | --- | --- | --- | --- |
|
|
82
|
+
| single-line ×8 | 1 | 311 | 314 | 3 | 1% |
|
|
83
|
+
| multi-line ×4 | 3–15 | 390 | 655 | 265 | **40%** |
|
|
84
|
+
| **TOTAL ×12** | | **701** | **969** | **268** | **28%** |
|
|
85
|
+
|
|
86
|
+
Read traffic is identical for both tools and cancels. These are the model's
|
|
87
|
+
**output** tokens, billed at ~5-6× the input rate — at the 5× rate, hashline
|
|
88
|
+
costs **~1.4× less** on effective cost. Savings scale with the replaced text:
|
|
89
|
+
near parity on short single lines (the anchors' overhead roughly cancels a
|
|
90
|
+
one-line `old_string`), 25–46% on multi-line ranges.
|
|
91
|
+
|
|
92
|
+
Reproduce it yourself — deterministic, self-checking, no build step:
|
|
65
93
|
|
|
66
94
|
```sh
|
|
67
|
-
|
|
95
|
+
npm install # installs js-tiktoken (pinned)
|
|
96
|
+
npm run benchmark # node benchmark/run.mjs
|
|
68
97
|
```
|
|
69
98
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
- Node `^22.19.0 || >=24.0.0` (dsh's requirement; the store uses `node:sqlite`)
|
|
73
|
-
- A dsh profile (`dsh plugin` initializes one on first use)
|
|
99
|
+
Full methodology, results, and honest limitations (what the baseline does and
|
|
100
|
+
doesn't model) are in [`benchmark/README.md`](benchmark/README.md).
|
|
74
101
|
|
|
75
102
|
## Usage
|
|
76
103
|
|
|
@@ -94,7 +121,8 @@ kQm│}
|
|
|
94
121
|
```
|
|
95
122
|
|
|
96
123
|
1. Keep editing. Anchors for lines you didn't touch stay valid; the post-edit
|
|
97
|
-
diff and the auto-read after `write` hand you fresh anchors.
|
|
124
|
+
diff and the auto-read after `write` hand you fresh anchors. A `read` is
|
|
125
|
+
on-demand recovery, not a per-edit ritual.
|
|
98
126
|
|
|
99
127
|
### The read tool
|
|
100
128
|
|
|
@@ -134,6 +162,48 @@ still matches the stored post-edit content. A later external write clears the
|
|
|
134
162
|
history instead of being overwritten. Undo survives restarts (stored in the
|
|
135
163
|
hash store).
|
|
136
164
|
|
|
165
|
+
## How it replaces the built-in tools
|
|
166
|
+
|
|
167
|
+
dsh's tool registry resolves per scope: an agent sees `agent → preset →
|
|
168
|
+
global`, and its **own** layer always wins. The built-in `read`/`edit` live on
|
|
169
|
+
the agent-preset layer, so a plain global registration cannot replace them.
|
|
170
|
+
This plugin:
|
|
171
|
+
|
|
172
|
+
1. Mounts as a host-plane Cordis plugin via its `cordis.patch.yml` bundle
|
|
173
|
+
patch.
|
|
174
|
+
2. On `agent/session-start`, registers the hashline tools **and** the
|
|
175
|
+
`tool:read` / `tool:edit` prompt sections on the agent's own scope layer —
|
|
176
|
+
they shadow the preset's built-ins for that agent and unwind automatically
|
|
177
|
+
when the agent is disposed.
|
|
178
|
+
3. Leaves the built-in `write` in place, but a scoped `tools/post-execute`
|
|
179
|
+
listener appends the hashline auto-read to write results.
|
|
180
|
+
|
|
181
|
+
## Installation
|
|
182
|
+
|
|
183
|
+
From npm:
|
|
184
|
+
|
|
185
|
+
```sh
|
|
186
|
+
dsh plugin --profile <name> add dsh-better-edit
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
From a local checkout:
|
|
190
|
+
|
|
191
|
+
```sh
|
|
192
|
+
dsh plugin --profile <name> add /path/to/dsh-better-edit
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
The profile's next session runs with the hashline tools installed. To verify
|
|
196
|
+
the layer is active:
|
|
197
|
+
|
|
198
|
+
```sh
|
|
199
|
+
dsh --profile <name> --dump-config # shows a "# == dsh-better-edit" layer
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### Requirements
|
|
203
|
+
|
|
204
|
+
- Node `^22.19.0 || >=24.0.0` (dsh's requirement; the store uses `node:sqlite`)
|
|
205
|
+
- A dsh profile (`dsh plugin` initializes one on first use)
|
|
206
|
+
|
|
137
207
|
## Store
|
|
138
208
|
|
|
139
209
|
Hash snapshots, served-state rows, and undo history live in one SQLite store
|
|
@@ -177,6 +247,27 @@ home — treat any pre-0.1.2 undo entries as gone.
|
|
|
177
247
|
| `[E_UNDO_UNAVAILABLE]` | Undo history could not be persisted; the edit was not applied. |
|
|
178
248
|
| `[E_WOULD_EMPTY]` | An edit would empty a non-empty file; use `write` to clear it. |
|
|
179
249
|
|
|
250
|
+
## Inspiration and lineage
|
|
251
|
+
|
|
252
|
+
Hash-anchored editing descends from Can Bölük's
|
|
253
|
+
[*The Harness Problem*](https://stencil.so/blog/the-harness-problem), which
|
|
254
|
+
showed that the harness — not the model — was the bottleneck, and that
|
|
255
|
+
anchored edits beat search-and-replace. This project is a dsh port of:
|
|
256
|
+
|
|
257
|
+
- [**pi-hashline-edit**](https://github.com/RimuruW/pi-hashline-edit) by
|
|
258
|
+
RimuruW — the original pi-coding-agent extension that introduced
|
|
259
|
+
3-character hashes and collision resolution.
|
|
260
|
+
- [**pi-hashline-edit-pro**](https://github.com/YuGiMob/pi-hashline-edit-pro)
|
|
261
|
+
by YuGiMob — the hardened fork the hashline core here is ported from.
|
|
262
|
+
- [**pi-hashline-edit-lsz**](https://github.com/Rianico/pi-hashline-edit-lsz) —
|
|
263
|
+
the self-maintained fork this project tracks. The hashline core is ported
|
|
264
|
+
byte-for-byte; the tool layer is rewritten on dsh's plugin API.
|
|
265
|
+
|
|
266
|
+
Related reading: [Hash anchors + Myers diff + single-token anchors
|
|
267
|
+
(dirac.run)](https://dirac.run/posts/hash-anchors-myers-diff-single-token)
|
|
268
|
+
(a design review of the O(S+R) → O(R) edit-call saving) and an independent
|
|
269
|
+
[hashline-vs-replace benchmark](https://nwyin.com/blogs/hashline-vs-replace-edit-bench.html).
|
|
270
|
+
|
|
180
271
|
## Development
|
|
181
272
|
|
|
182
273
|
```sh
|
|
@@ -184,12 +275,13 @@ npm install
|
|
|
184
275
|
npm run typecheck # tsc --noEmit
|
|
185
276
|
npm test # vitest run
|
|
186
277
|
npm run build # tsc → lib/
|
|
278
|
+
npm run benchmark # reproducible token-cost benchmark (benchmark/)
|
|
187
279
|
```
|
|
188
280
|
|
|
189
|
-
The test suite is ported from pi-hashline-edit-lsz (
|
|
281
|
+
The test suite is ported from pi-hashline-edit-lsz (615 tests) and drives the
|
|
190
282
|
dsh tool builders directly over a local filesystem bridge.
|
|
191
283
|
|
|
192
284
|
## License
|
|
193
285
|
|
|
194
286
|
MIT — see [LICENSE](LICENSE). Ported from pi-hashline-edit-lsz (MIT), which
|
|
195
|
-
itself carries the upstream copyrights of RimuruW and
|
|
287
|
+
itself carries the upstream copyrights of RimuruW and YuGiMob.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-better-edit",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Hash-anchored read/edit/batch_edit/undo_last_edit tools for DeepSeek Harness (dsh). Every line gets a unique 3-char hash (A-Za-z0-9) that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
|
|
6
6
|
"main": "lib/index.js",
|
|
@@ -50,10 +50,10 @@
|
|
|
50
50
|
}
|
|
51
51
|
},
|
|
52
52
|
"dependencies": {
|
|
53
|
+
"@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6",
|
|
53
54
|
"diff": "^8.0.2",
|
|
54
55
|
"file-type": "^21.3.0",
|
|
55
|
-
"xxhash-wasm": "^1.1.0"
|
|
56
|
-
"@deepseek-ai/dsh-sandbox": "^0.1.0-rc.6"
|
|
56
|
+
"xxhash-wasm": "^1.1.0"
|
|
57
57
|
},
|
|
58
58
|
"peerDependencies": {
|
|
59
59
|
"@deepseek-ai/cordis": "^4.0.0",
|
|
@@ -71,7 +71,8 @@
|
|
|
71
71
|
"typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
|
|
72
72
|
"test": "vitest run",
|
|
73
73
|
"test:watch": "vitest",
|
|
74
|
-
"prepublishOnly": "npm run typecheck && npm test"
|
|
74
|
+
"prepublishOnly": "npm run typecheck && npm test",
|
|
75
|
+
"benchmark": "node benchmark/run.mjs"
|
|
75
76
|
},
|
|
76
77
|
"devDependencies": {
|
|
77
78
|
"@deepseek-ai/cordis": "^4.0.1",
|
|
@@ -82,6 +83,7 @@
|
|
|
82
83
|
"@deepseek-ai/dsh-tools": "0.1.0-rc.6",
|
|
83
84
|
"@types/node": "^24.0.0",
|
|
84
85
|
"@vitest/coverage-v8": "^4.1.10",
|
|
86
|
+
"js-tiktoken": "1.0.21",
|
|
85
87
|
"typescript": "^5.8.0",
|
|
86
88
|
"vitest": "^4.1.8"
|
|
87
89
|
}
|