dsh-better-edit 0.6.1 → 0.6.3
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 +15 -12
- package/README.md +132 -383
- package/lib/index.js +18 -21
- package/lib/self-heal.js +101 -0
- package/lib/types/self-heal.d.ts +29 -0
- package/package.json +7 -7
package/CHANGELOG.md
CHANGED
|
@@ -1,21 +1,24 @@
|
|
|
1
|
-
## [
|
|
1
|
+
## [0.6.3](https://github.com/Rianico/dsh-better-edit/compare/v0.6.2...v0.6.3) (2026-09-05)
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
### Bug Fixes
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
* **self-heal:** restore hash-anchored read/edit after external takeover ([#43](https://github.com/Rianico/dsh-better-edit/issues/43)) ([#44](https://github.com/Rianico/dsh-better-edit/issues/44)) ([b53fc75](https://github.com/Rianico/dsh-better-edit/commit/b53fc753bcd71f1950bde61ad81e1b7b94758273))
|
|
6
|
+
|
|
7
|
+
## [0.6.2](https://github.com/Rianico/dsh-better-edit/compare/v0.6.1...v0.6.2) (2026-09-03)
|
|
8
|
+
|
|
9
|
+
### Bug Fixes
|
|
6
10
|
|
|
7
|
-
|
|
8
|
-
- **hashline:** make read path per-session reserved for ADR-0013
|
|
9
|
-
- **hashline:** polish P2s for ADR-0013 automatic fallback
|
|
10
|
-
- **hashline:** implement per-session tombstone and epoch-aware strict pos
|
|
11
|
-
- **hashline:** add per-session canons, epoch and strict pos for ADR-0013
|
|
12
|
-
- **hashline:** prevent freed anchor reuse (#31)
|
|
11
|
+
* **deps:** upgrade dsh dependencies to 0.1.1-rc.2 ([30e6029](https://github.com/Rianico/dsh-better-edit/commit/30e6029888fa517f20c640b7a38523a8a6148ccd))
|
|
13
12
|
|
|
14
13
|
### Documentation
|
|
15
14
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
15
|
+
* **readme:** compact rewrite — pos-free hero, round-trips, tokens ([dc468c5](https://github.com/Rianico/dsh-better-edit/commit/dc468c5ce9799ddf9578d92e715905701b2a95a1))
|
|
16
|
+
|
|
17
|
+
## [0.6.1](https://github.com/Rianico/dsh-better-edit/compare/v0.6.0...v0.6.1) (2026-09-01)
|
|
18
|
+
|
|
19
|
+
### Bug Fixes
|
|
20
|
+
|
|
21
|
+
* **hashline:** prevent freed anchor reuse ([#31](https://github.com/Rianico/dsh-better-edit/issues/31)) ([#42](https://github.com/Rianico/dsh-better-edit/issues/42)) ([19724a4](https://github.com/Rianico/dsh-better-edit/commit/19724a4083afcfc104172d5ce71bb6ab198026b7)), closes [GH#41](https://github.com/Rianico/GH/issues/41)
|
|
19
22
|
|
|
20
23
|
## [0.6.0](https://github.com/Rianico/dsh-better-edit/compare/v0.5.1...v0.6.0) (2026-08-31)
|
|
21
24
|
|
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
<h1 align="center">dsh-better-edit</h1>
|
|
6
6
|
<p align="center">
|
|
7
7
|
<strong>A better edit tool for DeepSeek Harness<br>
|
|
8
|
-
|
|
8
|
+
Position-free hashes — one read, many edits, fewer tokens, more room for real work.</strong>
|
|
9
9
|
</p>
|
|
10
10
|
<p align="center">
|
|
11
11
|
<strong>English</strong> ·
|
|
@@ -15,21 +15,20 @@
|
|
|
15
15
|
<p align="center">
|
|
16
16
|
<a href="#why-you-need-this"><img src="https://img.shields.io/badge/why-hashline-blue?style=flat" alt="why hashline"></a>
|
|
17
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="#
|
|
18
|
+
<a href="#benchmark"><img src="https://img.shields.io/badge/correctness-23%2F23-success?style=flat" alt="23/23 battery"></a>
|
|
19
19
|
</p>
|
|
20
20
|
|
|
21
21
|
<p align="center">
|
|
22
22
|
<a href="#quick-start">Quick Start</a> •
|
|
23
23
|
<a href="#why-hashline">Why Hashline</a> •
|
|
24
24
|
<a href="#tools">Tools</a> •
|
|
25
|
-
<a href="#
|
|
25
|
+
<a href="#benchmark">Benchmark</a> •
|
|
26
26
|
<a href="#how-anchors-work">How Anchors Work</a> •
|
|
27
|
-
<a href="#development">Development</a>
|
|
28
|
-
<a href="#acknowledgments">Acknowledgments</a>
|
|
27
|
+
<a href="#development">Development</a>
|
|
29
28
|
</p>
|
|
30
29
|
|
|
31
30
|
<p align="center">
|
|
32
|
-
<img src="https://img.shields.io/badge/version-0.
|
|
31
|
+
<img src="https://img.shields.io/badge/version-0.6.1-blue.svg" alt="Version">
|
|
33
32
|
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
|
|
34
33
|
<img src="https://img.shields.io/badge/DeepSeek_Harness-Plugin-blueviolet.svg" alt="DeepSeek Harness Plugin">
|
|
35
34
|
<img src="https://img.shields.io/npm/v/dsh-better-edit" alt="npm version">
|
|
@@ -44,59 +43,56 @@
|
|
|
44
43
|
---
|
|
45
44
|
|
|
46
45
|
> *"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.**
|
|
49
|
-
|
|
50
|
-
> **3
|
|
46
|
+
|
|
47
|
+
> **This is the harness fix.** Hashes replace line numbers — edits above don't shift anchors below. One `read` serves many `edit`s; drift outside your range passes with a notice, true conflicts retry with fresh anchors — no full `read` needed.
|
|
48
|
+
|
|
49
|
+
> **3 calls vs 6 · -55.8% tokens · 23/23 correctness.** Same external-drift refactor, same file (single stochastic run; [method](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/results/2026-08-17-practical-token-benchmark.md)). Payload numbers are deterministic — see [Benchmark](#benchmark).
|
|
51
50
|
|
|
52
51
|
## Why you need this
|
|
53
52
|
|
|
54
|
-
**If you've watched
|
|
53
|
+
**If you've watched `line 47 → 74` corrupt a file after an insert — this is for you.**
|
|
55
54
|
|
|
56
55
|
| Before: `str_replace` / line numbers | After: hashline `edit` |
|
|
57
56
|
| --- | --- |
|
|
58
|
-
|
|
|
59
|
-
| One insert
|
|
60
|
-
| No check
|
|
57
|
+
| Re-types old code (~5-6× billed) | Two `3-char` hashes, old text never echoed |
|
|
58
|
+
| One insert shifts every number → silent wrong line | Content addresses — edits above don't move anchors below |
|
|
59
|
+
| No check against what was shown | Every line verified; `[E_RANGE_STALE]`/`[E_RANGE_UNSERVED]` reject before write, then **reject-and-serve** returns fresh `HASH│content` |
|
|
61
60
|
|
|
62
61
|
> [!TIP]
|
|
63
|
-
> **Shining points — honest
|
|
62
|
+
> **Shining points — honest:**
|
|
64
63
|
>
|
|
65
|
-
> - **
|
|
66
|
-
> - **
|
|
67
|
-
> - **
|
|
68
|
-
> - **
|
|
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.
|
|
70
|
-
|
|
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.
|
|
64
|
+
> - **Position-free.** `read 1..5` → `insert @0` → `edit 10..12` still lands at `10..12`. Anchors are `canon(line)` hashes, not positions (ADR-0013). Exterior drift is a notice, not a re-read.
|
|
65
|
+
> - **Fewer round-trips.** Single-session `1 read → N edits` — no ritual re-reads. Multi-session exterior `A:10..12 / B:20..30` also passes; only overlapping `A∩B≠∅` retries once via `servedRows` (no full `read`). Harness `9/9` green.
|
|
66
|
+
> - **Fewer tokens.** Compact payload `{path, edits:[[from,to,text]]}` + never echoing `old_string`; diff/echo/rejection rows count as serves. Envelope `-40%` pinned 12-edit corpus, session `-55.8%` on external-drift.
|
|
67
|
+
> - **Concurrent-safe, not silent.** `tombstone` per `(session,path)` epoch blocks re-bound `S@3→@3`; `canon` + `hash` + `changed∩[L,R]` makes `pos-free` single-thread and `strict` only on true overlap. One retry vs silent wrong-line.
|
|
72
68
|
|
|
73
|
-
|
|
69
|
+
Not for one-line touch-ups (near parity) or new files (`write`). Pays off in long sessions and structural edits.
|
|
74
70
|
|
|
75
|
-
## Quick Start —
|
|
71
|
+
## Quick Start — install to verified edit in 30s
|
|
76
72
|
|
|
77
73
|
### Install (pick one)
|
|
78
74
|
|
|
79
75
|
```sh
|
|
80
76
|
npx @deepseek-ai/dsh plugin --profile web add github:Rianico/dsh-better-edit # from github
|
|
81
|
-
npx @deepseek-ai/dsh plugin --profile web add dsh-better-edit
|
|
82
|
-
npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-better-edit
|
|
77
|
+
npx @deepseek-ai/dsh plugin --profile web add dsh-better-edit # from npm
|
|
78
|
+
npx @deepseek-ai/dsh plugin --profile web add /path/to/dsh-better-edit # local
|
|
83
79
|
```
|
|
84
80
|
|
|
85
|
-
No config.
|
|
81
|
+
No config. Next session runs with hashline tools. Verify:
|
|
86
82
|
|
|
87
83
|
```sh
|
|
88
|
-
dsh --profile <name> --dump-config # shows
|
|
84
|
+
dsh --profile <name> --dump-config # shows "# == dsh-better-edit" layer
|
|
89
85
|
```
|
|
90
86
|
|
|
91
87
|
| Requirement | |
|
|
92
88
|
| --- | --- |
|
|
93
|
-
| Node | `^22.19.0 \|\| >=24.0.0`
|
|
94
|
-
| Profile |
|
|
95
|
-
| Backends | sandboxed / remote
|
|
89
|
+
| Node | `^22.19.0 \|\| >=24.0.0` |
|
|
90
|
+
| Profile | `dsh` profile (`dsh plugin` creates one) |
|
|
91
|
+
| Backends | sandboxed / remote `ctx.fs` |
|
|
96
92
|
|
|
97
93
|
### See it work
|
|
98
94
|
|
|
99
|
-
`read`
|
|
95
|
+
`read` serves `HASH│content` — the hash *is* the address:
|
|
100
96
|
|
|
101
97
|
```text
|
|
102
98
|
ve7│function hello() {
|
|
@@ -104,13 +100,13 @@ szJ│ console.log("world");
|
|
|
104
100
|
kQm│}
|
|
105
101
|
```
|
|
106
102
|
|
|
107
|
-
`edit`
|
|
103
|
+
`edit` by hashes — always lands where you meant:
|
|
108
104
|
|
|
109
105
|
```json
|
|
110
106
|
{ "path": "src/main.ts", "edits": [["szJ", "szJ", " console.log('hi');"]] }
|
|
111
107
|
```
|
|
112
108
|
|
|
113
|
-
|
|
109
|
+
Returns a diff with fresh anchors — next edit needs no `read`:
|
|
114
110
|
|
|
115
111
|
```text
|
|
116
112
|
- szJ │ console.log("world");
|
|
@@ -118,434 +114,187 @@ and returns a diff with fresh anchors, so the next edit verifies cleanly with no
|
|
|
118
114
|
kQm │ }
|
|
119
115
|
```
|
|
120
116
|
|
|
121
|
-
|
|
117
|
+
**Position-free in one line:** `read 1..5` → `insert @0` → `edit 10..12` still verifies `10..12` (`resist` mode). **Multi-session honesty:** `A:10..12+1` shifts `B:20..30→21..31` → `B` passes (drift notice); `B:12..13` overlapping `A` → `E_RANGE_STALE` + fresh rows, one retry.
|
|
118
|
+
|
|
119
|
+
Batch atomically — one `edit`, up to 32 same-file ranges:
|
|
122
120
|
|
|
123
121
|
```json
|
|
124
|
-
{ "path": "src/main.ts", "edits": [["a1b",
|
|
122
|
+
{ "path": "src/main.ts", "edits": [["a1b","a1b","new line 1\n"], ["c3d","c3d","new line 2"]] }
|
|
125
123
|
```
|
|
126
124
|
|
|
127
|
-
One fails
|
|
125
|
+
One fails → none write (`[E_BATCH_ABORT]`).
|
|
128
126
|
|
|
129
127
|
> [!TIP]
|
|
130
|
-
> **Want proof before you install?**
|
|
128
|
+
> **Want proof before you install?** Upstream [23/23 battery](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/README.md) runs no LLM — stale edits are rejected every run. Same algorithm.
|
|
131
129
|
|
|
132
130
|
### Configuration
|
|
133
131
|
|
|
134
|
-
Tenancy and prompt guidance
|
|
132
|
+
Tenancy and prompt guidance declare once, read at `agent/session-start`, no code change.
|
|
135
133
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
The store lives at `$DSH_HOME/plugins/dsh-better-edit/runtime/<name>-<hash8>/` by default (`central`).
|
|
139
|
-
|
|
140
|
-
> [!NOTE]
|
|
141
|
-
> DB files are **disposable caches** — they are rebuilt automatically on the next `read` (hashes are re-derived from file content). Feel free to `rm -rf` any `runtime/<name>-<hash8>/` or `hash-store.sqlite*` to reclaim disk; no user data is lost (only anchor history and undo snapshots).
|
|
142
|
-
|
|
143
|
-
To opt into legacy co-location or a custom root:
|
|
134
|
+
**Store** central by default `$DSH_HOME/plugins/dsh-better-edit/runtime/<name>-<hash8>/` (`ls`-readable + `.wsPath` sidecar). DBs are disposable caches — `rm -rf runtime/<name>-<hash8>/` is safe, rebuilt on next `read`.
|
|
144
135
|
|
|
145
136
|
```yaml
|
|
146
137
|
# $DSH_HOME/plugins/dsh-better-edit/config.yaml
|
|
147
|
-
storeDir: central #
|
|
148
|
-
autoGitignore: false
|
|
149
|
-
undo_ttl_s: 604800 #
|
|
150
|
-
storeMaxAgeS: 2592000 #
|
|
151
|
-
storeMaxTotalBytes: 524288000 #
|
|
138
|
+
storeDir: central # central | workspace | /abs
|
|
139
|
+
autoGitignore: false
|
|
140
|
+
undo_ttl_s: 604800 # 7d, -1 forever
|
|
141
|
+
storeMaxAgeS: 2592000 # 30d janitor
|
|
142
|
+
storeMaxTotalBytes: 524288000 # 500 MB LRU
|
|
152
143
|
```
|
|
153
144
|
|
|
154
|
-
|
|
155
|
-
> If the file does not exist, a default `config.yaml` with commented defaults is generated on first boot (never overwrites an existing file).
|
|
156
|
-
|
|
157
|
-
Env overrides yaml (`env > yaml > central`), malformed falls back to `central` with a warning:
|
|
158
|
-
|
|
159
|
-
```sh
|
|
160
|
-
DSH_BETTER_EDIT_STORE_DIR=central|workspace|/abs
|
|
161
|
-
DSH_BETTER_EDIT_AUTO_GITIGNORE=true|false # case-insensitive
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
`runtime/<name>-<hash8>/` is `ls`-readable with a `.wsPath` sidecar. See `docs/specs/issue-24-store-tenancy.md` for lifecycle (janitor `mtime>storeMaxAgeS` then LRU, WAL checkpoint, `undo` TTL).
|
|
165
|
-
|
|
166
|
-
#### Guidance per preset
|
|
167
|
-
|
|
168
|
-
The `tool:read` / `tool:edit` / `tool:undo_last_edit` prompt sections are plain-markdown files per agent preset, overridable without touching the plugin:
|
|
169
|
-
|
|
170
|
-
```
|
|
171
|
-
$DSH_HOME/plugins/dsh-better-edit/<preset>/<section>.md
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
(default home `~/.dsh`, so `~/.dsh/plugins/dsh-better-edit/`). The section table:
|
|
175
|
-
|
|
176
|
-
| File | Section | Default order |
|
|
177
|
-
| --- | --- | --- |
|
|
178
|
-
| `read.md` | `tool:read` | 130 |
|
|
179
|
-
| `edit.md` | `tool:edit` | 131 |
|
|
180
|
-
| `undo_last_edit.md` | `tool:undo_last_edit` | 133 |
|
|
181
|
-
|
|
182
|
-
On first boot the plugin seeds the three shipped presets — `standard/`, `code/`, `minimal/`, `cordis/` — each with the compiled guidance as editable files (plus `order` front-matter). See [Configuration details](#configuring-guidance-per-preset) for reset/restore. Full spec: `docs/specs/issue-24-store-tenancy.md` and guidance docs.
|
|
145
|
+
Env overrides yaml (`DSH_BETTER_EDIT_STORE_DIR`, `DSH_BETTER_EDIT_AUTO_GITIGNORE`).
|
|
183
146
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
Emptying or deleting an override file restores that section's compiled default guidance and order: the default renders at session-start, and the file re-seeds at next boot.
|
|
187
|
-
|
|
188
|
-
- **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.
|
|
189
|
-
- **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.
|
|
190
|
-
- **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.
|
|
191
|
-
- **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).
|
|
192
|
-
- **Reset restores the current bundle defaults** — a plugin upgrade yields new defaults.
|
|
193
|
-
|
|
194
|
-
Re-seeding happens at boot, never mid-session.
|
|
147
|
+
**Guidance per preset** — `tool:read` / `tool:edit` / `tool:undo_last_edit` are plain markdown per preset at `$DSH_HOME/plugins/dsh-better-edit/<preset>/<section>.md` (orders `130/131/133`). Delete or empty a file → default re-seeds at next boot; keep a `---` fence to blank on purpose.
|
|
195
148
|
|
|
196
149
|
## Why Hashline
|
|
197
150
|
|
|
198
|
-
**
|
|
199
|
-
served rows — what `read`, a post-edit diff, or a rejection echo actually showed the model.
|
|
200
|
-
A line inside the range that changed on disk since it was served, or was never served, is
|
|
201
|
-
hard-rejected before any file I/O: `[E_RANGE_STALE]` / `[E_RANGE_UNSERVED]` /
|
|
202
|
-
`[E_RANGE_UNVERIFIED]`, and the current range is echoed as fresh `HASH│content` rows. The
|
|
203
|
-
retry needs no `read`. Served state is session-scoped, so sub-agent serves never validate the main session's edits and vice versa.
|
|
204
|
-
|
|
205
|
-
**Content-addressed anchors.** Anchors are derived from line content (ASCII-whitespace
|
|
206
|
-
stripped), not position: edit one part of a file and the hashes of the rest stay put, so
|
|
207
|
-
chained edits need no re-reads. Re-inserting identical text keeps its hash — "edit X with
|
|
208
|
-
X" doesn't rotate the anchor. Anchors are unique by construction — repeated `}` or
|
|
209
|
-
`import` lines never share one.
|
|
210
|
-
|
|
211
|
-
**Chained edits without re-reading.** Post-edit diff rows, auto-read rows, and rejection
|
|
212
|
-
echoes all count as serves. `read` is on-demand recovery, not a per-edit ritual.
|
|
213
|
-
|
|
214
|
-
**Stop the loop.** A no-op edit reports `No changes made` and leaves anchors alone; the
|
|
215
|
-
same no-op re-sent three times is refused (`[E_NOOP_LOOP]`). `edit` applies up to 32
|
|
216
|
-
edits atomically — any stale item aborts the whole batch with `[E_BATCH_ABORT]`.
|
|
151
|
+
**Verified against what was served.** Every resolved line checked against `read`/diff/rejection rows. Stale or unseen → `[E_RANGE_STALE]`/`[E_RANGE_UNSERVED]`/`[E_RANGE_UNVERIFIED]` + fresh `HASH│content`, retry needs no `read`. Session-scoped — sub-agent serves never validate main edits.
|
|
217
152
|
|
|
218
|
-
|
|
153
|
+
**Content-addressed.** `canon(line)` strips ASCII whitespace, `xxh32 → 62³=238,328` anchors. Re-inserting identical text keeps its hash; `prettier`/`eslint --fix` between edits doesn't invalidate. Unique by bitset probing — `}`/`import` repeats never collide; cap `238,328` lines (`[E_FILE_TOO_LARGE]`).
|
|
219
154
|
|
|
220
|
-
|
|
155
|
+
**No loop, no ritual.** No-op → `No changes made`; same no-op ×3 → `[E_NOOP_LOOP]`. Diff/echo/rejection rows count as serves — `read` is recovery, not ritual.
|
|
221
156
|
|
|
222
|
-
|
|
223
|
-
- replacement text is emitted once, and the old text is never repeated in the call.
|
|
157
|
+
### Token economics
|
|
224
158
|
|
|
225
|
-
|
|
159
|
+
Envelope change: hoist `path`, `edits:[[from,to,text]]`, never repeat `old_string`.
|
|
226
160
|
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
| snapshot | `str_replace` | pi/dsh-better-edit: `edit` | pi/dsh-better-edit: `edit` (multi-item) | OMP: per-edit | OMP: one batch |
|
|
161
|
+
| snapshot | `str_replace` | `edit` | `edit` multi | OMP per-edit | OMP batch |
|
|
230
162
|
| --- | ---: | ---: | ---: | ---: | ---: |
|
|
231
|
-
|
|
|
232
|
-
| local
|
|
233
|
-
|
|
234
|
-
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.
|
|
235
|
-
|
|
236
|
-
#### Practical benchmark — coding-agent session
|
|
163
|
+
| pinned 12-edit corpus | 1,015 | 609 **-40.0%** | 582 **-42.7%** | 590 **-41.9%** | 480 **-52.7%** |
|
|
164
|
+
| local snapshot | 358 | 272 **-24.0%** | 241 **-32.7%** | 268 **-25.1%** | 180 **-49.7%** |
|
|
237
165
|
|
|
238
|
-
|
|
166
|
+
Percent vs `str_replace`. External row pinned corpus, `cl100k_base`; local `npm run benchmark` in upstream.
|
|
239
167
|
|
|
240
|
-
| engine |
|
|
168
|
+
| engine | calls | tokens | saved | ok |
|
|
241
169
|
| --- | ---: | ---: | ---: | :---: |
|
|
242
|
-
| OMP
|
|
243
|
-
| hashline `edit`
|
|
170
|
+
| OMP | **6** | 28,467 | — | ✅ |
|
|
171
|
+
| hashline `edit` | **3** | 12,593 | **-55.8%** | ✅ |
|
|
244
172
|
|
|
245
|
-
|
|
173
|
+
Single stochastic run, `opencode-go/gpt-5.6-luna` high. [Artifact](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/results/2026-08-17-practical-token-benchmark.md).
|
|
246
174
|
|
|
247
|
-
> **Scope & honesty.**
|
|
175
|
+
> **Scope & honesty.** Payload deterministic; practical run stochastic. We measure **payload + round-trips**, not throughput. Retries are where the gap is largest — see [edge cases](#comparison).
|
|
248
176
|
|
|
249
177
|
## Tools
|
|
250
178
|
|
|
251
179
|
| Tool | What it does |
|
|
252
|
-
|
|
|
253
|
-
| `read` |
|
|
254
|
-
| `read_skill` |
|
|
255
|
-
| `edit` |
|
|
256
|
-
| `undo_last_edit` | `{
|
|
257
|
-
|
|
258
|
-
The built-in `write` remains available for full-file replacement. Before it runs, the plugin refuses only a candidate line that begins with the exact `HASH│` anchor served for the same session, canonical path, and line; the file stays unchanged and the response asks for a retry with file content only. It never generically strips hash-like text.
|
|
180
|
+
| --- | --- |
|
|
181
|
+
| `read` | `HASH│content` with `offset`/`limit`; `[Showing N-M of T]` paging; `>200KB` lines show marker |
|
|
182
|
+
| `read_skill` | Plain text, no hashes, no serves — editing after it needs a serve |
|
|
183
|
+
| `edit` | `{path, edits:[[from,to,text]]}` `path:string\|null` inference, `""` deletes, atomic ≤32, verify-then-write |
|
|
184
|
+
| `undo_last_edit` | `{path}` restores last edit (BOM/line endings/anchors), persisted |
|
|
259
185
|
|
|
260
|
-
`
|
|
261
|
-
position is a non-empty string or `null` for unique anchor-based inference. Each range is inclusive,
|
|
262
|
-
and an empty replacement deletes the range. All items are checked before file I/O and applied
|
|
263
|
-
atomically to that one file — one item per call is the norm, several same-file items batch in one call.
|
|
186
|
+
`write` stays, but refuses an exact `HASH│` echo for same `session/path/line` before dispatch.
|
|
264
187
|
|
|
265
188
|
### Error codes
|
|
266
189
|
|
|
267
190
|
| Code | Meaning |
|
|
268
191
|
| --- | --- |
|
|
269
|
-
| `[E_BAD_SHAPE]` |
|
|
270
|
-
| `[
|
|
271
|
-
| `[
|
|
272
|
-
| `[
|
|
273
|
-
| `[E_INVALID_PATCH]` |
|
|
274
|
-
| `[
|
|
275
|
-
| `[
|
|
276
|
-
| `[
|
|
277
|
-
| `[
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
| `[E_NOT_TEXT]` | The path is a directory, binary file, image, or UTF-16/UTF-32 encoded text; hashline editing only supports text files. |
|
|
281
|
-
| `[E_NOT_OBSERVED]` | The file has not been observed in this session (read-before-write); call `read` first. |
|
|
282
|
-
| `[E_WRITE_HASH_ECHO]` | A built-in `write` candidate copied a `HASH│` preview anchor served for the same session, path, and line. The write is refused before dispatch; remove the entire copied anchor chain and retry. |
|
|
283
|
-
| `[E_UNDO_STALE]` | `undo_last_edit` refused: the file was modified or deleted after the last edit. |
|
|
284
|
-
| `[E_UNDO_UNAVAILABLE]` | Undo history could not be persisted to the hash store; the `edit` was refused and the file was left unchanged. |
|
|
285
|
-
| `[E_FILE_TOO_LARGE]` | The file exceeds the 238,328-line hashline limit. |
|
|
286
|
-
| `[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). |
|
|
287
|
-
| `[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. |
|
|
288
|
-
| `[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. |
|
|
289
|
-
| `[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. |
|
|
290
|
-
| `[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. |
|
|
192
|
+
| `[E_BAD_SHAPE]`/`[E_BAD_REF]` | Bad tuple shape or not bare `3-char` |
|
|
193
|
+
| `[E_STALE_ANCHOR]`/`[E_AMBIGUOUS_ANCHOR]` | No line / multi-line → `read` |
|
|
194
|
+
| `[E_EDIT_HASH_ECHO]`/`[E_WRITE_HASH_ECHO]` | Copied `HASH│` from same session/path/line — strip and retry |
|
|
195
|
+
| `[E_WOULD_EMPTY]`/`[E_NOT_FOUND]`/`[E_ACCESS]`/`[E_NOT_TEXT]`/`[E_FILE_TOO_LARGE]` | Empty guard / missing / access / binary / >238,328 lines |
|
|
196
|
+
| `[E_BAD_OP]`/`[E_INVALID_PATCH]`/`[E_BARE_HASH_PREFIX]` | Swapped range / `+HASH│` patch marker (auto-corrected) |
|
|
197
|
+
| `[E_BAD_ENCODING]`/`[E_DECODE_FAILED]` | Encoding / decode failed |
|
|
198
|
+
| `[E_NOT_OBSERVED]`/`[E_RANGE_STALE]`/`[E_RANGE_UNSERVED]`/`[E_RANGE_UNVERIFIED]` | Served-state miss — echoed fresh `HASH│content` |
|
|
199
|
+
| `[E_UNDO_STALE]`/`[E_UNDO_UNAVAILABLE]` | Undo stale / unavailable |
|
|
200
|
+
| `[E_NOOP_LOOP]`/`[E_BATCH_ABORT]` | 3× same no-op / atomic batch fail → nothing written |
|
|
201
|
+
|
|
202
|
+
Full list in `src/` — every rejection echoes fresh rows, no `read` needed.
|
|
291
203
|
|
|
292
204
|
## Comparison
|
|
293
205
|
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
| | **dsh-better-edit** (this) | @oh-my-pi/hashline | `str_replace` (Claude Code / Codex) |
|
|
206
|
+
| | **dsh-better-edit** | @oh-my-pi/hashline | `str_replace` |
|
|
297
207
|
| --- | --- | --- | --- |
|
|
298
|
-
|
|
|
299
|
-
|
|
|
300
|
-
|
|
|
301
|
-
|
|
|
302
|
-
|
|
|
303
|
-
|
|
|
304
|
-
|
|
|
305
|
-
|
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
### Different jobs, same lineage
|
|
314
|
-
|
|
315
|
-
Both this plugin and `@oh-my-pi/hashline` descend from the harness-problem insight that
|
|
316
|
-
the model should never re-type old code, but they are different layers.
|
|
317
|
-
|
|
318
|
-
`@oh-my-pi/hashline` is a **patch-language library**: `[path#tag]` headers bind every hunk
|
|
319
|
-
to a full-file content hash, `PUT N.=M:` addresses lines by number, and it ships multi-hunk
|
|
320
|
-
documents, a pluggable filesystem for any backend (disk, in-memory, network), and
|
|
321
|
-
session-aware 3-way-merge recovery on stale tags. Its payload per edit is lighter and it cannot
|
|
322
|
-
be confused by repeated text — the line number is unambiguous.
|
|
323
|
-
This plugin is a **dsh tool pair**: `read` hands the model 3-char content hashes, `edit`
|
|
324
|
-
takes two of them, and every resolved line is verified against the served state — no line
|
|
325
|
-
numbers to renumber, no tag to refetch, a wrong anchor can never land on the wrong line,
|
|
326
|
-
and `undo_last_edit` survives restarts. Its trade-offs: a JSON envelope per edit costs a
|
|
327
|
-
little payload, and it lives inside dsh (Node) rather than as a standalone patcher (Bun). Pick
|
|
328
|
-
hashline-the-library for a cross-backend patch format; pick hashline-the-tool for verified,
|
|
329
|
-
content-addressed edits in your agent. Syntax-aware structural edits and file-lifecycle operations
|
|
330
|
-
remain outside this verified line-range contract.
|
|
331
|
-
|
|
332
|
-
### What you get
|
|
333
|
-
|
|
334
|
-
- **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.
|
|
335
|
-
- **Session-keyed** — sub-agent serves never validate the main session's edits and vice versa.
|
|
336
|
-
- **Drift notices** — served territory outside the range that changed on disk is reported once per episode, not as a warning.
|
|
337
|
-
- **Chained without re-reads** — diff, auto-read, and rejection rows all count as serves.
|
|
338
|
-
- **Atomic batch** — up to 32 same-file edits in one `edit` call, all-or-nothing with `[E_BATCH_ABORT]`.
|
|
339
|
-
- **Formatter-tolerant** — ASCII-whitespace-insensitive anchors survive re-indents; unique by construction (bitset probing).
|
|
340
|
-
|
|
341
|
-
### Correctness in edge cases
|
|
342
|
-
|
|
343
|
-
The battery below measures *behavior*, where the two hashline implementations actually
|
|
344
|
-
diverge. These are the real failure modes from the harness-problem literature, and what
|
|
345
|
-
each tool does when they hit:
|
|
346
|
-
|
|
347
|
-
| Edge case | hashline `edit` (this) | @oh-my-pi/hashline patch |
|
|
348
|
-
| --- | --- | --- |
|
|
349
|
-
| 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 |
|
|
350
|
-
| 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 |
|
|
351
|
-
| 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 |
|
|
352
|
-
| 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 |
|
|
353
|
-
| 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 |
|
|
354
|
-
| 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 |
|
|
355
|
-
|
|
356
|
-
> The oh-my-pi payload saving is a lighter wire format; the table above is what that format
|
|
357
|
-
> asks the model to hold in its head instead — renumbering, tag-chasing — the
|
|
358
|
-
> exact component that fails most with replace-style edits. This plugin's contract is:
|
|
359
|
-
> 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).
|
|
360
|
-
|
|
361
|
-
### Reproducible benchmark
|
|
362
|
-
|
|
363
|
-
The claims above are measured, not asserted. Two deterministic batteries — no LLM in the
|
|
364
|
-
loop, no sampling: a run either reproduces or it doesn't.
|
|
365
|
-
|
|
366
|
-
**Tool battery — 23 scenarios (2026-08-17):**
|
|
367
|
-
|
|
368
|
-
| vs expected verdict | correct | silent data-loss cases |
|
|
369
|
-
| --- | --: | --: |
|
|
370
|
-
| **dsh-better-edit** (same algorithm as pi-better-edit 1.1.4) | **23/23** | 0 |
|
|
371
|
-
|
|
372
|
-
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.
|
|
373
|
-
|
|
374
|
-
Full method, per-scenario tables, and limitations: upstream [benchmarks/README.md](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/README.md)
|
|
375
|
-
and [benchmarks/results/](https://github.com/Rianico/pi-better-edit/tree/main/benchmarks/results).
|
|
376
|
-
|
|
377
|
-
> See [Configuration](#configuration) under [Quick Start](#quick-start) for guidance overrides and store tenancy.
|
|
208
|
+
| Address | `HASH│` 3-char canon | `[path#tag]` + line | text match |
|
|
209
|
+
| Whitespace-insen. | ✅ | ~ n/a | ❌ |
|
|
210
|
+
| Duplicate lines | ✅ unique | ~ pos | ❌ first |
|
|
211
|
+
| Verified vs served | ✅ every line | ~ file tag | ❌ |
|
|
212
|
+
| Blind edit | ✅ reject | ~ | ❌ |
|
|
213
|
+
| Batch atomic | ✅ | ✅ | ❌ |
|
|
214
|
+
| Undo | ✅ | ❌ | ❌ |
|
|
215
|
+
| Battery | 23/23 | 10/10 | — |
|
|
216
|
+
|
|
217
|
+
`~` partial, `—` n/a. Same lineage — patch library vs dsh tool pair; pick by seam.
|
|
218
|
+
|
|
219
|
+
**Edge cases:** wrong anchor impossible (verified), disk drift → reject+serve, shift above → nothing moves, repeats → unique/ambiguous, unseen → reject, batch → atomic. See upstream [benchmarks](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/README.md).
|
|
220
|
+
|
|
221
|
+
**Battery:** `23/23` tool, `10/10` library (upstream `npm run eval`, same algorithm).
|
|
378
222
|
|
|
379
223
|
## How Anchors Work
|
|
380
224
|
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
between edits does not invalidate it. Everything that is not ASCII whitespace stays
|
|
387
|
-
significant — string contents, regex classes, comments, quotes, semicolons, and Unicode
|
|
388
|
-
whitespace (NBSP) all rotate the anchor. One caveat: ASCII whitespace *inside* string
|
|
389
|
-
literals and regexes is stripped too, so a whitespace-only change within a string is
|
|
390
|
-
invisible to verification — benign in practice because formatters never alter string
|
|
391
|
-
contents. Token-level edits (quote style, semicolons, brace placement) therefore still
|
|
392
|
-
reject as stale.
|
|
393
|
-
|
|
394
|
-
The alphabet is sized for an LLM consumer — the model tokenizes rather than squinting at
|
|
395
|
-
glyphs, so case and digits are all included. The URL-safe specials `-` and `_` are
|
|
396
|
-
deliberately excluded: a hash starting with `-` is shape-identical to a diff-preview
|
|
397
|
-
deletion row, and `-`/`_` at a line start are markdown-active, inviting mis-copying.
|
|
398
|
-
|
|
399
|
-
Anchors are unique by construction. If a line's base hash collides with an already-assigned
|
|
400
|
-
hash, the next free hash is allocated from a bitset by probing with a stride coprime to the
|
|
401
|
-
hash space (O(1) amortized; the stride is 62² + 62 + 1, so runs of blank lines or repeated
|
|
402
|
-
`}` land on anchors that differ in all three characters). Every line therefore gets a
|
|
403
|
-
unique anchor; two byte-identical lines never share one. The same guarantee sets the file
|
|
404
|
-
size cap: at most 238,328 lines per file, beyond which `read` and `edit` reject with
|
|
405
|
-
`[E_FILE_TOO_LARGE]` (use `write` for very large files).
|
|
406
|
-
|
|
407
|
-
Hashes live in a persistent per-file store
|
|
408
|
-
(`<workspace>/.dsh_better_edit/hash-store.sqlite`, honoring `XDG_CONFIG_HOME` on
|
|
409
|
-
non-Windows) that keeps the hashes of unchanged lines across edits.
|
|
410
|
-
|
|
411
|
-
## How It Replaces the Built-in Tools
|
|
412
|
-
|
|
413
|
-
dsh's tool registry resolves per scope: an agent sees `agent → preset → global`, and its **own**
|
|
414
|
-
layer always wins. The built-in `read`/`edit` live on the agent-preset layer, so a plain global
|
|
415
|
-
registration cannot replace them. This plugin:
|
|
416
|
-
|
|
417
|
-
1. Mounts as a host-plane Cordis plugin via its `cordis.patch.yml` bundle patch.
|
|
418
|
-
2. On `agent/session-start`, registers the hashline tools **and** the `tool:read` / `tool:edit`
|
|
419
|
-
prompt sections on the agent's own scope layer — they shadow the preset's built-ins for that
|
|
420
|
-
agent and unwind automatically when the agent is disposed.
|
|
421
|
-
3. Leaves the built-in `write` in place: a scoped `tools/pre-execute` listener rejects an exact
|
|
422
|
-
same-session/path/line served-anchor echo before dispatch, and `tools/post-execute` appends the
|
|
423
|
-
hashline auto-read to successful results.
|
|
424
|
-
|
|
425
|
-
## Store
|
|
426
|
-
|
|
427
|
-
Hash snapshots, served-state rows, and undo history live in one SQLite store — **central by default** (`$DSH_HOME/plugins/dsh-better-edit/runtime/<name>-<hash8>/hash-store.sqlite`, `ls`-readable with `.wsPath` sidecar). Legacy co-located `<workspace>/.dsh_better_edit/` is still supported via `storeDir: workspace` in `config.yaml` and is copied once on first central open. Parallel sessions in different workspaces keep separate stores (the session cwd is carried through each tool call), so one project's anchors and undo history never leak into another's. Outside a tool call (tests, previews) the store falls back to the shared DeepSeek Harness home (`$DSH_HOME/plugins/dsh-better-edit/hash-store.sqlite`).
|
|
428
|
-
|
|
429
|
-
A 7-day TTL prunes served rows; `undo_ttl_s` (default 7d, `-1` forever) prunes undo clones; missing-file snapshots are pruned on throttled `openStore`; corrupt stores are quarantined and rebuilt automatically. The central janitor (`apply` + `agent/session-start` throttled >24h) evicts `mtime>storeMaxAgeS` (default 2592000 s = 30 days) then LRU to `count<100 && sum<500MB`, never deleting live `hash(workspaceCwd)`, with `wal_checkpoint(TRUNCATE)` on close. DB files are disposable caches — safe to delete, rebuilt on next `read`.
|
|
225
|
+
`canon(line)` strips ASCII whitespace → `xxHash32` → `A-Za-z0-9` 3-char (62³). Stable across `prettier`; Unicode/strings stay significant except ASCII whitespace inside strings (linter-only). `stride=62²+62+1` probes bitset → unique; cap `238,328`. Store `hash-store.sqlite` per workspace (central, honoring `XDG_CONFIG_HOME`); 7-day served TTL, janitor `storeMaxAgeS/LRU` + `wal_checkpoint`.
|
|
226
|
+
|
|
227
|
+
## How It Replaces Built-ins
|
|
228
|
+
|
|
229
|
+
dsh resolves `agent → preset → global`; built-ins live on preset. Plugin via `cordis.patch.yml`: at `agent/session-start` registers `read/edit` on agent layer (shadows, auto-unwinds); `write` stays with `pre-execute` guard + `post-execute` auto-read.
|
|
430
230
|
|
|
431
231
|
## Project Structure
|
|
432
232
|
|
|
433
233
|
```
|
|
434
234
|
dsh-better-edit/
|
|
435
|
-
├── src/
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
│ ├── served-store.ts # per-workspace SQLite store (node:sqlite)
|
|
443
|
-
│ └── workspace.ts # session-cwd AsyncLocalStorage carrier
|
|
444
|
-
├── benchmark/ # frozen 103-line fixture (reference upstream for reproducible numbers)
|
|
445
|
-
│ └── corpus/ # frozen 103-line fixture
|
|
446
|
-
├── test/ # ported + regression tests
|
|
447
|
-
├── assets/ # logo + banner
|
|
448
|
-
├── cordis.patch.yml # bundle patch
|
|
449
|
-
└── package.json # dsh.bundle manifest
|
|
235
|
+
├── src/hashline/ # hash + served core
|
|
236
|
+
├── src/tool-*.ts # read / edit / undo
|
|
237
|
+
├── src/served-store.ts # SQLite store
|
|
238
|
+
├── benchmark/corpus/ # 103-line fixture
|
|
239
|
+
├── test/ # 108 files, 1222 tests
|
|
240
|
+
├── assets/ # logo + banner
|
|
241
|
+
└── cordis.patch.yml
|
|
450
242
|
```
|
|
451
243
|
|
|
452
244
|
## Development
|
|
453
245
|
|
|
454
246
|
```sh
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
247
|
+
pnpm install
|
|
248
|
+
pnpm typecheck # tsc --noEmit
|
|
249
|
+
pnpm test # vitest run
|
|
250
|
+
pnpm benchmark # hash probe + session envelope (reads/retries/tokens)
|
|
459
251
|
```
|
|
460
252
|
|
|
461
|
-
|
|
253
|
+
## Benchmark
|
|
462
254
|
|
|
463
|
-
|
|
464
|
-
npm run release -- 0.3.1 # bump + CHANGELOG move + commit + tag + push → GitHub release
|
|
465
|
-
npm publish --registry https://registry.npmjs.org # blocked until the version is tagged
|
|
466
|
-
```
|
|
255
|
+
103-line file, 12 replacements (8×1 + 4×3/6/10/15), `cl100k_base`. `hashline` vs `str_replace` vs `oh-my-pi` `seq/batch`. Upstream is source of truth — same algorithm byte-for-byte.
|
|
467
256
|
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
257
|
+
| Criterion | hashline | str_replace | seq / batch |
|
|
258
|
+
| --- | :---: | :---: | :---: |
|
|
259
|
+
| `old_string` echoed | never | every edit | never |
|
|
260
|
+
| 12-edit saved | **31%** | 0% | **42% / 53%** |
|
|
261
|
+
| multi-line saved | **29–47%** | 0% | **40–53%** |
|
|
262
|
+
| 5× output cost | **~1.4× less** | 1× | **~1.7×/~2.1× less** |
|
|
263
|
+
| Verified | 100% | none | tag only |
|
|
472
264
|
|
|
473
|
-
|
|
265
|
+
| Scenario | hashline | str_replace |
|
|
266
|
+
| --- | ---: | ---: |
|
|
267
|
+
| `1×8` | 309 | 324 |
|
|
268
|
+
| `3–15×4` | 393 | 691 |
|
|
269
|
+
| **TOTAL ×12** | **702** | **1015** |
|
|
270
|
+
|
|
271
|
+
Saved **313 (31%)**. Reproduce: upstream `npm run benchmark`. See [`pi-better-edit/benchmark/README.md`](https://github.com/Rianico/pi-better-edit/blob/main/benchmarks/README.md).
|
|
474
272
|
|
|
475
|
-
|
|
476
|
-
3/6/10/15 lines), tokenized with the pinned `js-tiktoken` `cl100k_base`. Three arms emit the same
|
|
477
|
-
replacements: this plugin's `edit` (two 3-char anchors via `edits` tuple), a `str_replace` tool (old text echoed
|
|
478
|
-
verbatim), and [`@oh-my-pi/hashline`](https://www.npmjs.com/package/@oh-my-pi/hashline) in both of
|
|
479
|
-
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:
|
|
480
|
-
|
|
481
|
-
| Criterion | hashline | str_replace | oh-my-pi seq / batch |
|
|
482
|
-
| ----------- | :---: | :---: | :---: |
|
|
483
|
-
| Replaced text sent over the wire | ✅ never | ❌ every edit | ✅ never |
|
|
484
|
-
| Output tokens saved (12-edit session) | ✅ **31%** | ❌ 0% | ✅ **42% / 53%** |
|
|
485
|
-
| Multi-line range savings (3–15 lines) | ✅ **29–47%** | ❌ 0% | ✅ **40–53%** |
|
|
486
|
-
| Effective cost at 5× output pricing | ✅ **~1.4× less** | ❌ 1× | ✅ **~1.7× / ~2.1× less** |
|
|
487
|
-
| Ranges verified against served state | ✅ 100% | ❌ none | ~ file version only |
|
|
488
|
-
| Line numbers the model must track | ✅ none — content anchors | ✅ none — text match | ❌ renumber every edit |
|
|
489
|
-
| Deterministic, reproducible locally | ✅ via upstream `npm run benchmark` | — | — |
|
|
490
|
-
|
|
491
|
-
| Scenario | Lines | hashline | str_replace | oh-my-pi seq | oh-my-pi batch |
|
|
492
|
-
| --- | :---: | :---: | :---: | :---: | :---: |
|
|
493
|
-
| single-line ×8 | 1 | 309 | 324 | 241 | — |
|
|
494
|
-
| multi-line ×4 | 3–15 | 393 | 691 | 349 | — |
|
|
495
|
-
| **TOTAL ×12** | | **702** | **1015** | **590** | **480** |
|
|
496
|
-
|
|
497
|
-
Saved vs `str_replace`: hashline **313 (31%)** · oh-my-pi per-edit **425 (42%)** · oh-my-pi batch **535 (53%)**.
|
|
498
|
-
|
|
499
|
-
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.
|
|
500
|
-
|
|
501
|
-
> **Scope & honesty.** The benchmark measures **request-payload tokens** — what the model emits per
|
|
502
|
-
> edit call — with identical read traffic excluded (it cancels) and identical replacement text.
|
|
503
|
-
> It does **not** model transcription failure and retries, which is where the real-world gap is
|
|
504
|
-
> largest. The correctness gap behind those numbers is spelled out above in [Correctness in edge cases](#correctness-in-edge-cases).
|
|
273
|
+
> **Scope & honesty.** Benchmark is **request-payload tokens** (reads cancel, replacement text identical). No transcription-failure model — real gap larger; see [edge cases](#comparison).
|
|
505
274
|
|
|
506
275
|
## Roadmap
|
|
507
276
|
|
|
508
|
-
**Current
|
|
277
|
+
**Current `0.6.1`:** pos-free `resist`/`strict` + tombstone/canons/epoch, per-session `(session,path)` store, `1222` tests, `9/9` harness.
|
|
509
278
|
|
|
510
279
|
<details><summary>Next</summary>
|
|
511
280
|
|
|
512
|
-
-
|
|
513
|
-
-
|
|
514
|
-
-
|
|
281
|
+
- Keep `benchmark/run.mjs` in sync with `ADR-0013` (reads/retries/tokens per session)
|
|
282
|
+
- Re-check wiring vs next `dsh` (pinned `0.1.0-rc.6`)
|
|
283
|
+
- `README.zh.md` parity
|
|
515
284
|
|
|
516
285
|
</details>
|
|
517
286
|
|
|
518
287
|
## Contributing
|
|
519
288
|
|
|
520
|
-
See [CONTRIBUTING.md](CONTRIBUTING.md)
|
|
521
|
-
The most valuable contributions right now are more edge-case tests for the
|
|
522
|
-
served-state verification.
|
|
289
|
+
See [CONTRIBUTING.md](CONTRIBUTING.md). Most valuable: more served-state edge-case tests.
|
|
523
290
|
|
|
524
291
|
## License
|
|
525
292
|
|
|
526
|
-
MIT
|
|
293
|
+
MIT — see [LICENSE](LICENSE).
|
|
527
294
|
|
|
528
295
|
## Acknowledgments
|
|
529
296
|
|
|
530
|
-
|
|
531
|
-
[*The Harness Problem*](https://stencil.so/blog/the-harness-problem) — the post that showed the
|
|
532
|
-
harness, not the model, is the bottleneck, and that anchored edits beat search-and-replace. This
|
|
533
|
-
project stands on the shoulders of:
|
|
534
|
-
|
|
535
|
-
- [**pi-hashline-edit**](https://github.com/RimuruW/pi-hashline-edit) by RimuruW — the original
|
|
536
|
-
pi-coding-agent extension that introduced hash anchors and the strict-semantics
|
|
537
|
-
policy.
|
|
538
|
-
- [**pi-hashline-edit-pro**](https://github.com/YuGiMob/pi-hashline-edit-pro) by YuGiMob —
|
|
539
|
-
the hardened fork this project is self-maintained from (3-char hashes, collision
|
|
540
|
-
resolution, served-state verification, persisted undo).
|
|
541
|
-
- [**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.
|
|
542
|
-
- [**@oh-my-pi/hashline**](https://www.npmjs.com/package/@oh-my-pi/hashline)
|
|
543
|
-
by can1357 — the original oh-my-pi implementation and the hashline patch-language concept.
|
|
544
|
-
|
|
545
|
-
Related reading: [Hash anchors + Myers diff + single-token anchors
|
|
546
|
-
(dirac.run)](https://dirac.run/posts/hash-anchors-myers-diff-single-token) (a design review of the
|
|
547
|
-
O(S+R) → O(R) edit-call saving) and an independent
|
|
548
|
-
[hashline-vs-replace benchmark](https://nwyin.com/blogs/hashline-vs-replace-edit-bench.html).
|
|
297
|
+
From Can Bölük's [*The Harness Problem*](https://stencil.so/blog/the-harness-problem). Thanks to [pi-hashline-edit](https://github.com/RimuruW/pi-hashline-edit), [pi-hashline-edit-pro](https://github.com/YuGiMob/pi-hashline-edit-pro), [pi-better-edit](https://github.com/Rianico/pi-better-edit), [@oh-my-pi/hashline](https://www.npmjs.com/package/@oh-my-pi/hashline). Reading: [hash-anchors](https://dirac.run/posts/hash-anchors-myers-diff-single-token).
|
|
549
298
|
|
|
550
299
|
---
|
|
551
300
|
|
|
@@ -556,5 +305,5 @@ O(S+R) → O(R) edit-call saving) and an independent
|
|
|
556
305
|
---
|
|
557
306
|
|
|
558
307
|
<p align="center">
|
|
559
|
-
<strong>⭐ If hashline
|
|
308
|
+
<strong>⭐ If hashline made your agent edit better, give it a star!</strong>
|
|
560
309
|
</p>
|
package/lib/index.js
CHANGED
|
@@ -1,26 +1,10 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* dsh-better-edit — hash-anchored read/edit/batch_edit/undo_last_edit for
|
|
3
|
-
* DeepSeek Harness, a dsh port of pi-hashline-edit-lsz.
|
|
4
|
-
*
|
|
5
|
-
* Cordis host-plane plugin (mounted by the bundle's cordis.patch.yml). On
|
|
6
|
-
* `agent/session-start` it registers the hashline tools and prompt sections on
|
|
7
|
-
* the AGENT's own scope layer, so they shadow the preset's built-in `read` /
|
|
8
|
-
* `edit` for that agent (nearest layer wins in dsh's tool registry) and unwind
|
|
9
|
-
* automatically when the agent is disposed. The built-in `write` stays in
|
|
10
|
-
* place; scoped pre/post listeners reject copied same-line served anchors
|
|
11
|
-
* before dispatch and append a fresh hashline preview after successful writes.
|
|
12
|
-
*
|
|
13
|
-
* The four `tool:*` guidance sections resolve per agent preset from override
|
|
14
|
-
* files in the shared home (see `src/guidance.ts`); deployments without the
|
|
15
|
-
* `agentPresets` service keep the compiled defaults unchanged.
|
|
16
|
-
* @module dsh-better-edit
|
|
17
|
-
*/
|
|
18
1
|
import { ctxFsIO } from "./fs-bridge.js";
|
|
19
2
|
import { FsSandboxController } from "./sandbox.js";
|
|
20
|
-
import {
|
|
21
|
-
import {
|
|
3
|
+
import { buildReadTool } from "./tool-read.js";
|
|
4
|
+
import { buildEditTool } from "./tool-edit.js";
|
|
22
5
|
import { registerUndoTool } from "./tool-undo.js";
|
|
23
6
|
import { registerWriteHook } from "./write-hook.js";
|
|
7
|
+
import { createSelfHealWatcher } from "./self-heal.js";
|
|
24
8
|
import { initHasher } from "./hashline/hash-assign.js";
|
|
25
9
|
import { composeSections, ensurePresetGuidance, GUIDANCE_SECTIONS, } from "./guidance.js";
|
|
26
10
|
import { configDir } from "./store/index.js";
|
|
@@ -80,11 +64,24 @@ function installAgentTools(rootCtx, agent) {
|
|
|
80
64
|
// exec.agent.session.header.cwd.
|
|
81
65
|
const io = ctxFsIO(rootCtx.fs, rootCtx);
|
|
82
66
|
const disposers = [];
|
|
83
|
-
disposers.push(registerReadTool(rootCtx, agent.ctx, io));
|
|
84
67
|
const sandbox = new FsSandboxController(rootCtx);
|
|
85
|
-
|
|
68
|
+
// Keep owned definitions by reference for self-heal identity check
|
|
69
|
+
const hashReadDef = buildReadTool(io);
|
|
70
|
+
disposers.push(agent.ctx.tools.register(hashReadDef));
|
|
71
|
+
const hashEditDef = buildEditTool(io, sandbox);
|
|
72
|
+
disposers.push(agent.ctx.tools.register(hashEditDef));
|
|
86
73
|
disposers.push(registerUndoTool(rootCtx, agent.ctx, io, sandbox));
|
|
87
74
|
disposers.push(registerWriteHook(rootCtx, agent.ctx, io));
|
|
75
|
+
const toolsSvc = rootCtx.get("tools");
|
|
76
|
+
disposers.push(createSelfHealWatcher({
|
|
77
|
+
agentId: agent.id,
|
|
78
|
+
rootCtx,
|
|
79
|
+
agent,
|
|
80
|
+
agentCtx: agent.ctx,
|
|
81
|
+
toolsSvc,
|
|
82
|
+
hashReadDef,
|
|
83
|
+
hashEditDef,
|
|
84
|
+
}));
|
|
88
85
|
// Shadow the preset's built-in tool guidance with the hashline
|
|
89
86
|
// contract. Same section names on the agent's own layer win over the
|
|
90
87
|
// preset's; text and order come from the per-preset resolution.
|
package/lib/self-heal.js
ADDED
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Self-healing watcher for hash-anchored tools.
|
|
3
|
+
* Restores `read`/`edit` on the agent's own scope layer if an external
|
|
4
|
+
* preset deletes them (e.g. router-standard stage advance).
|
|
5
|
+
* See Rianico/dsh-better-edit#43.
|
|
6
|
+
* @module dsh-better-edit/self-heal
|
|
7
|
+
*/
|
|
8
|
+
export function createSelfHealWatcher(options) {
|
|
9
|
+
const { agentId, rootCtx, agent, agentCtx, toolsSvc, hashReadDef, hashEditDef, healMinIntervalMs = 1000, } = options;
|
|
10
|
+
let lastHealAt = 0;
|
|
11
|
+
let healCount = 0;
|
|
12
|
+
let selfHealDisabled = false;
|
|
13
|
+
const stop = agentCtx.on("tools/change", () => {
|
|
14
|
+
try {
|
|
15
|
+
if (selfHealDisabled)
|
|
16
|
+
return;
|
|
17
|
+
// SAFETY: toolsSvc is the DSH tools service — shape is `layers.scoped: Map<agent, {tools}>` per cordis internals; narrow at boundary
|
|
18
|
+
const layer = toolsSvc
|
|
19
|
+
?.layers?.scoped?.get?.(agent)?.tools;
|
|
20
|
+
if (!layer)
|
|
21
|
+
return;
|
|
22
|
+
const currentRead = layer?.get?.("read") ?? layer?.data?.get?.("read");
|
|
23
|
+
const currentEdit = layer?.get?.("edit") ?? layer?.data?.get?.("edit");
|
|
24
|
+
const readOk = currentRead === hashReadDef;
|
|
25
|
+
const editOk = currentEdit === hashEditDef;
|
|
26
|
+
if (readOk && editOk)
|
|
27
|
+
return;
|
|
28
|
+
const now = Date.now();
|
|
29
|
+
if (now - lastHealAt < healMinIntervalMs)
|
|
30
|
+
return;
|
|
31
|
+
if (healCount >= 2) {
|
|
32
|
+
selfHealDisabled = true;
|
|
33
|
+
try {
|
|
34
|
+
rootCtx.logger.error(`dsh-better-edit: repeated takeover of edit detected; self-heal disabled for agent ${agentId} \u2014 edit will remain built-in for this session \u2014 see Rianico/dsh-better-edit#43`);
|
|
35
|
+
}
|
|
36
|
+
catch {
|
|
37
|
+
// ignore — logger may throw in mock
|
|
38
|
+
}
|
|
39
|
+
return;
|
|
40
|
+
}
|
|
41
|
+
healCount++;
|
|
42
|
+
lastHealAt = now;
|
|
43
|
+
const restoreRead = !readOk;
|
|
44
|
+
const restoreEdit = !editOk;
|
|
45
|
+
const restoreCount = healCount;
|
|
46
|
+
queueMicrotask(() => {
|
|
47
|
+
try {
|
|
48
|
+
// SAFETY: re-read layer inside microtask — same shape as above
|
|
49
|
+
const currentLayer = toolsSvc
|
|
50
|
+
?.layers?.scoped?.get?.(agent)?.tools;
|
|
51
|
+
if (!currentLayer)
|
|
52
|
+
return;
|
|
53
|
+
if (restoreEdit) {
|
|
54
|
+
try {
|
|
55
|
+
currentLayer?.data?.delete?.("edit");
|
|
56
|
+
}
|
|
57
|
+
catch {
|
|
58
|
+
// ignore — best-effort delete of intruding entry
|
|
59
|
+
}
|
|
60
|
+
try {
|
|
61
|
+
agentCtx.tools.register(hashEditDef);
|
|
62
|
+
}
|
|
63
|
+
catch (e) {
|
|
64
|
+
rootCtx.logger.warn(`dsh-better-edit: self-heal failed for agent ${agentId}: ${e instanceof Error ? e.message : String(e)} \u2014 see Rianico/dsh-better-edit#43`);
|
|
65
|
+
return;
|
|
66
|
+
}
|
|
67
|
+
rootCtx.logger.warn(`dsh-better-edit: restored hash-anchored edit after external takeover \u2014 agent ${agentId} (${restoreCount}/2) \u2014 see Rianico/dsh-better-edit#43`);
|
|
68
|
+
}
|
|
69
|
+
if (restoreRead) {
|
|
70
|
+
try {
|
|
71
|
+
currentLayer?.data?.delete?.("read");
|
|
72
|
+
}
|
|
73
|
+
catch {
|
|
74
|
+
// ignore — best-effort delete of intruding entry
|
|
75
|
+
}
|
|
76
|
+
try {
|
|
77
|
+
agentCtx.tools.register(hashReadDef);
|
|
78
|
+
}
|
|
79
|
+
catch (e) {
|
|
80
|
+
rootCtx.logger.warn(`dsh-better-edit: self-heal failed for agent ${agentId}: ${e instanceof Error ? e.message : String(e)} \u2014 see Rianico/dsh-better-edit#43`);
|
|
81
|
+
return;
|
|
82
|
+
}
|
|
83
|
+
rootCtx.logger.warn(`dsh-better-edit: restored hash-anchored read after external takeover \u2014 agent ${agentId} (${restoreCount}/2) \u2014 see Rianico/dsh-better-edit#43`);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
catch (error) {
|
|
87
|
+
rootCtx.logger.warn(`dsh-better-edit: self-heal failed for agent ${agentId}: ${error instanceof Error ? error.message : String(error)} \u2014 see Rianico/dsh-better-edit#43`);
|
|
88
|
+
}
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
catch (error) {
|
|
92
|
+
try {
|
|
93
|
+
rootCtx.logger.warn(`dsh-better-edit: self-heal failed for agent ${agentId}: ${error instanceof Error ? error.message : String(error)} \u2014 see Rianico/dsh-better-edit#43`);
|
|
94
|
+
}
|
|
95
|
+
catch {
|
|
96
|
+
// ignore — logger may throw in mock
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
});
|
|
100
|
+
return stop;
|
|
101
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Self-healing watcher for hash-anchored tools.
|
|
3
|
+
* Restores `read`/`edit` on the agent's own scope layer if an external
|
|
4
|
+
* preset deletes them (e.g. router-standard stage advance).
|
|
5
|
+
* See Rianico/dsh-better-edit#43.
|
|
6
|
+
* @module dsh-better-edit/self-heal
|
|
7
|
+
*/
|
|
8
|
+
export interface SelfHealOptions {
|
|
9
|
+
agentId: string;
|
|
10
|
+
rootCtx: {
|
|
11
|
+
logger: {
|
|
12
|
+
warn(msg: string): void;
|
|
13
|
+
error(msg: string): void;
|
|
14
|
+
};
|
|
15
|
+
get(service: string): any;
|
|
16
|
+
};
|
|
17
|
+
agent: unknown;
|
|
18
|
+
agentCtx: {
|
|
19
|
+
tools: {
|
|
20
|
+
register(def: unknown): () => void;
|
|
21
|
+
};
|
|
22
|
+
on(event: string, handler: () => void): () => void;
|
|
23
|
+
};
|
|
24
|
+
toolsSvc: unknown;
|
|
25
|
+
hashReadDef: unknown;
|
|
26
|
+
hashEditDef: unknown;
|
|
27
|
+
healMinIntervalMs?: number;
|
|
28
|
+
}
|
|
29
|
+
export declare function createSelfHealWatcher(options: SelfHealOptions): () => void;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-better-edit",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.3",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Hash-anchored read/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",
|
|
@@ -84,12 +84,12 @@
|
|
|
84
84
|
"@commitlint/cli": "^21.2.2",
|
|
85
85
|
"@commitlint/config-conventional": "^21.2.2",
|
|
86
86
|
"@deepseek-ai/cordis": "^4.0.1",
|
|
87
|
-
"@deepseek-ai/dsh-agent": "0.1.
|
|
88
|
-
"@deepseek-ai/dsh-fs": "0.1.
|
|
89
|
-
"@deepseek-ai/dsh-home-paths": "0.1.
|
|
90
|
-
"@deepseek-ai/dsh-sandbox": "
|
|
91
|
-
"@deepseek-ai/dsh-session": "0.1.
|
|
92
|
-
"@deepseek-ai/dsh-tools": "0.1.
|
|
87
|
+
"@deepseek-ai/dsh-agent": "0.1.1-rc.2",
|
|
88
|
+
"@deepseek-ai/dsh-fs": "0.1.1-rc.2",
|
|
89
|
+
"@deepseek-ai/dsh-home-paths": "0.1.1-rc.2",
|
|
90
|
+
"@deepseek-ai/dsh-sandbox": "0.1.1-rc.2",
|
|
91
|
+
"@deepseek-ai/dsh-session": "0.1.1-rc.2",
|
|
92
|
+
"@deepseek-ai/dsh-tools": "0.1.1-rc.2",
|
|
93
93
|
"@semantic-release/changelog": "^7.0.0",
|
|
94
94
|
"@semantic-release/git": "^11.0.1",
|
|
95
95
|
"@semantic-release/github": "^12.0.9",
|