open-hashline 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artur
+
+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

@@ -0,0 +1,186 @@
+# open-hashline
+
+**Stop reproducing code to edit it.** An [OpenCode](https://github.com/anomalyco/opencode) plugin that tags every line with a content hash, so the model references lines by hash instead of copying exact text.
+
+Based on the [Harness Problem](https://blog.can.ac/2026/02/12/the-harness-problem/) — most LLM edit failures are mechanical, not intellectual. Models know *what* to change but fail at *locating* it because they must reproduce exact content (including whitespace) to specify edit locations.
+
+---
+
+## The Problem
+
+When an LLM edits a file, it needs to specify *which lines* to change. The standard approach requires the model to reproduce the exact content of those lines as `oldString` — including every space, tab, and quote. This is fragile:
+
+- Whitespace mismatches cause silent failures
+- Long lines get truncated or hallucinated
+- Repeated content creates ambiguity
+- The model wastes tokens reproducing code it already read
+
+## The Solution
+
+Hashline tags every line the model reads with a short content hash:
+
+```
+ 42:a3f| function hello() {
+ 43:f1b|   return "world";
+ 44:0e9| }
+```
+
+To edit, the model just references the hash — no content reproduction needed:
+
+```json
+{ "startHash": "42:a3f", "endHash": "44:0e9", "content": "function hello() {\n  return \"universe\";\n}" }
+```
+
+The plugin resolves hashes back to actual content before the built-in edit tool runs. The TUI diff display works exactly as before.
+
+---
+
+## How It Works
+
+1. **Read** — The `tool.execute.after` hook transforms read output, tagging each line as `<line>:<hash>| <content>` and storing a per-file hash map in memory.
+
+2. **Edit schema** — The `tool.definition` hook replaces the edit tool's parameters with `startHash`, `endHash`, `afterHash`, and `content` (instead of `oldString`/`newString`).
+
+3. **Edit resolve** — The `tool.execute.before` hook intercepts hash-based edits, resolves references back to `oldString`/`newString`, and passes them to the built-in edit tool.
+
+4. **System prompt** — The `experimental.chat.system.transform` hook injects instructions so the model knows to use hashline references.
+
+No modifications are made to any built-in tools. Everything works through hooks.
+
+---
+
+## Three Edit Operations
+
+### 1. Replace a single line
+
+```json
+{ "startHash": "3:cc7", "content": "  \"version\": \"2.0.0\"," }
+```
+
+### 2. Replace a range of lines
+
+```json
+{ "startHash": "10:a1b", "endHash": "15:f3d", "content": "// new implementation\nfunction updated() {\n  return true;\n}" }
+```
+
+### 3. Insert after a line
+
+```json
+{ "afterHash": "7:e2c", "content": "  \"newField\": \"value\"," }
+```
+
+---
+
+## Installation
+
+### Prerequisites
+
+- [OpenCode](https://github.com/anomalyco/opencode) with the `tool.definition` hook (PR [#4956](https://github.com/anomalyco/opencode/pull/4956))
+- [Bun](https://bun.sh) runtime
+
+### Option 1: Install from npm
+
+```bash
+npm install open-hashline
+```
+
+or with Bun:
+
+```bash
+bun add open-hashline
+```
+
+Then add to your OpenCode config (`~/.config/opencode/config.json` or `.opencode/config.json` in your project):
+
+```json
+{
+  "plugins": {
+    "hashline": {
+      "module": "open-hashline"
+    }
+  }
+}
+```
+
+### Option 2: Install from source
+
+```bash
+git clone https://github.com/ASidorenkoCode/openhashline.git
+cd openhashline
+bun install
+```
+
+Then add to your OpenCode config using a file path:
+
+```json
+{
+  "plugins": {
+    "hashline": {
+      "module": "file:///path/to/openhashline/src/index.ts"
+    }
+  }
+}
+```
+
+### Start OpenCode
+
+```bash
+opencode
+```
+
+That's it. Read any file and you'll see hash markers on every line. Edits will automatically use hash references.
+
+---
+
+## Hash Algorithm
+
+Each line is hashed using djb2, truncated to 3 hex characters (4096 possible values):
+
+```typescript
+function hashLine(content: string): string {
+  const trimmed = content.trimEnd()
+  let h = 5381
+  for (let i = 0; i < trimmed.length; i++) {
+    h = ((h << 5) + h + trimmed.charCodeAt(i)) | 0
+  }
+  return (h >>> 0).toString(16).slice(-3).padStart(3, "0")
+}
+```
+
+Collisions are rare and disambiguated by line number — the full reference is `<lineNumber>:<hash>` (e.g. `42:a3f`).
+
+---
+
+## Edge Cases
+
+| Scenario | Behavior |
+|---|---|
+| **Stale hashes** | File changed since last read — edit rejected, model told to re-read |
+| **File not previously read** | Falls through to normal `oldString`/`newString` edit |
+| **Hash collision** | Line number provides disambiguation |
+| **Partial/offset reads** | Hashes merge with existing stored hashes for the file |
+| **Edit invalidation** | Stored hashes cleared after any edit to prevent stale references |
+
+---
+
+## Project Structure
+
+```
+open-hashline/
+├── src/
+│   └── index.ts       # Plugin implementation (single file)
+├── package.json
+├── tsconfig.json
+├── LICENSE
+└── README.md
+```
+
+---
+
+## Contributing
+
+Contributions are welcome. Please open an issue or submit a pull request.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "open-hashline",
+  "version": "0.2.0",
+  "description": "OpenCode plugin that tags lines with content hashes for reliable LLM edits",
+  "type": "module",
+  "license": "MIT",
+  "author": "ASidorenkoCode",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ASidorenkoCode/openhashline.git"
+  },
+  "homepage": "https://github.com/ASidorenkoCode/openhashline",
+  "bugs": {
+    "url": "https://github.com/ASidorenkoCode/openhashline/issues"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "hashline",
+    "llm",
+    "code-editing",
+    "ai"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "latest"
+  }
+}

package/src/index.ts

@@ -0,0 +1,303 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { tool } from "@opencode-ai/plugin"
+import * as fs from "fs"
+import * as path from "path"
+
+const z = tool.schema
+
+/**
+ * djb2 hash of trimmed line content, truncated to 3 hex chars.
+ * 3 hex chars = 4096 values. Collisions are rare and disambiguated by line number.
+ */
+function hashLine(content: string): string {
+  const trimmed = content.trimEnd()
+  let h = 5381
+  for (let i = 0; i < trimmed.length; i++) {
+    h = ((h << 5) + h + trimmed.charCodeAt(i)) | 0
+  }
+  return (h >>> 0).toString(16).slice(-3).padStart(3, "0")
+}
+
+/** Per-file mapping: hash ref (e.g. "42:a3f") → line content */
+const fileHashes = new Map<string, Map<string, string>>()
+
+export const HashlinePlugin: Plugin = async ({ directory }) => {
+  function resolvePath(filePath: string): string {
+    if (path.isAbsolute(filePath)) return path.normalize(filePath)
+    return path.resolve(directory, filePath)
+  }
+
+  /** Read file from disk and compute fresh hashes */
+  function computeFileHashes(filePath: string): Map<string, string> {
+    const content = fs.readFileSync(filePath, "utf-8")
+    const lines = content.split("\n")
+    const hashes = new Map<string, string>()
+    for (let i = 0; i < lines.length; i++) {
+      const hash = hashLine(lines[i])
+      hashes.set(`${i + 1}:${hash}`, lines[i])
+    }
+    fileHashes.set(filePath, hashes)
+    return hashes
+  }
+
+  return {
+    // ── Read: tag each line with its content hash ──────────────────────
+    "tool.execute.after": async (input, output) => {
+      if (input.tool === "edit") {
+        // Invalidate stored hashes after any edit
+        const filePath = resolvePath(input.args.filePath)
+        fileHashes.delete(filePath)
+        return
+      }
+
+      if (input.tool !== "read") return
+
+      // Skip directory reads
+      if (output.output.includes("<type>directory</type>")) return
+
+      // Extract absolute file path from output and normalize it
+      const pathMatch = output.output.match(/<path>(.+?)<\/path>/)
+      if (!pathMatch) return
+      const filePath = path.normalize(pathMatch[1])
+
+      // Transform content lines: "N: content" → "N:hash| content"
+      // The first line is concatenated with <content> (no newline), so we
+      // match an optional <content> prefix and preserve it in the output.
+      const hashes = new Map<string, string>()
+      output.output = output.output.replace(
+        /^(<content>)?(\d+): (.*)$/gm,
+        (
+          _match,
+          prefix: string | undefined,
+          lineNum: string,
+          content: string,
+        ) => {
+          const hash = hashLine(content)
+          const ref = `${lineNum}:${hash}`
+          hashes.set(ref, content)
+          return `${prefix ?? ""}${lineNum}:${hash}| ${content}`
+        },
+      )
+
+      if (hashes.size > 0) {
+        // Merge with existing hashes (supports partial reads / offset reads)
+        const existing = fileHashes.get(filePath)
+        if (existing) {
+          for (const [ref, content] of hashes) {
+            existing.set(ref, content)
+          }
+        } else {
+          fileHashes.set(filePath, hashes)
+        }
+      }
+    },
+
+    // ── Edit schema: replace oldString/newString with hash references ──
+    // Requires PR #4956 (tool.definition hook) to take effect.
+    "tool.definition": async (input: any, output: any) => {
+      if (input.toolID !== "edit") return
+      output.description = [
+        "Edit a file using hashline references from the most recent read output.",
+        "Each line is tagged as `<line>:<hash>| <content>`.",
+        "",
+        "Three operations:",
+        "1. Replace line:  startHash only → replaces that single line",
+        "2. Replace range: startHash + endHash → replaces all lines in range",
+        "3. Insert after:  afterHash → inserts content after that line (no replacement)",
+      ].join("\n")
+      output.parameters = z.object({
+        filePath: z.string().describe("The absolute path to the file to modify"),
+        startHash: z
+          .string()
+          .optional()
+          .describe(
+            'Hash reference for the start line to replace (e.g. "42:a3f")',
+          ),
+        endHash: z
+          .string()
+          .optional()
+          .describe(
+            "Hash reference for the end line (for multi-line range replacement)",
+          ),
+        afterHash: z
+          .string()
+          .optional()
+          .describe(
+            "Hash reference for the line to insert after (no replacement)",
+          ),
+        content: z
+          .string()
+          .describe("The new content to insert or replace with"),
+      })
+    },
+
+    // ── System prompt: instruct the model to use hashline edits ────────
+    "experimental.chat.system.transform": async (_input: any, output: any) => {
+      output.system.push(
+        [
+          "## Hashline Edit Mode (MANDATORY)",
+          "",
+          "When you read a file, each line is tagged with a hash: `<lineNumber>:<hash>| <content>`.",
+          "You MUST use these hash references when editing files. Do NOT use oldString/newString.",
+          "",
+          "Three operations:",
+          "",
+          "1. **Replace line** — replace a single line:",
+          '   `startHash: "3:cc7", content: "  \\"version\\": \\"1.0.0\\","` ',
+          "",
+          "2. **Replace range** — replace lines startHash through endHash:",
+          '   `startHash: "3:cc7", endHash: "5:e60", content: "line3\\nline4\\nline5"`',
+          "",
+          "3. **Insert after** — insert new content after a line (without replacing it):",
+          '   `afterHash: "3:cc7", content: "  \\"newKey\\": \\"newValue\\","` ',
+          "",
+          "NEVER pass oldString or newString. ALWAYS use startHash/afterHash + content.",
+        ].join("\n"),
+      )
+    },
+
+    // ── Edit: resolve hash references before the built-in edit runs ────
+    "tool.execute.before": async (input, output) => {
+      if (input.tool !== "edit") return
+
+      const args = output.args
+
+      // Reject oldString edits for files we have hashes for — force hashline usage
+      if (args.oldString && !args.startHash) {
+        const filePath = resolvePath(args.filePath)
+        if (fileHashes.has(filePath)) {
+          throw new Error(
+            [
+              "You must use hashline references to edit this file.",
+              "Use startHash (e.g. \"3:cc7\") instead of oldString.",
+              "Refer to the hash markers from the read output.",
+            ].join(" "),
+          )
+        }
+        // No hashes for this file — allow normal edit
+        return
+      }
+
+      // Only intercept hashline edits; fall through for normal edits
+      if (!args.startHash && !args.afterHash) return
+
+      // ── Insert after: append content after the referenced line ──
+      if (args.afterHash) {
+        const filePath = resolvePath(args.filePath)
+        let hashes = fileHashes.get(filePath)
+        if (!hashes) {
+          try {
+            hashes = computeFileHashes(filePath)
+          } catch {
+            return
+          }
+        }
+        if (!hashes.has(args.afterHash)) {
+          try {
+            hashes = computeFileHashes(filePath)
+          } catch {
+            throw new Error(
+              `Cannot read file "${args.filePath}" to verify hash references.`,
+            )
+          }
+          if (!hashes.has(args.afterHash)) {
+            fileHashes.delete(filePath)
+            throw new Error(
+              `Hash reference "${args.afterHash}" not found. The file may have changed since last read. Please re-read the file.`,
+            )
+          }
+        }
+
+        const anchorContent = hashes.get(args.afterHash)!
+        // oldString = anchor line, newString = anchor line + new content
+        args.oldString = anchorContent
+        args.newString = anchorContent + "\n" + args.content
+
+        delete args.afterHash
+        delete args.content
+        return
+      }
+
+      const filePath = resolvePath(args.filePath)
+      let hashes = fileHashes.get(filePath)
+
+      // No stored hashes → try reading the file fresh
+      if (!hashes) {
+        try {
+          hashes = computeFileHashes(filePath)
+        } catch {
+          // Can't read file — fall through to normal edit behavior
+          return
+        }
+      }
+
+      // Validate startHash; if stale, re-read and retry once
+      if (!hashes.has(args.startHash)) {
+        try {
+          hashes = computeFileHashes(filePath)
+        } catch {
+          throw new Error(
+            `Cannot read file "${args.filePath}" to verify hash references.`,
+          )
+        }
+        if (!hashes.has(args.startHash)) {
+          fileHashes.delete(filePath)
+          throw new Error(
+            `Hash reference "${args.startHash}" not found. The file may have changed since last read. Please re-read the file.`,
+          )
+        }
+      }
+
+      const startLine = parseInt(args.startHash.split(":")[0], 10)
+      const endLine = args.endHash
+        ? parseInt(args.endHash.split(":")[0], 10)
+        : startLine
+
+      // Validate endHash
+      if (args.endHash && !hashes.has(args.endHash)) {
+        fileHashes.delete(filePath)
+        throw new Error(
+          `Hash reference "${args.endHash}" not found. The file may have changed since last read. Please re-read the file.`,
+        )
+      }
+
+      if (endLine < startLine) {
+        throw new Error(
+          `endHash line (${endLine}) must be >= startHash line (${startLine})`,
+        )
+      }
+
+      // Build oldString from the line range
+      const rangeLines: string[] = []
+      for (let lineNum = startLine; lineNum <= endLine; lineNum++) {
+        let found = false
+        for (const [ref, content] of hashes) {
+          if (ref.startsWith(`${lineNum}:`)) {
+            rangeLines.push(content)
+            found = true
+            break
+          }
+        }
+        if (!found) {
+          fileHashes.delete(filePath)
+          throw new Error(
+            `No hash found for line ${lineNum} in range ${startLine}-${endLine}. The file may have changed. Please re-read the file.`,
+          )
+        }
+      }
+
+      const oldString = rangeLines.join("\n")
+
+      // Set resolved args for the built-in edit tool
+      args.oldString = oldString
+      args.newString = args.content
+
+      // Remove hashline-specific fields so the built-in edit doesn't choke
+      delete args.startHash
+      delete args.endHash
+      delete args.content
+    },
+  } as any
+}
+
+export default HashlinePlugin