Skip to content

dsh-hashline-edit

Verified

dsh-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 (and pnpm 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│content row 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 subsequent apply_patch or edit, even when the windows are far apart.
  • Verbatim mode returns the same page as plain text with no anchors and serves nothing; an apply_patch identity hunk or an edit item 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 existing unbash parser (no wasm). Vue widens a top-level template/script/style block without parsing embedded JS/TS. SQL is not supported: real migrations largely fail to parse and .tql is a Java template, not SQL (see docs/spec/sql-vue-feasibility-gate.md).
  • offset/limit and windows are page requests, not anchors: only served output 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 File pins 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:

  1. a leading UTF-8 BOM (EF BB BF) is stripped, so it never reaches an anchor;
  2. 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:fs seam. The read path consumes a CoreReadIo port (local or mounted ctx.fs), but writeAtomic, the shared mutation engine and undo records remain local-only. apply_patch and edit fail closed with E_NOT_FOUND when the target is reachable only through ctx.fs. A full mutation bridge needs target-keyed store state: the host's ctx.fs already exposes versioned writes in 0.2.2-alpha.3, but the snapshot/lease store still keys on absolute paths and local stat identity (M6, see dsh/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 (see dsh/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.

License

MIT