dsh-line-patch 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kingofpowers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# dsh-line-patch
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+按「行号 + 行哈希 + 整文件哈希」三重锚定修改文件的 DSH 插件。给两个模型可见工具：`read_hash` 与 `patch_hash`。
+
+## 为什么需要它
+
+内置 `edit` 用字面量 `old_string` 定位，**定位费按输出 token 计价**。本机 308 个会话、891 次 `edit` 的实测数据：
+
+| 指标 | 数值 |
+|---|---|
+| `old_string` 累计 | 285,035 字符 ≈ **81,439 输出 token** |
+| 占 `new_string` 的比例 | **36%** |
+| 引文 >30 行的调用 | 4.6% |
+| `edit` 失败构成 | 未先读 2.9% / 文件已变 2.8% / **原文找不到仅 0.7%** |
+
+也就是说：抄原文这件事本身就吃掉了三成输出，而它换来的定位可靠性只解决 0.7% 的失败。`patch_hash` 把这部分换成「行号 + 两个 4 字符 hash」，定位费降到个位数 token。
+
+同时它和 DSH 内置的版本守卫**互补而非重复**：
+
+| 场景 | 内置 stat 版本 | 本插件 sha256 |
+|---|---|---|
+| 内容改了且 mtime 变了 | 拒绝 ✅ | 拒绝 ✅ |
+| 内容改了但 mtime/size 没变（`cp -p`、备份还原） | **漏判 ❌** | 拒绝 ✅ |
+| 内容没变只是被 touch / 重新构建 | **误伤 ❌** | 放行 ✅ |
+
+## 安装
+
+```bash
+dsh plugin --profile desktop add /path/to/dsh-line-patch
+```
+
+改完 `lib/` 后需要重新加载：touch 一下 `~/.dsh/profiles/desktop/cordis.patch.yml` 触发 HMR，或重启宿主。
+
+## 用法
+
+```text
+read_hash { file_path: "app.py" }
+→ file_hash: 7bb7a279c235cef2
+  1/f3c2: import os
+  2/7182: def main():
+  ...
+
+patch_hash {
+  file_path: "app.py",
+  file_hash: "7bb7a279c235cef2",
+  line_start: 2, hash_start: "7182",
+  line_end: 3,  hash_end: "251e",
+  replace: "def run():"
+}
+→ patched app.py: lines 2-3 replaced (line shift -1). new file_hash: d119fac30942d216
+```
+
+- `file_hash`、`hash_start`、`hash_end` **三项必填**，缺一项 schema 层就拒绝。
+- `replace: ""` 表示删除该行区间。
+- 替换后返回 `new_file_hash` 与 `line_shift`，连续修改时不必整段重读。
+- CRLF 文件按原风格写回；末行无换行符的状态保持。
+
+## 锚点核实（每轮自动）
+
+`read_hash` 发出的每个锚点会登记下来，之后每次模型请求前（`agent/request`）复核一次，只覆盖**最近 3 个用户回合**内的文件：
+
+```
+stat 预筛（微秒级，不读文件）
+├─ 版本没变            → 什么都不做
+└─ 版本变了 → 算 sha256
+   ├─ 内容相同（touch / 重新构建） → 只补发 fs/observed 刷新策略底账，上下文零改动
+   └─ 内容真变了                    → 把当初那条 read 结果原地替换成「已失效 + 新旧 hash + 请重读」
+```
+
+第二行是关键：内置的 stat 版本守卫会把「内容没变但 mtime 变了」误判为外部修改，这里用内容哈希纠正它，模型不必因为一次 rebuild 就重读整个文件。
+
+工具自己改过的文件（`patch_hash`、内置 `write`/`edit`）会先通过 `fs/observed` 把对应锚点作废，**不会被当成外部变更回报给模型**。
+
+## 实现要点
+
+- 所有读写走 `ctx.fs`，不直接碰 `node:fs`，沙箱与远端后端仍然有效。
+- 写入复刻内置 `write` 的 intent 舞蹈：`fs/write-intent` waterfall 取意图 → `writeText(intent)` → `emit('fs/observed')`。**裸调 `writeText` 会静默绕过读后写门禁与版本 CAS**。
+- 读取时同样 `emit('fs/observed')`，否则策略门禁会把目标当作「没读过」。
+
+## 已验证
+
+在真实宿主（desktop profile）上跑通：
+
+- `read_hash` 返回逐行 `行号/hash` 与 `file_hash`
+- `patch_hash` 正常替换、行数位移计算正确
+- 过期 `file_hash` → `file_hash mismatch ... read it again`
+- 错误行 hash → `line N hash mismatch ... the line numbers shifted`
+- `replace: ""` 删除区间，文件内容与行位移正确
+- 写入确实经过 `replaceIfVersion` intent（stub 测试断言）
+
+锚点核实也做了真机验证：读文件 → 用 bash 在 `ctx.fs` 之外改写内容 → 下一次模型请求前，会话日志里出现
+
+```
+tool/result seq=1055  surfaceOp={"op":"replace","startSeq":1046,"endSeq":1046}  sources=[1046]
+→ "[line-patch] …/line-patch-reval.txt was modified after it was read
+   (file_hash 4cdfa7d498707b8f -> 417e4745306cbe22). … call read_hash again before patching."
+```
+
+即原来的 read 结果（seq 1046）被准确替换。
+
+离线测试：`npm test` — 32 个用例（核心逻辑 17 + 工具胶水 10 + 锚点核实 5），全部通过。
+
+## 尚未实现
+
+- `presentCall` / `presentResult` 的 diff 卡片（目前是纯文本渲染）。
+- 只核对「本会话登记过的、3 个用户回合内」的文件；更早的锚点按设计丢弃，不做长期追踪。
+
+## 已知限制
+
+- 单文件 5 MB 上限。
+- `read_hash` 单次最多 2000 行。
+- `fs/write-intent` 不可用时退化为自行构造的 `replaceIfVersion`；再不可用则退化为无条件写（此时只剩 sha256 与行 hash 保护）。
+- 若 `@deepseek-ai/dsh-tools` 无法解析，`defineTool` 退化为恒等函数：工具仍可用，但参数校验交给插件自己。
+
+## 许可
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# Anchored line-range editing: read_hash / patch_hash.
+- insert:
+    - id: line-patch
+      name: dsh-line-patch

package/lib/core.js

@@ -0,0 +1,191 @@
+/**
+ * dsh-line-patch — pure anchoring logic.
+ *
+ * No I/O and no host API lives here: every function takes text in and returns
+ * text out, so the whole editing contract is unit-testable without a Harness.
+ */
+import { createHash } from 'node:crypto'
+
+/** Characters kept from a line's md5 — enough to spot a changed boundary line. */
+export const LINE_HASH_CHARS = 4
+
+/** Characters kept from the whole-file sha256 — enough to spot a changed file. */
+export const FILE_HASH_CHARS = 16
+
+/** Fixed hash a blank line carries, so every line has an anchor. */
+export const EMPTY_LINE_HASH = lineHashOf('')
+
+function lineHashOf(text) {
+  return createHash('md5').update(text, 'utf8').digest('hex').slice(0, LINE_HASH_CHARS)
+}
+
+/**
+ * The anchor shown next to one line.
+ * @param {string} text - the line with its line ending already stripped.
+ * @returns {string} a stable 4-character hash.
+ */
+export function lineHash(text) {
+  return lineHashOf(text)
+}
+
+/**
+ * The anchor shown for a whole file.
+ * @param {string|Buffer} content - raw file content.
+ * @returns {string} a 16-character sha256 prefix.
+ */
+export function fileHash(content) {
+  return createHash('sha256').update(content).digest('hex').slice(0, FILE_HASH_CHARS)
+}
+
+/**
+ * Detect the line ending a file is written in so replacements keep it.
+ * @param {string} content - the file text.
+ * @returns {string} '\r\n' or '\n'.
+ */
+export function detectEol(content) {
+  return content.includes('\r\n') ? '\r\n' : '\n'
+}
+
+/**
+ * Split text into lines while keeping each line's own ending.
+ *
+ * Rejoining the result must reproduce the input byte for byte; a final line
+ * without a newline therefore stays without one.
+ * @param {string} content - the file text.
+ * @returns {string[]} lines, each ending in '\n' except possibly the last.
+ */
+export function splitKeepEnds(content) {
+  const out = []
+  let start = 0
+  while (start < content.length) {
+    const nl = content.indexOf('\n', start)
+    if (nl < 0) {
+      out.push(content.slice(start))
+      break
+    }
+    out.push(content.slice(start, nl + 1))
+    start = nl + 1
+  }
+  return out
+}
+
+/** Strip a line's ending terms before hashing it. */
+function bareLine(line) {
+  return line.replace(/[\r\n]+$/, '')
+}
+
+/**
+ * Render the model-facing view of a line range.
+ *
+ * Each line is prefixed with `<number>/<hash>: ` so the model never counts
+ * lines itself and can copy the hash straight into `patch_hash`.
+ * @param {string} content - the text to annotate.
+ * @param {number} [startLine] - absolute number for the first line.
+ * @returns {string} annotated text.
+ */
+export function annotateLines(content, startLine = 1) {
+  const lines = splitKeepEnds(content)
+  return lines
+    .map((line, index) => {
+      const text = bareLine(line)
+      const hash = text.length === 0 ? EMPTY_LINE_HASH : lineHash(text)
+      return `${startLine + index}/${hash}: ${text}\n`
+    })
+    .join('')
+}
+
+/** Normalise every line ending in a replacement to the file's own style. */
+function normalizeEol(text, eol) {
+  const unified = text.replace(/\r\n|[\r\n]/g, '\n')
+  return eol === '\n' ? unified : unified.replace(/\n/g, eol)
+}
+
+/** Count the lines a replacement text occupies. */
+function countLines(text) {
+  if (text.length === 0) return 0
+  const parts = text.split('\n')
+  if (parts.length > 0 && parts[parts.length - 1] === '') parts.pop()
+  return parts.length
+}
+
+/**
+ * Apply an anchored line-range replacement.
+ *
+ * All three anchors are checked before anything is written, and the returned
+ * text is the complete new file: callers never splice in place themselves.
+ * @param {object} input - the guarded edit request.
+ * @param {string} input.content - current file text.
+ * @param {string} input.expectedFileHash - `file_hash` the model was shown.
+ * @param {number} input.lineStart - 1-based first line to replace.
+ * @param {string} input.hashStart - hash of that line.
+ * @param {number} input.lineEnd - 1-based last line to replace (inclusive).
+ * @param {string} input.hashEnd - hash of that line.
+ * @param {string} input.replace - replacement text; '' deletes the range.
+ * @returns {{ok: true, content: string, fileHash: string, lineShift: number, removedLines: number}
+ *   | {ok: false, code: string, message: string}}
+ */
+export function applyPatch(input) {
+  const { content, expectedFileHash, lineStart, hashStart, lineEnd, hashEnd, replace } = input
+
+  const actualFileHash = fileHash(content)
+  if (expectedFileHash !== actualFileHash) {
+    return {
+      ok: false,
+      code: 'FILE_HASH_MISMATCH',
+      message: `file_hash mismatch: expected ${expectedFileHash}, actual ${actualFileHash} — the file changed since read_hash; read it again.`,
+    }
+  }
+
+  const lines = splitKeepEnds(content)
+  const total = lines.length
+  if (lineStart < 1 || lineStart > total) {
+    return {
+      ok: false,
+      code: 'RANGE_INVALID',
+      message: `line_start ${lineStart} is out of range (file has ${total} lines).`,
+    }
+  }
+  if (lineEnd < lineStart || lineEnd > total) {
+    return {
+      ok: false,
+      code: 'RANGE_INVALID',
+      message: `line_end ${lineEnd} is out of range (line_start ${lineStart}, file has ${total} lines).`,
+    }
+  }
+
+  const startActual = lineHash(bareLine(lines[lineStart - 1]))
+  if (startActual !== hashStart) {
+    return {
+      ok: false,
+      code: 'LINE_HASH_MISMATCH',
+      message: `line ${lineStart} hash mismatch: expected ${hashStart}, actual ${startActual} — the line numbers shifted; read the file again.`,
+    }
+  }
+  const endActual = lineHash(bareLine(lines[lineEnd - 1]))
+  if (endActual !== hashEnd) {
+    return {
+      ok: false,
+      code: 'LINE_HASH_MISMATCH',
+      message: `line ${lineEnd} hash mismatch: expected ${hashEnd}, actual ${endActual} — the line numbers shifted; read the file again.`,
+    }
+  }
+
+  const eol = detectEol(content)
+  const hadTrailingNewline = content.endsWith('\n')
+  let body = normalizeEol(replace, eol)
+  if (body.length > 0 && !body.endsWith('\n')) body += eol
+
+  const before = lines.slice(0, lineStart - 1)
+  const after = lines.slice(lineEnd)
+  if (after.length === 0 && !hadTrailingNewline) body = body.replace(/\r?\n$/, '')
+
+  const next = before.join('') + body + after.join('')
+  const removedLines = lineEnd - lineStart + 1
+  return {
+    ok: true,
+    content: next,
+    fileHash: fileHash(next),
+    lineShift: countLines(body) - removedLines,
+    removedLines,
+  }
+}

package/lib/index.js

@@ -0,0 +1,411 @@
+/**
+ * dsh-line-patch — anchored file editing for DeepSeek Harness.
+ *
+ * `read_hash` shows every line as `<number>/<hash>: <text>` plus a whole-file
+ * hash. `patch_hash` replaces a line range only when the file hash and both
+ * boundary-line hashes still match, so a stale read can never silently
+ * overwrite newer content.
+ *
+ * The tools never touch `node:fs`: reads and writes go through `ctx.fs` so the
+ * mounted filesystem (sandbox, remote, policy gate) stays authoritative.
+ */
+import {
+  LINE_HASH_CHARS,
+  FILE_HASH_CHARS,
+  annotateLines,
+  applyPatch,
+  fileHash,
+  splitKeepEnds,
+} from './core.js'
+
+/** Plugin name used by loader diagnostics. */
+export const name = 'line-patch'
+
+/**
+ * `defineTool` types and validates arguments in the host. When the package is
+ * absent — a plain `node --test` checkout — the identity fallback keeps the
+ * module loadable so the pure logic and tool glue stay testable offline.
+ */
+const { defineTool } = await import('@deepseek-ai/dsh-tools')
+  .catch(() => {
+    console.warn('[line-patch] @deepseek-ai/dsh-tools not resolvable; running without argument validation')
+    return { defineTool: definition => definition }
+  })
+
+/** The tool registry and the filesystem service must be ready before either tool registers. */
+export const inject = ['tools', 'fs']
+
+/** Largest file this plugin will read or rewrite in one call. */
+const MAX_FILE_BYTES = 5 * 1024 * 1024
+
+/** Default and maximum lines one `read_hash` call returns. */
+const DEFAULT_READ_LIMIT = 2000
+
+/** How many user turns an anchor stays eligible for revalidation. */
+const ANCHOR_TURNS = 3
+
+/** Cap on tracked anchors so a read-heavy turn cannot grow the registry without bound. */
+const MAX_ANCHORS = 32
+
+const READ_DESCRIPTION = [
+  'Read a UTF-8 text file with per-line and whole-file hashes.',
+  'Every line comes back as `<number>/<hash>: <text>`; the result also carries `file_hash`.',
+  'Copy those values into patch_hash — they are the only anchors it accepts.',
+  'Use this instead of read when you intend to modify the file afterwards.',
+].join(' ')
+
+const PATCH_DESCRIPTION = [
+  'Replace an inclusive line range after verifying the whole file and both boundary lines.',
+  'file_hash, hash_start and hash_end are all required and must come from a read_hash result.',
+  'replace is the new text; pass an empty string to delete the range.',
+  'Cheaper than edit for large rewrites: you send line numbers instead of quoting the old text.',
+].join(' ')
+
+/**
+ * Resolve the filesystem service or explain why the tool cannot run.
+ * @param {object} ctx - the plugin context.
+ * @returns {object} the `ctx.fs` service.
+ */
+function requireFs(ctx) {
+  const fs = ctx?.fs
+  if (!fs || typeof fs.resolve !== 'function' || typeof fs.readText !== 'function') {
+    throw new Error('line-patch requires the ctx.fs service; mount @deepseek-ai/dsh-fs-local (or another provider).')
+  }
+  return fs
+}
+
+/**
+ * Read a file that fits the plugin's single-call budget.
+ * @param {object} ctx - the plugin context.
+ * @param {string} filePath - model-supplied path.
+ * @param {AbortSignal} [signal] - cancellation.
+ * @returns {Promise<{target: object, content: string, version: string, size: number}>} the read result.
+ */
+async function readWholeFile(ctx, filePath, signal) {
+  const fs = requireFs(ctx)
+  const target = await fs.resolve(filePath, { signal })
+  const info = await fs.stat(target, signal)
+  if (!info) throw new Error(`file not found: ${filePath}`)
+  if (info.type !== 'file') throw new Error(`not a regular file: ${filePath}`)
+  if (typeof info.size === 'number' && info.size > MAX_FILE_BYTES) {
+    throw new Error(`file is larger than the ${MAX_FILE_BYTES} byte limit: ${filePath}`)
+  }
+  const content = await fs.readText(target, signal)
+  return { target, content, version: info.version, size: info.size ?? content.length }
+}
+
+/** Wrap a numeric line count into the canonical `total_lines` value. */
+function totalLinesOf(content) {
+  return splitKeepEnds(content).length
+}
+
+/**
+ * Record the model-facing anchor so later turns can revalidate it.
+ * @param {object} registry - the plugin's anchor registry.
+ * @param {object} entry - anchor facts.
+ */
+function rememberAnchor(registry, entry) {
+  const key = entry.targetKey ?? entry.path
+  registry.anchors.set(key, entry)
+  registry.order.push(key)
+  while (registry.order.length > MAX_ANCHORS) {
+    const dropped = registry.order.shift()
+    if (dropped !== undefined && dropped !== key) registry.anchors.delete(dropped)
+  }
+}
+
+/**
+ * Replace the tool result that carried a now-void anchor with a notice.
+ *
+ * The surface is append-only, so "editing history" means appending a
+ * replacement event that shadows the original sequence.
+ * @param {object} registry - the plugin's anchor registry.
+ * @param {object} anchor - the anchor whose read result is stale.
+ * @param {string} freshHash - the file hash as it is now.
+ */
+function replaceStaleRead(registry, anchor, freshHash) {
+  const session = anchor.session ?? registry.session
+  if (!session || typeof session.append !== 'function' || typeof anchor.seq !== 'number') return
+  const event = session.eventAt?.(anchor.seq)
+  const data = event?.data
+  if (!data || !data.message) return
+  const text = `[line-patch] ${anchor.displayPath} was modified after it was read ` +
+    `(file_hash ${anchor.fileHash} -> ${freshHash}). The content and line numbers above are void; ` +
+    'call read_hash again before patching.'
+  try {
+    session.append(
+      'tool/result',
+      { ...data, message: { ...data.message, content: [{ type: 'text', text }] } },
+      { surfaceOp: { op: 'replace', startSeq: anchor.seq, endSeq: anchor.seq }, sourceEventSeqs: [anchor.seq] },
+    )
+  } catch {
+    // A already-shadowed or foreign sequence is not ours to rewrite; the patch-time hashes still protect.
+  }
+}
+
+/**
+ * Re-check every live anchor against the file it came from.
+ *
+ * `stat` is the cheap prefilter: an unchanged stat version means nothing moved
+ * and no read happens. A changed version then splits into the two cases that
+ * matter — same content (refresh bookkeeping, keep the model's anchors) and
+ * different content (void the old result).
+ * @param {object} ctx - the plugin context.
+ * @param {object} registry - the plugin's anchor registry.
+ * @param {object} actor - the request's step context, used as the observation owner.
+ */
+async function revalidateAnchors(ctx, registry, actor) {
+  const fs = ctx?.fs
+  if (!fs || registry.anchors.size === 0) return
+  for (const [key, anchor] of [...registry.anchors]) {
+    if (registry.turn - anchor.turn > ANCHOR_TURNS) {
+      registry.anchors.delete(key)
+      continue
+    }
+    const target = anchor.target ?? { targetKey: key, displayPath: anchor.displayPath }
+    let info
+    try {
+      info = await fs.stat(target)
+    } catch {
+      continue
+    }
+    if (!info) {
+      registry.anchors.delete(key)
+      continue
+    }
+    if (info.version === anchor.version) continue
+    let content
+    try {
+      content = await fs.readText(target)
+    } catch {
+      continue
+    }
+    const fresh = fileHash(content)
+    if (fresh === anchor.fileHash) {
+      // Byte-identical: a rebuild or a touch moved the stat, not the content.
+      anchor.version = info.version
+      try {
+        ctx.emit('fs/observed', target, { kind: 'present', version: info.version }, actor)
+      } catch {
+        // no observation gate mounted
+      }
+      continue
+    }
+    replaceStaleRead(registry, anchor, fresh)
+    registry.anchors.delete(key)
+  }
+}
+
+/**
+ * Register both tools plus the anchor bookkeeping on a plugin context.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - the plugin context.
+ */
+export function apply(ctx) {
+  const registry = { anchors: new Map(), order: [], turn: 0, session: undefined }
+
+  /** Record an observation so `fs/write-intent` sees this file as read. */
+  const observe = (target, version, actor) => {
+    try {
+      ctx.emit('fs/observed', target, { kind: 'present', version }, actor)
+    } catch {
+      // The gate is optional; a bare provider simply has no listener.
+    }
+  }
+
+  // A tool-mediated write refreshes its own observation, so the anchor it
+  // invalidates must not later read back as an "external" change.
+  try {
+    ctx.on('fs/observed', (target, observation) => {
+      if (!target || observation?.kind !== 'present') return
+      const anchor = registry.anchors.get(target.targetKey)
+      if (anchor && anchor.version !== observation.version) registry.anchors.delete(target.targetKey)
+    })
+  } catch {
+    // Hosts without the observation gate simply skip this bookkeeping.
+  }
+
+  // One session/event listener carries three facts the revalidation needs: the
+  // live session, the user-turn counter, and the sequence of our own results.
+  try {
+    ctx.on('session/event', (session, event) => {
+      if (session) registry.session = session
+      if (!event) return
+      if (event.type === 'turn/start') {
+        registry.turn += 1
+        return
+      }
+      if (event.type !== 'tool/result') return
+      const callId = event.data?.message?.toolCallId
+      if (typeof callId !== 'string') return
+      for (const anchor of registry.anchors.values()) {
+        if (anchor.callId === callId && typeof anchor.seq !== 'number') {
+          anchor.seq = event.seq
+          anchor.session = session
+        }
+      }
+    })
+  } catch {
+    // A host without session events still gets working tools; anchors just never expire by age.
+  }
+
+  // `agent/request` runs with an open step and before the model call: the one
+  // place where a surface replacement is legal and still useful.
+  try {
+    ctx.on('agent/request', (...args) => {
+      const next = typeof args.at(-1) === 'function' ? args.at(-1) : undefined
+      const stepContext = args[0]
+      const settled = revalidateAnchors(ctx, registry, stepContext).catch(() => {})
+      return next ? settled.then(() => next()) : settled
+    })
+  } catch {
+    // Without the hook, anchors are only checked at patch time.
+  }
+
+  ctx.tools.register(defineTool({
+    name: 'read_hash',
+    description: READ_DESCRIPTION,
+    parameters: {
+      file_path: { type: 'string', required: true, description: 'Path to read, resolved by the filesystem backend.' },
+      offset: { type: 'number', description: '1-based first line to show. Defaults to 1.' },
+      limit: { type: 'number', description: `Maximum lines to show. Defaults to and is capped at ${DEFAULT_READ_LIMIT}.` },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          path: { type: 'string', required: true },
+          file_hash: { type: 'string', required: true },
+          line_hash_chars: { type: 'integer', required: true },
+          offset: { type: 'integer', required: true },
+          line_count: { type: 'integer', required: true },
+          total_lines: { type: 'integer', required: true },
+          content: { type: 'string', required: true },
+          truncated: { type: 'boolean', required: true },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `file_hash: ${value.file_hash}\n` +
+          `lines ${value.offset}-${value.offset + value.line_count - 1} of ${value.total_lines}\n` +
+          `${value.content}` +
+          (value.truncated ? `\n... [showing ${value.line_count} lines; narrow the range with offset/limit]` : ''),
+      }],
+    },
+    async execute(args, exec) {
+      const fs = requireFs(ctx)
+      const offset = Math.max(1, Math.trunc(args.offset ?? 1))
+      const limit = Math.min(Math.max(1, Math.trunc(args.limit ?? DEFAULT_READ_LIMIT)), DEFAULT_READ_LIMIT)
+      const { target, content, version } = await readWholeFile(ctx, args.file_path, exec.signal)
+      const all = splitKeepEnds(content)
+      const total = all.length
+      const end = Math.min(total, offset + limit - 1)
+      const window = end >= offset ? all.slice(offset - 1, end).join('') : ''
+      observe(target, version, exec)
+      rememberAnchor(registry, {
+        path: fs.processPath ? fs.processPath(target) : String(args.file_path),
+        targetKey: target.targetKey ?? target.key ?? String(args.file_path),
+        displayPath: String(args.file_path),
+        fileHash: fileHash(content),
+        version,
+        turn: registry.turn,
+        target,
+        session: registry.session,
+        callId: exec?.callId,
+      })
+      return {
+        path: fs.processPath ? fs.processPath(target) : String(args.file_path),
+        file_hash: fileHash(content),
+        line_hash_chars: LINE_HASH_CHARS,
+        offset,
+        line_count: Math.max(0, end - offset + 1),
+        total_lines: total,
+        content: annotateLines(window, offset),
+        truncated: end < total,
+      }
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'patch_hash',
+    description: PATCH_DESCRIPTION,
+    parameters: {
+      file_path: { type: 'string', required: true, description: 'Path to edit, resolved by the filesystem backend.' },
+      file_hash: { type: 'string', required: true, description: `Whole-file hash from read_hash (${FILE_HASH_CHARS} hex chars).` },
+      line_start: { type: 'number', required: true, description: '1-based first line to replace.' },
+      hash_start: { type: 'string', required: true, description: `Hash of line_start as shown by read_hash (${LINE_HASH_CHARS} hex chars).` },
+      line_end: { type: 'number', required: true, description: '1-based last line to replace, inclusive. Equal to line_start for one line.' },
+      hash_end: { type: 'string', required: true, description: `Hash of line_end as shown by read_hash (${LINE_HASH_CHARS} hex chars).` },
+      replace: { type: 'string', required: true, description: 'Replacement text. An empty string deletes the range.' },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          path: { type: 'string', required: true },
+          replaced: { type: 'array', required: true, items: { type: 'number' } },
+          line_shift: { type: 'integer', required: true },
+          new_file_hash: { type: 'string', required: true },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: `patched ${value.path}: lines ${value.replaced[0]}-${value.replaced[1]} replaced ` +
+          `(line shift ${value.line_shift >= 0 ? '+' : ''}${value.line_shift}). ` +
+          `new file_hash: ${value.new_file_hash}`,
+      }],
+      presentationMeta: (args, value) => ({ replaced: value.replaced, path: value.path }),
+    },
+    async execute(args, exec) {
+      const fs = requireFs(ctx)
+      const { target, content, version } = await readWholeFile(ctx, args.file_path, exec.signal)
+      const result = applyPatch({
+        content,
+        expectedFileHash: args.file_hash,
+        lineStart: Math.trunc(args.line_start),
+        hashStart: args.hash_start,
+        lineEnd: Math.trunc(args.line_end),
+        hashEnd: args.hash_end,
+        replace: args.replace,
+      })
+      if (!result.ok) {
+        const error = new Error(result.message)
+        error.code = result.code
+        throw error
+      }
+
+      // Mirror the built-in write tool: ask the policy gate for the intent, then
+      // hand it to the provider so the version CAS (and read-before-write) apply.
+      const fallback = { kind: 'replaceIfVersion', version }
+      let intent = fallback
+      try {
+        const decided = await ctx.waterfall('fs/write-intent', target, exec, () => fallback)
+        if (decided) intent = decided
+      } catch {
+        intent = fallback
+      }
+
+      const outcome = await fs.writeText(target, result.content, intent, exec.signal)
+      observe(target, outcome?.version ?? version, exec)
+
+      rememberAnchor(registry, {
+        path: fs.processPath ? fs.processPath(target) : String(args.file_path),
+        targetKey: target.targetKey ?? target.key ?? String(args.file_path),
+        displayPath: String(args.file_path),
+        fileHash: result.fileHash,
+        version: outcome?.version ?? version,
+        turn: registry.turn,
+        target,
+        // No callId: a patch result is never rewritten, it is only bookkeeping.
+      })
+
+      return {
+        path: fs.processPath ? fs.processPath(target) : String(args.file_path),
+        replaced: [Math.trunc(args.line_start), Math.trunc(args.line_end)],
+        line_shift: result.lineShift,
+        new_file_hash: result.fileHash,
+      }
+    },
+  }))
+}

package/package.json

@@ -1,6 +1,58 @@
-{
-  "name": "dsh-line-patch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "dsh-line-patch",
+  "version": "0.2.0",
+  "description": "Anchored file editing for DeepSeek Harness: read_hash hands out per-line and whole-file hashes, patch_hash rewrites a line range only when the whole file and both boundary lines still match.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kingofpowers/dsh-line-patch.git"
+  },
+  "homepage": "https://github.com/kingofpowers/dsh-line-patch#readme",
+  "bugs": {
+    "url": "https://github.com/kingofpowers/dsh-line-patch/issues"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh",
+    "cordis",
+    "edit",
+    "patch",
+    "hash",
+    "anchor"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "manifestVersion": 1
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-tools": "*"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "check": "node --check lib/core.js && node --check lib/index.js"
+  },
+  "license": "MIT",
+  "author": "kingofpowers",
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  }
+}