dsh-hashline-edit
Verifieddsh-hashline-edit · v0.4.0 · MIT · Web UI
Hash-anchored read/apply_patch/edit tools for DeepSeek Harness (dsh). Every line gets a unique 3- or 4-char hash (A-Za-z0-9, configurable) that stays stable across edits; apply_patch and the anchored range edit tool are the file-mutation entry points, eac
Install
dsh plugin add dsh-hashline-edit Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Readme
dsh-hashline-edit
Hash-anchored file editing for DeepSeek Harness (dsh) on Windows.
dsh-hashline-edit is a dsh bundle that shadows the host's built-in read with hash-anchored output and offers two write tools over the same served rows: apply_patch for Codex patch documents and edit for anchored range edits. The host's built-in write stays visible and is integrated by the write hook; while either plugin write tool is registered, the native edit/str_replace_editor/apply_patch surface is hidden. There is no pi host support, because this package targets DeepSeek Harness only. Every line a served read shows carries a stable 3- or 4-character base62 anchor (A–Z, a–z, 0–9; the width is a build-time setting, see Anchor width) derived from the file's canonical path and the line's content. apply_patch hunks either name served anchors or match file content; every edit item names served anchors. The model never re-types existing code. Anchors for unchanged lines stay stable across edits, and every successful mutation returns fresh anchors for the changed lines, so chained calls need no re-read.
The semantic core is the pi-better-edit v2.16.0 hashline engine (MIT), carried as an internal engine; the pi host integration has been removed. The dsh/ tree is this repository's DeepSeek Harness host layer: tool registration, filesystem bridge, UTF-8-only admission, prompt guidance, shell integration, write integration and telemetry. See dsh/README.md for the host-layer map.
Requirements
| Requirement | Version |
|---|---|
| OS | Windows — this branch targets Windows only (see dsh/UPSTREAM.md) |
| Node.js | ≥ 24.0.0 |
| pnpm | 12.x |
| DeepSeek Harness | plugin-capable build; the repository is developed against @deepseek-ai/dsh-*@0.2.2-rc.1 (host packages are declared as peer dependencies) |
Anchor width (3 or 4)
The anchor width is baked into the build. Set PI_BETTER_EDIT_ANCHOR_WIDTH when you build or pack:
- unset builds the 3-char default.
PI_BETTER_EDIT_ANCHOR_WIDTH=4 pnpm run build(andpnpm pack) produces a fully 4-char artifact.
| Value | Anchor width | Usable space | Anchor generation |
|---|---|---|---|
| unset (default) | 3 chars | 237,328 | 2 |
4 |
4 chars | 14,766,336 | 1 |
The value is inlined into the bundle at build time (esbuild define), so the installed plugin never reads an environment variable at runtime — a 3-char build stays 3-char. The persisted store is keyed by the anchor generation, so changing the build width is a hard cache miss (served rows are simply re-read), never a cross-width hit. Width 4 keeps generation 1, so existing stores keep working unchanged.
Prompt prose is width-neutral: shipped prompt files use the {{HASH_LEN}} placeholder, resolved from the baked width, so a 3-char and a 4-char build each expose their own width through every prompt and guidance surface.
Measured on the DeepSeek-V4.1 tokenizer, a 3-char anchor averages ~2.3 tokens and a 4-char anchor ~3.0 tokens per served line, and neither collapses to one token (see ADR-0020). The default is 3; build with PI_BETTER_EDIT_ANCHOR_WIDTH=4 to ship the 4-char artifact, whose generation-1 store keeps existing rows valid.
Install
Build the plugin first: the dsh loader reads the package through exports/main, and lib/ is gitignored.
pnpm install
pnpm run build
dsh plugin add <path-to-repo-or-tgz>
To keep the install isolated, use a throwaway profile:
dsh plugin --profile scratch-hashline add <path-to-repo>
dsh --profile scratch-hashline --dump-config # the bundle row is composed
For a tarball, pack first and add the archive:
pnpm pack
dsh plugin add ./dsh-hashline-edit-0.2.1.tgz
The bundle ships lib/index.js plus lib/types/**; prompts/ must sit next to lib/ in the installed package (it is in files). Guidance text is bundled with the package and injected statically — there is no runtime override file.
The anchored model
A served read looks like this (│ is U+2502, the separator):
ve7│function calculateTotal(items: CartItem[]): number {
szJ│ let total = 0;
kQm│ for (const item of items) {
m2z│ total += item.price;
d2x│ }
p9r│ return total;
a1b│}
Copy only the build-width characters before │ (3 by default; 4 in a 4-char build). edit passes them as anchor_from / anchor_to; apply_patch writes them as @@<anchor> for one row or @@<from>-<to> for a span. Both forms target an inclusive served range; a successful call returns a diff whose modified and context rows carry fresh anchors:
- szJ│ let total = 0;
- kQm│ for (const item of items) {
- m2z│ total += item.price;
+w4k│ let total = items.reduce((sum, item) => sum + item.price, 0);
d2x│ }
Served anchors are leased per session and per file. A stale, unknown, retired or foreign anchor is refused with a [MODEL] [E_*] message; range refusals return the current rows as a fresh read (Current range (fresh read):) so the model can retry from the rejection alone. An ordinary refusal writes nothing; a foreign-source cut is ordered and repair-backed rather than filesystem-atomic across a crash.
Tools
Live switches and profiles
read, applyPatch and edit are three live per-agent switches. The host reloads the bundle row and remounts every live agent, so flipping one takes effect without a rebuild. read shadows the built-in read and enables the shell/grep views; applyPatch registers the apply_patch tool; edit registers the anchored range edit tool.
| Switch | Default | Effect |
|---|---|---|
read |
true |
Register the hash-anchored read tool and its shell/grep views. |
applyPatch |
true |
Register the apply_patch tool. |
edit |
false |
Register the anchored range edit tool. |
The two mutation switches form three supported profiles. With both mutation switches off, neither write tool is registered and the native-hide layer is not installed; the native editors and the host's built-in write stay visible. Each snippet below is the config block of the dsh-hashline-edit row:
# apply_patch only (the shipped default)
config: { read: true, applyPatch: true, edit: false }
# both mutation tools
config: { read: true, applyPatch: true, edit: true }
# edit only
config: { read: true, applyPatch: false, edit: true }
read
read({
path: string, // relative or absolute; the dsh tool takes `path`, not `file`
offset?: number, // 1-indexed start; a bare offset reads a window (default limit 50)
limit?: number,
windows?: Array< // up to 16 disjoint windows in one call
| { offset: number; limit: number }
| { around_anchor: string; radius?: number } // radius defaults to 10
>,
mode?: "served" | "verbatim", // default "served"
})
- Served mode returns one
HASH│contentrow per line and records every shown row as a lease for this session. A windowed read also includes a[Lines A-B of N total]page header. Every row shown is usable by one subsequentapply_patchoredit, even when the windows are far apart. - Verbatim mode returns the same page as plain text with no anchors and serves nothing; an
apply_patchidentity hunk or anedititem cannot target those lines. - A small requested window — up to 61 lines after folding — may widen to its enclosing function, method, class, section or paragraph; a
[widened …]note names the block that was served. Expansion applies in both modes. Languages: TypeScript/TSX, Python, Go, Rust, Java and Vue through pinned tree-sitter wasm grammars (fetched lazily and verified against a committed SHA-256), plus Bash through the existingunbashparser (no wasm). Vue widens a top-leveltemplate/script/styleblock without parsing embedded JS/TS. SQL is not supported: real migrations largely fail to parse and.tqlis a Java template, not SQL (seedocs/spec/sql-vue-feasibility-gate.md). offset/limitandwindowsare page requests, not anchors: onlyservedoutput grants mutation leases.
apply_patch
One of the two write tools: the precise, batch patch-document surface. It shares
the served anchors, lease store and mutation queue with edit; the host's built-in write stays
available for whole-file rewrites. One call carries one Codex patch document and commits the whole
batch as one correlated transaction (pre-mirror, undo rows, deterministic member order, all-or-nothing
rollback, then per-file store commits).
*** Begin Patch
*** Update File: src/config.ts
@@
- retries: 3,
+ retries: 5,
*** Add File: src/new.ts
+export const x = 1;
*** End Patch
Addressing works in two modes, and one patch may mix them:
- Fragment hunks use the official Codex syntax.
@@starts the search window at the file start;@@ <one context line>moves the window after that line's unique match. Body lines are(context),-(remove) and+(add). Matching is byte-exact and must be unique: zero or multiple matches reject the whole call and serve the candidate rows back. - Identity hunks use the
@@<a>/@@<a>-<b>extension: two inclusive anchors of this build's width (3 or 4 chars) from rows this session served. The body is+lines only; an empty body deletes the span. A stale, unknown or foreign anchor is rejected with the file's current rows served. - Reference hunks
*** Copy From: <path> <a>-<b>/*** Cut From: <path> <a>-<b>take the bytes of another served span; a cut also retires the source span in the same transaction. - Lifecycle
*** Add File:,*** Delete File:and*** Move to:join text edits in the same transaction and the same undo record.*** End of Filepins a hunk to the file tail.
@@ followed by a space is Codex's context mode; @@ immediately followed by HASH_LEN anchor
characters is identity mode. Any rejection leaves every file byte-identical and reports every
independent problem with its patch line number and [E_*] code. Success returns a file-level summary
(A/M/R/D) followed by fresh HASH│content anchors for every changed line, so the next call can chain
without a read. To replace a whole file, use one *** Update File: identity hunk spanning every served line.
edit
The anchored range writer. One call targets one file and carries one ordered edits array, so N changes in that file are N items in the same call.
{
"file": "src/config.ts",
"edits": [
{ "anchor_from": "szJ", "anchor_to": "szJ", "text": " retries: 5," },
{
"anchor_from": "d2x",
"anchor_to": "d2x",
"text_ref": { "anchor_from": "a1b", "anchor_to": "a1b", "file": "src/defaults.ts", "mode": "copy" }
}
]
}
Each item names two inclusive bare anchors and exactly one payload: text is the replacement content ("" deletes the range), or text_ref is a served span read in copy or cut mode. Optional at is in-place by default; before / after insert at the boundary and require a single-line target. A text_ref.file may name another served file as the copy/cut source, and cut also retires those source lines; the call's own target remains one file. The retired item-level file field is not part of the payload — an old multi-file item shape is refused with [E_BAD_PAYLOAD], and a different target file is a different call. The call commits as one transaction and writes one undo record for recovery; undo is not exposed as a model tool.
Shell view
The plugin installs a tools/post-execute listener for the host's pwsh, bash and built-in grep tools. When the command is a whitelisted read-only file view, the captured stdout is replaced with the aligned file's HASH│content rows, and those rows are served (leased) exactly like a read — a following apply_patch or edit can use them with no re-read. A built-in grep result whose matches are proven against disk is served the same way (see the table below).
| Command shape | Served as |
|---|---|
Get-Content <file>, type <file>, cat <file> |
the file's lines |
Get-Content <file> | Select-Object -First|-Last|-Skip <N> |
the bounded slice |
Get-Content <file> | Select-Object -Skip N -First M (either order) |
disk lines N+1 through N+M |
Select-String <pattern> <file> |
the matched lines, with their line numbers |
rg <pattern> <file> (explicit single file, no switches) |
the matched lines, with their line numbers |
built-in grep (@deepseek-ai/dsh-tool-fs-search) |
the matched lines grouped per file, each row HASH│content |
The grep view applies the host's spill policy: at most 250 matches and at most 12,500 inline tokens (the host estimate ceil(chars / 4) + 4). A result over either cap, a failed call, a forged or stale match line, or non-ascending coordinates passes through byte-for-byte with no lease.
Alignment is strict: stdout lines are mapped to 1-based disk line numbers with a monotonic, unique match (search output's own line numbers are used as hints). Every served view is prefixed with the shared [Bash view: <file> (lines a-b of N total)] page header, so the positions the raw output used to name are not lost. Anything the view cannot prove — an unknown pipeline, a statement separator (;), a variable path ($f), a wildcard, formatted output, a truncated capture, a failed command — passes through byte-for-byte. The hook never guesses and never serves the wrong occurrence of a duplicated line.
Encoding: UTF-8 only
The dsh host reads and writes UTF-8. Read admission is one rule with one exemption:
- a leading UTF-8 BOM (
EF BB BF) is stripped, so it never reaches an anchor; - the remaining bytes must be strict UTF-8.
A file that is not valid UTF-8 is refused with [E_UNSUPPORTED_FILE] naming the file path and telling the model to ask the user how to handle it — for example a GBK-encoded source file or a BOM-less UTF-16LE file. The host does not guess a code page, offers no reopen-with-encoding parameter, keeps no encoding/BOM memo, and does not re-encode on save. UTF-16/UTF-32 BOMs are still recognized by kind detection: they are named in the refusal (e.g. UTF-16LE encoded text) instead of being decoded. Convert a non-UTF-8 file with an external tool before editing it here.
apply_patch and edit speak the same contract: they write UTF-8, and every file this plugin serves is UTF-8. The built-in write integration keeps the same contract for a profile that deliberately keeps write visible.
Sandbox behavior
apply_patch and edit carry the host's optional escalation fields sandbox_permissions and justification only when a confining filesystem backend is mounted. dsh/sandbox.ts mirrors the built-in @deepseek-ai/dsh-tool-fs controller: it validates the field pairing, repeats the standing mode without approval, and resolves a strictly wider mode through the host's approval channel before touching the filesystem. A provider FS_SANDBOX_DENIED error is mapped to the standard model-facing denial marker plus escalation hint; other errors pass through unchanged.
Host-side 0xC0000142 workspace-write finding
On this Windows host, the default workspace-write pwsh sandbox cannot start pwsh: dsh-pwsh-sandbox launches it through the Windows ACL restricted-token runner, and the child dies at process start with exit code 3221225794 (0xC0000142, STATUS_DLL_INIT_FAILED). It reproduces in a headless profile with no hashline plugin installed, so the failure belongs to dsh-tool-pwsh + dsh-sandbox-windows-acl, not to this plugin.
The M3/M4 smoke runs therefore used DSH_PERMISSION_MODE=danger-full-access; this is an environment setup requirement, not a plugin behavior. Evidence: dsh/baseline/m4-behaviour.json (sandboxFinding) and dsh/baseline/m3.json.
Build and verify
| Command | What it does |
|---|---|
pnpm install |
install dependencies |
pnpm run build |
node scripts/build-dsh.mjs: bundle lib/index.js and emit lib/types/** from tsconfig.dsh.json |
pnpm run typecheck |
tsc --noEmit (full upstream program) and tsc --noEmit -p tsconfig.dsh.json (dsh build program) |
pnpm run test:win |
the Windows test suite (vitest.config.windows.ts); the primary gate for this branch |
pnpm test |
the default vitest suite |
pnpm run format |
oxfmt --check . (use pnpm run format:fix to write) |
pnpm run lint |
oxlint . + knip --max-issues 0 |
pnpm run verify |
lint + format + typecheck + Windows coverage |
The build enforces its own packaging contract: host packages stay external, the bundle must not reference pi (there is no pi host integration), and no bare import outside the allowlist can slip in. See dsh/README.md.
Error and warning codes
Every refusal carries a bracketed code; src/domain-errors.ts is the source of truth. E_* are refusals (nothing is written), W_* are warnings carried beside an accepted result.
| Code | Meaning |
|---|---|
[E_ACCESS] |
The filesystem denied access to the target path. |
[E_BAD_PAYLOAD] |
Malformed or unknown tool payload; nothing is written. |
[E_BATCH_ABORT] |
A batch item failed; the whole batch was not applied. |
[E_EMPTY_RANGE] |
The patch would empty a non-empty file; use write. |
[E_FOREIGN_ANCHOR] |
The anchor belongs to a different file. |
[E_INTERNAL_INVARIANT] |
An internal invariant was violated. |
[E_LARGE_FILE] |
The file exceeds the served line or byte budget. |
[E_LOSSY_TEXT] |
The file's bytes do not round-trip through UTF-8; editing would corrupt it. |
[E_MALFORMED_ANCHOR] |
The anchor token cannot be parsed. |
[E_NOOP_LOOP] |
Repeated identical no-op edits; refused with the current range served. |
[E_NOT_FOUND] |
The target file does not exist or is unreachable. |
[E_PATCH_SYNTAX] |
The apply_patch text is not valid syntax; nothing is written. |
[E_STALE_ANCHOR] |
A boundary anchor no longer resolves against the file. |
[E_STALE_RANGE] |
The served range changed between serve and patch. |
[E_SUSPICIOUS_TEXT] |
The replacement reproduces served anchor text (a copied HASH│ echo). |
[E_TARGET_LOST] |
The target line identity can no longer be resolved. |
[E_UNDO_REVERT_FAILED] |
A correlated revert failed mid-way; a repair run finishes it. |
[E_UNDO_STALE] |
The undo record is stale relative to the file. |
[E_UNDO_UNAVAILABLE] |
There is no undo history for the path. |
[E_UNIQUE_MATCH] |
A fragment hunk matched zero or multiple places; candidates are served back. |
[E_UNKNOWN] |
An unclassified failure; the message carries the cause. |
[E_UNKNOWN_ANCHOR] |
The anchor was never served in this session. |
[E_UNSUPPORTED_FILE] |
Binary, image or directory targets are not editable text; a non-UTF-8 file is refused with its path and an instruction to ask the user how to handle it. |
[E_UNVERIFIED_RANGE] |
The range interior cannot be verified (never served). |
[W_LITERAL_BYPASS] |
Literal HASH│ bytes were written through apply_patch and accepted with a warning. |
[W_NEVER_SERVED_SHAPE] |
A never-served hint was attached to an accepted patch. |
[W_NOOP] |
The patch produced no content change and was accepted as a no-op. |
[W_NOOP_INSERT] |
An insert-shaped hunk produced no change. |
[W_REVERSED_ANCHORS] |
Boundaries were reversed and healed. |
[W_SERVED_PREFIX_MISMATCH] |
A served prefix does not match; fresh rows were served. |
[W_UNICODE_LITERAL] |
A Unicode literal in the payload looks like a copied anchor. |
Range-family rejections render their current-row evidence exactly once: the headline plus one Current range (fresh read): block. A single-line anchor pair (anchor_from equals anchor_to) is listed once, and the distinct-anchor lists de-duplicate. [E_UNKNOWN_ANCHOR] and [E_FOREIGN_ANCHOR] also name each distinct anchor once.
Current limitations
- Mutation stays on the local
node:fsseam. The read path consumes aCoreReadIoport (local or mountedctx.fs), butwriteAtomic, the shared mutation engine and undo records remain local-only.apply_patchandeditfail closed withE_NOT_FOUNDwhen the target is reachable only throughctx.fs. A full mutation bridge needs target-keyed store state: the host'sctx.fsalready exposes versioned writes in0.2.2-alpha.3, but the snapshot/lease store still keys on absolute paths and local stat identity (M6, seedsh/README.md). - UTF-8 only. Non-UTF-8 files are refused on read and must be converted with an external tool; the plugin does not decode legacy code pages, does not re-encode on save, and keeps no encoding state.
- Windows-only. The branch targets Windows; POSIX-only suites are excluded in
vitest.config.windows.ts, and that exclusion list must shrink, never grow (seedsh/UPSTREAM.md).
Repository layout
| Path | Role |
|---|---|
src/ |
hashline engine core derived from pi-better-edit (semantic source; upstream fixes are picked selectively, see dsh/UPSTREAM.md) |
dsh/ |
DeepSeek Harness host layer — the only code that differs from upstream; map in dsh/README.md |
dsh/UPSTREAM.md |
upstream sync cursor, policy and Windows adaptation patches |
dsh/baseline/ |
milestone measurement baselines (M0–M5) |
scripts/build-dsh.mjs |
dsh bundle builder and packaging guards |
tsconfig.dsh.json |
dsh build typecheck/declaration program |
Upstream attribution
The hashline engine is pi-better-edit by Rianico, used under the MIT license and synced at upstream 673964c (v2.16.0; see dsh/UPSTREAM.md). This repository is a self-maintained fork: upstream is the semantic source of the hashline core and a place to pick bug-fix commits from, recorded in dsh/UPSTREAM.md; there is no commit-for-commit sync promise. The dsh/ adapter is ours, is never merged upstream, and contains only host wiring.