pi-readseek 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Jarkko Sakkinen
+Copyright (c) 2026 Maxwell Newman
+
+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,41 @@
+# pi-readseek
+
+`pi-readseek` is a pi extension for readseek-backed file reading, hash-anchored
+editing, anchored grep, structural maps, symbol lookup, and structural search.
+It exists to resolve conflicts between overlapping pi file-operation tools by
+exposing one consistent readseek-centered surface.
+
+## Installation
+
+```bash
+pi install npm:pi-readseek
+```
+
+## Tools
+
+- `read` — reads text files with `LINE:HASH` anchors for later `edit` calls;
+  images are returned as attachments. Large or symbol-scoped reads can include
+  structural maps powered by `@jarkkojs/readseek`.
+- `edit` — changes existing text files using fresh anchors from `read`, `grep`,
+  `search`, or `write`. Use anchored variants such as `set_line`; `new_text`
+  must be plain replacement text and never include `LINE:HASH|` prefixes.
+  Set `new_text` to `""` to delete a line. Fuzzy replacement is literal
+  relocation, not approximate or semantic matching.
+- `grep` — searches text and returns edit-ready `LINE:HASH` anchors without a
+  follow-up `read`.
+- `search` — searches code by structural pattern and returns anchored
+  matches; use it when syntax matters more than raw text.
+- `write` — creates or overwrites whole files and returns anchors for immediate
+  follow-up edits. Create a new file with `write` when there is no existing file
+  to edit.
+- `ls` — lists one directory.
+- `find` — recursively discovers files and directories.
+
+## Licensing
+
+`pi-readseek` is licensed under `MIT`. See [LICENSE](LICENSE) for more
+information.
+
+`readseek` is originally derived from the source code of
+[`pi-hashline-readmap`](https://github.com/coctostan/pi-hashline-readmap).
+The relevant copyrights have been retained in [LICENSE](LICENSE).

package/index.ts

@@ -0,0 +1,142 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerReadTool } from "./src/read.js";
+import { registerEditTool } from "./src/edit.js";
+import { registerGrepTool } from "./src/grep.js";
+import { registerSgTool, isSgAvailable } from "./src/sg.js";
+import { registerWriteTool } from "./src/write.js";
+import { registerLsTool } from "./src/ls.js";
+import { registerFindTool } from "./src/find.js";
+import { applyContextHygieneStaleContext } from "./src/context-application.js";
+import {
+  createContextHygieneTracker,
+  normalizePathForContextHygiene,
+  type ContextHygieneEvent,
+  type ContextHygieneMetadata,
+  type ContextHygieneReport,
+  type ContextHygieneResource,
+  type ContextHygieneTracker,
+} from "./src/context-hygiene.js";
+import {
+  consumeDoomLoopWarning,
+  createDoomLoopState,
+  formatDoomLoopMessage,
+  recordToolCall,
+} from "./src/doom-loop.js";
+
+function isContextHygieneResource(value: unknown): value is ContextHygieneResource {
+  if (!value || typeof value !== "object") return false;
+  const resource = value as { kind?: unknown; key?: unknown };
+  return (resource.kind === "file" || resource.kind === "symbol") && typeof resource.key === "string";
+}
+
+function isContextHygieneMetadata(value: unknown): value is ContextHygieneMetadata {
+  if (!value || typeof value !== "object") return false;
+  const metadata = value as Partial<ContextHygieneMetadata>;
+  return (
+    metadata.schemaVersion === 1 &&
+    typeof metadata.tool === "string" &&
+    (metadata.classification === "read-context" ||
+      metadata.classification === "search-context" ||
+      metadata.classification === "mutation") &&
+    Array.isArray(metadata.resources) &&
+    metadata.resources.every(isContextHygieneResource)
+  );
+}
+
+function contextHygieneFromDetails(details: unknown): ContextHygieneMetadata | undefined {
+  if (!details || typeof details !== "object") return undefined;
+  const metadata = (details as { contextHygiene?: unknown }).contextHygiene;
+  return isContextHygieneMetadata(metadata) ? metadata : undefined;
+}
+
+function recordContextHygiene(
+  tracker: ContextHygieneTracker,
+  metadata: ContextHygieneMetadata,
+  toolCallId: unknown,
+): ContextHygieneEvent {
+  return tracker.record(metadata, {
+    resultId: typeof toolCallId === "string" ? toolCallId : undefined,
+  });
+}
+
+export default function piReadseekExtension(pi: ExtensionAPI): void {
+  const readTurns = new Map<string, number>();
+  const doomLoopState = createDoomLoopState();
+  const contextHygieneTracker = createContextHygieneTracker();
+  const readTurnKey = (absolutePath: string) => normalizePathForContextHygiene(absolutePath);
+  const noteRead = (absolutePath: string) => {
+    const report = contextHygieneTracker.generateReport();
+    const eventId = report.eventCount + 1;
+    readTurns.set(readTurnKey(absolutePath), eventId);
+  };
+  const wasReadInSession = (absolutePath: string) => readTurns.has(readTurnKey(absolutePath));
+
+  registerReadTool(pi, { onSuccessfulRead: noteRead });
+  registerEditTool(pi, { wasReadInSession });
+  const sgAvailable = isSgAvailable();
+  const searchGuideline = sgAvailable
+    ? "Use grep summary for counts; use search for structural code patterns."
+    : "Use grep summary for counts; install @jarkkojs/readseek to enable search.";
+
+  registerGrepTool(pi, { searchGuideline, onFileAnchored: noteRead });
+  registerSgTool(pi, { onFileAnchored: noteRead });
+  registerWriteTool(pi, { onFileAnchored: noteRead });
+  registerLsTool(pi);
+  registerFindTool(pi);
+
+  pi.on("tool_call", (event: any) => {
+    recordToolCall(
+      doomLoopState,
+      event.toolName,
+      event.toolCallId,
+      (event.input ?? {}) as Record<string, unknown>,
+    );
+  });
+
+  const expireStaleReadTurns = (report: ContextHygieneReport) => {
+    if (readTurns.size === 0) return;
+    for (const candidate of report.staleCandidates) {
+      if (!candidate.resourceKey.startsWith("file:")) continue;
+      const resourcePath = readTurnKey(candidate.resourceKey.slice("file:".length));
+      const recordedEventId = readTurns.get(resourcePath);
+      if (recordedEventId === undefined) continue;
+      if (recordedEventId < candidate.mutationEventId) {
+        readTurns.delete(resourcePath);
+      }
+    }
+  };
+
+  pi.on("context", (event: any): any => {
+    if (!Array.isArray(event.messages)) return undefined;
+    const report = contextHygieneTracker.generateReport();
+    const messages = applyContextHygieneStaleContext(event.messages, report);
+    expireStaleReadTurns(report);
+    return { messages };
+  });
+
+  pi.on("tool_result", (event: any) => {
+    const contextHygiene = contextHygieneFromDetails(event.details);
+    if (contextHygiene) recordContextHygiene(contextHygieneTracker, contextHygiene, event.toolCallId);
+
+    const doomLoop = consumeDoomLoopWarning(doomLoopState, event.toolCallId);
+    if (!doomLoop || !Array.isArray(event.content)) return undefined;
+
+    const content = [...event.content];
+    const prefix = `${formatDoomLoopMessage(doomLoop)}\n\n---\n`;
+    const textIndex = content.findIndex((item) => {
+      const maybeText = item as { type?: unknown; text?: unknown };
+      return maybeText.type === "text" && typeof maybeText.text === "string";
+    });
+    if (textIndex >= 0) {
+      const item = content[textIndex] as { type: "text"; text: string };
+      content[textIndex] = { ...item, text: `${prefix}${item.text}` };
+    } else {
+      content.unshift({ type: "text" as const, text: prefix });
+    }
+    return {
+      content,
+      details: event.details,
+      isError: event.isError,
+    };
+  });
+}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "pi-readseek",
+  "version": "0.1.0",
+  "description": "Pi extension for readseek-backed hash-anchored read/edit/grep, structural code maps, structural search, and file exploration",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "hashline",
+    "code-map",
+    "structural-search"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coctostan/pi-readseek.git"
+  },
+  "author": "Maxwell Newman",
+  "license": "MIT",
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "src/",
+    "prompts/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node scripts/vitest-run.mjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@jarkkojs/readseek": "0.1.5",
+    "diff": "^8.0.3",
+    "ignore": "^7.0.5",
+    "picomatch": "^4.0.4",
+    "tree-sitter-wasms": "0.1.13",
+    "web-tree-sitter": "0.25.10",
+    "xxhash-wasm": "^1.1.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.78.0",
+    "@earendil-works/pi-coding-agent": "^0.78.0",
+    "@earendil-works/pi-tui": "^0.78.0",
+    "@sinclair/typebox": "^0.34.48",
+    "@types/node": "^25.5.0",
+    "jiti": "^2.7.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  },
+  "directories": {
+    "doc": "docs",
+    "test": "tests"
+  },
+  "bugs": {
+    "url": "https://github.com/coctostan/pi-readseek/issues"
+  },
+  "homepage": "https://github.com/coctostan/pi-readseek#readme"
+}

package/prompts/edit.md

@@ -0,0 +1,113 @@
+Surgically edit existing text files. Prefer hash-verified anchored edits from fresh `read`, `grep`, `search`, or `write` output; copy `LINE:HASH` anchors exactly.
+
+`edit` requires the target file to have been anchored earlier in the current session. If you get `file-not-read`, run `read`, `grep`, `search`, or `write` first.
+
+## Variants
+
+| Variant | Use | Anchors |
+|---|---|---|
+| `set_line` | Replace/delete one line | 1 |
+| `replace_lines` | Replace/delete a contiguous range | 2 |
+| `insert_after` | Insert after an existing line | 1 |
+| `replace_symbol` | Replace one function/class/method/etc. | 0 (`symbol`) |
+| `replace` | String replacement escape hatch; one match by default, all with `all: true` | 0 |
+
+Set `new_text` (or `replace_lines` `new_text`) to `""` to delete the anchored line(s). For an intentionally blank line, use `"\n"` or whitespace content, not `""`.
+Prefer `set_line`, `replace_lines`, and `insert_after`: they verify the file still matches the anchored content. Use `replace` only when anchors are impractical, such as repeated text across many unrelated lines.
+
+`replace` is exact-only by default: missing `old_text` fails with `text-not-found`. Wrap old_text/new_text in {replace: ...} — a bare top-level `{old_text, new_text}` inside `edits[]` is rejected with guidance. `fuzzy: true` is a narrow fallback that only normalizes whitespace and confusable Unicode (e.g. smart hyphens) after exact matching fails; it is **not approximate or Levenshtein/semantic matching** and will not find renamed or reworded text. When fuzzy matching is used, the response warns that exact text was not found.
+
+## Input shape
+
+```json
+{
+  "path": "src/foo.ts",
+  "edits": [
+    { "set_line": { "anchor": "42:ab1", "new_text": "const x = 2;" } },
+    { "replace_lines": { "start_anchor": "50:c3d", "end_anchor": "55:e4f", "new_text": "const y = 3;\nreturn y;" } },
+    { "insert_after": { "anchor": "60:f5a", "new_text": "// TODO\n" } },
+    { "replace_symbol": { "symbol": "add", "new_body": "export function add(a, b) {\n  return a + b;\n}" } },
+    { "replace": { "old_text": "value", "new_text": "result", "all": true } }
+  ]
+}
+```
+
+Use only the variant(s) needed for the task; the example shows all shapes together for reference. Each `edits[]` entry must contain exactly one variant key. `new_text` / `new_body` is plain file content — no hash prefixes or diff markers.
+
+## Optional post-edit verification
+
+`postEditVerify: true` opts into post-write persisted-content verification for this one call. It is default off: when omitted or false, successful edits use the normal fast path and do not perform an extra read-back check.
+
+When enabled, `edit` first runs the normal validation and write path. Only after the write succeeds, it reads the file back from disk and compares the persisted content to the exact intended content, including BOM restoration and original line-ending restoration. This is not syntax validation; syntax validation is the separate pre-write `syntaxValidate` / `PI_HASHLINE_SYNTAX_VALIDATE` guard described below.
+
+## `replace_symbol`
+
+Use `replace_symbol` to replace one function, class, method, interface, type, enum, or similar symbol. Query symbols like `read symbol:`: `Name`, `Class.method`, or `Name@<line>`.
+
+Rules:
+- Use an exact name, dotted path, or `@<line>`. If `read({symbol})` returned a fuzzy match, confirm the exact symbol before editing.
+- Supported for TypeScript, JavaScript, Rust, and Java. For other languages, use anchored edits.
+- `new_body` must not be empty or whitespace-only.
+- Write `new_body` without extra leading indentation; `edit` re-indents it to match the original symbol.
+- If `new_body` appears to declare a different symbol name, the edit still applies but returns a `name-mismatch` warning.
+- Do not combine `replace_symbol` with anchored edits that touch the same lines. Duplicate/overlapping `replace_symbol` ranges are rejected.
+
+## Stale anchors
+
+If anchors no longer match, `edit` fails with a hash mismatch (`hash-mismatch`) and shows nearby current lines. Lines marked `>>>` include updated anchors:
+
+```text
+>>> 41:b34|  const renamed = 3;
+```
+
+Copy the updated `LINE:HASH` and retry. If the target moved farther away, re-run `read`, `grep`, `search`, or `write` for fresh anchors.
+
+If `edit` auto-relocates an anchor, check the warning and verify the edit landed in the intended place.
+
+## Validation and warnings
+
+- All edits are checked before writing; if a hard validation fails, nothing is written.
+- Anchored edits are applied bottom-up so line numbers stay stable.
+- `no-op` means the requested edit matched the current file already or produced identical content.
+- A whitespace-only warning means formatting changed but behavior probably did not.
+- A `replace`-only success may include a reminder to prefer anchored edits next time.
+
+Syntax validation runs before writing when supported:
+- Supported: Rust, C++, C headers, Java.
+- Default `warn`: write succeeds, but warnings include `syntax-regression: lines X-Y`.
+- `block`: aborts without writing.
+- `off`: skips validation.
+- `PI_HASHLINE_SYNTAX_VALIDATE` can set the default mode.
+
+Existing syntax errors are tolerated; the warning is for newly introduced parser errors.
+
+## Diff data contract
+
+Successful `edit` results include `details.diffData` and `details.readseekValue.diffData` in addition to the existing `details.diff` / `readseekValue.diff` string fields. The string fields remain the backward-compatible human-readable fallback.
+
+Successful `edit` results also include `details.patch`: a standard unified diff (`---`/`+++` file headers and `@@` hunk headers) generated from the pre-/post-edit file contents. Use `details.patch` when you need a portable, tool-agnostic patch (e.g. to apply elsewhere); use the compact `details.diff` hashline string for human-readable in-session display. `details.patch` is additive and does not change `details.diff`.
+
+`diffData` is a stable versioned contract:
+
+```ts
+type DiffData = {
+  version: 1;
+  entries: Array<
+    | { kind: "context"; oldLine: number; newLine: number; text: string }
+    | { kind: "add"; newLine: number; text: string }
+    | { kind: "remove"; oldLine: number; text: string }
+    | { kind: "meta"; text: string }
+  >;
+  stats: { added: number; removed: number; context: number };
+  language?: string;
+  blockRanges?: Array<{ kind: "add" | "remove"; startLine: number; endLine: number }>;
+  inlineDiffs?: Array<{
+    removeLineIndex: number;
+    addLineIndex: number;
+    removeSpans: Array<{ kind: "equal" | "remove" | "add"; text: string }>;
+    addSpans: Array<{ kind: "equal" | "remove" | "add"; text: string }>;
+  }>;
+};
+```
+
+For compact one-line hashline diffs, `details.diff` remains compact, while `diffData.entries` uses expanded remove/add rows so renderers can show inline word changes without breaking hashline output.

package/prompts/find.md

@@ -0,0 +1,19 @@
+Find files recursively by name. Uses glob patterns by default, respects nested `.gitignore`, includes hidden files, and returns relative paths.
+
+## Parameters
+
+- `pattern` — required. Glob by default; with `regex: true`, JavaScript regex against each basename.
+- `path` — directory to search, default cwd.
+- `type` — `"file"` default, `"dir"`, or `"any"`.
+- `limit` — max returned entries after filtering/sorting, default 1000.
+- `maxDepth` — non-negative directory depth limit.
+- `sortBy` — `"name"` default, `"mtime"`, or `"size"`; use `reverse: true` for descending/newest/largest first.
+- `modifiedSince` — keep entries modified strictly after an ISO date/time or relative age like `30m`, `1h`, `24h`, `7d`.
+- `minSize` / `maxSize` — file-size filters, inclusive; numbers are bytes, strings accept 1024-based `KB`, `MB`, `GB`, etc. Directories are not removed by size filters.
+
+## Output and usage
+
+One relative path per line. Directories end with `/`. If results exceed `limit` or 50 KB, output says it was truncated.
+Filtering and sorting happen before `limit`, so queries like largest/newest files work as expected.
+
+Use `find` for recursive file-name discovery, `ls` for one directory, and `grep` for file contents. Remember: `pattern` matches basenames, not full paths.

package/prompts/grep.md

@@ -0,0 +1,26 @@
+Search file contents. Non-summary results return `LINE:HASH` anchors usable directly by `edit`; no follow-up `read` is needed.
+
+## Modes
+
+- Default: matching lines only. Output lines are `path:>>LINE:HASH|content`; `>>` marks matches.
+- `context: N`: include N lines before/after each match. Context lines use `path:  LINE:HASH|content`; nearby ranges are merged/deduped.
+- `summary: true`: return per-file match counts only — no line content or anchors. Use first for broad searches, then narrow with `path`/`glob`.
+- `scope: "symbol"`: group matches by enclosing symbol. By default returns the full symbol block. `scopeContext: N` windows to ±N lines around each match, clipped to the symbol; `0` returns only match lines. Ignored when `summary: true`.
+
+## Parameters
+
+- `pattern` — regex by default; use `literal: true` for exact strings or regex metacharacters.
+- `path` — file or directory, default cwd.
+- `glob` — file filter, e.g. `'*.ts'` or `'**/*.test.ts'`.
+- `ignoreCase` — case-insensitive search.
+- `context` — surrounding lines for normal grep.
+- `limit` — max matches, default 100.
+- `summary` — counts only, no anchors.
+- `scope` — only `"symbol"` is supported.
+- `scopeContext` — non-negative context within symbol scope; requires `scope: "symbol"`.
+
+## Truncation and guidance
+
+If matches hit `limit`, output appends `[Results truncated at N matches — refine pattern or increase limit]`. Large non-summary results may cap displayed matches per file and/or head-truncate by output budget; narrow with `summary`, `path`, `glob`, or a more specific pattern.
+
+Use `grep` for text search. For structural code patterns such as calls, imports, or JSX, prefer `search`.

package/prompts/ls.md

@@ -0,0 +1,11 @@
+List one directory. Shows directories first with `/`, then files, sorted alphabetically; dotfiles are included.
+
+## Parameters
+
+- `path` — directory to list, default cwd.
+- `limit` — max entries, default 500; must be positive.
+- `glob` — optional entry-name filter such as `*.ts` or `.env*`.
+
+## Usage
+
+Output is one entry per line. Use `ls` to inspect a single directory, `find` for recursive discovery, and `read` for file contents. If output exceeds `limit` or 50 KB, it says so.

package/prompts/read.md

@@ -0,0 +1,33 @@
+Read text files with `LINE:HASH|content` anchors usable by `edit`. Default cap: {{DEFAULT_MAX_LINES}} lines or {{DEFAULT_MAX_BYTES}}. Images return attachments, not edit anchors.
+
+## Parameters
+
+- `offset` / `limit` — positive line numbers for targeted reads; `offset` is 1-indexed.
+- `map: true` — append a full-file structural map even for small files. May combine with `offset` / `limit`; cannot combine with `symbol` or `bundle`.
+- `symbol: "Name"` — read one symbol range by name, with hash anchors. Supports `ClassName.method`, Java package-relative names, and `Name@<line>` disambiguation. Cannot combine with `offset` / `limit`.
+- `bundle: "local"` — with `symbol`, also include direct same-file local support when available. Cannot combine with `map`.
+
+When a full-file read is truncated, a readseek structural map is appended automatically when available. Use that map's line ranges for follow-up `read({ offset, limit })`. Map and symbol coverage depends on readseek language support.
+
+## Symbol examples
+
+| Query | Reads |
+|---|---|
+| `{ "symbol": "processEvent" }` | function or top-level symbol |
+| `{ "symbol": "EventEmitter" }` | class/interface/type/enum/etc. |
+| `{ "symbol": "EventEmitter.emit" }` | child method/member |
+| `{ "symbol": "Foo.bar@42" }` | specific overload/definition near line 42 |
+| `{ "symbol": "handleRequest", "bundle": "local" }` | symbol plus direct local support |
+
+## Symbol resolution
+
+`@<line>` only applies as a trailing suffix like `Foo.bar@42`; names such as `foo@bar` are ordinary queries. Resolution order: containing range → nearest symbol starting at/after the requested line → nearest symbol above it. If unresolved but same-name candidates exist, the response lists retry hints like `name@<startLine>`.
+
+Result behavior:
+- **Found**: returns only the symbol range with `[Symbol: name (kind), lines X-Y of Z]`.
+- **Ambiguous**: returns candidate names/kinds/ranges; retry with dot notation or `@<line>`.
+- **Fuzzy**: returns the best camelCase/substring match with a warning banner and confirmation hint. Verify before editing from fuzzy-match anchors.
+- **Not found**: falls back to normal read with a warning listing available symbols.
+- **Unmappable**: falls back to normal read with a warning.
+
+Hash anchors from symbol and bundled reads are valid for `edit`.

package/prompts/sg.md

@@ -0,0 +1,25 @@
+AST-aware structural code search. Use when text search is too broad or brittle and you need code shape, such as calls, imports, declarations, or JSX. Returns matches grouped by file with edit-ready hashline anchors.
+
+## Parameters
+
+- `pattern` — ast-grep-style pattern to match.
+- `lang` — language hint such as `typescript`, `tsx`, `javascript`, `jsx`, `rust`, or `python`; set it when syntax is ambiguous.
+- `path` — file or directory, default cwd.
+
+## Pattern syntax
+
+- `$NAME` matches one AST node.
+- `$_` matches any one node.
+- `$$$ARGS` matches zero or more nodes; use `$$$` for variable-length args, body statements, object fields, JSX children, etc.
+
+## Examples
+
+- `console.log($$$ARGS)` — calls.
+- `import $NAME from '$SOURCE'` — default imports.
+- `export function $NAME($$$PARAMS) { $$$BODY }` — exported functions.
+- `$OBJ.$METHOD($$$ARGS)` — method calls.
+- `<$TAG $$$ATTRS>$$$CHILDREN</$TAG>` — JSX/TSX elements.
+
+## Tips
+
+Patterns are parsed as code, not text: formatting is mostly ignored, but syntax must be valid for `lang`. Include semicolons in languages that require them. Use `grep` for plain text and `search` for structure.

package/prompts/write.md

@@ -0,0 +1,46 @@
+Write full file content. Creates new files and parent directories, overwrites existing files, and returns `LINE:HASH` anchors for immediate `edit` use.
+
+## Use / avoid
+
+Use `write` to create a file or intentionally replace a whole file. For small changes or appends, `read` first and use `edit` (`insert_after` for appends).
+
+Existing files are overwritten without confirmation. Binary-looking content is written, but hashlines are not generated, so there are no anchors to feed into `edit`.
+
+## Parameters
+
+- `path` — relative or absolute file path.
+- `content` — complete file contents.
+- `map` — optional; append a structural map when possible. Map append is best-effort and write still succeeds if map generation fails.
+
+## Output
+
+Successful text writes return `LINE:HASH|content`; display hashlines escape control characters for safe rendering. Visible output is capped at 2000 lines or 50 KB, but full anchors remain available in `readseekValue`.
+
+## Diff data contract
+
+Successful text `write` results include additive final `details.diff`, `details.readseekValue.diff`, `details.diffData`, and `details.readseekValue.diffData` fields. The string fields remain the backward-compatible human-readable fallback.
+
+`diffData` is a stable versioned contract:
+
+```ts
+type DiffData = {
+  version: 1;
+  entries: Array<
+    | { kind: "context"; oldLine: number; newLine: number; text: string }
+    | { kind: "add"; newLine: number; text: string }
+    | { kind: "remove"; oldLine: number; text: string }
+    | { kind: "meta"; text: string }
+  >;
+  stats: { added: number; removed: number; context: number };
+  language?: string;
+  blockRanges?: Array<{ kind: "add" | "remove"; startLine: number; endLine: number }>;
+  inlineDiffs?: Array<{
+    removeLineIndex: number;
+    addLineIndex: number;
+    removeSpans: Array<{ kind: "equal" | "remove" | "add"; text: string }>;
+    addSpans: Array<{ kind: "equal" | "remove" | "add"; text: string }>;
+  }>;
+};
+```
+
+For compact one-line hashline diffs, `details.diff` remains compact, while `diffData.entries` uses expanded remove/add rows so renderers can show inline word changes without breaking hashline output.

package/src/binary-detect.ts

@@ -0,0 +1,22 @@
+/**
+ * Returns true if the buffer appears to contain binary (non-text) content.
+ *
+ * Detection strategy:
+ *   1. NUL byte (0x00) — universally indicates binary
+ *   2. Invalid UTF-8 sequences — Node.js decodes them as U+FFFD replacement
+ *      characters. To avoid false-positives on valid UTF-8 text that
+ *      intentionally contains U+FFFD (encoded as EF BF BD), we do a round-trip
+ *      check: if re-encoding the decoded string produces a different byte
+ *      sequence, then U+FFFD was introduced by the decoder — not present in
+ *      the original bytes as valid UTF-8.
+ */
+export function looksLikeBinary(buf: Buffer): boolean {
+  if (buf.length === 0) return false;
+  // Fast path: NUL byte is a reliable binary marker
+  if (buf.includes(0)) return true;
+  const decoded = buf.toString("utf8");
+  if (!decoded.includes("\uFFFD")) return false;
+
+  // If U+FFFD came from invalid byte sequences, re-encoding will differ.
+  return !Buffer.from(decoded, "utf8").equals(buf);
+}

package/src/binary-resolution.ts

@@ -0,0 +1,77 @@
+import { existsSync as defaultExistsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+
+const require = createRequire(import.meta.url);
+
+export interface ResolveBundledBinDeps {
+  resolvePackageJson?: (specifier: string) => string;
+  readPackageJson?: (packageJsonPath: string) => string;
+  existsSync?: (candidate: string) => boolean;
+  platform?: NodeJS.Platform;
+}
+
+function defaultResolvePackageJson(specifier: string): string {
+  return require.resolve(specifier);
+}
+
+function defaultReadPackageJson(packageJsonPath: string): string {
+  return readFileSync(packageJsonPath, "utf8");
+}
+
+function binEntryFor(packageJsonText: string, binName: string): string | undefined {
+  const parsed = JSON.parse(packageJsonText) as { bin?: string | Record<string, string> };
+  if (typeof parsed.bin === "string") return parsed.bin;
+  return parsed.bin?.[binName];
+}
+
+function commandCandidates(basePath: string, platform: NodeJS.Platform): string[] {
+  if (platform !== "win32") return [basePath];
+  return [`${basePath}.exe`, basePath];
+}
+
+function firstExisting(candidates: string[], existsSync: (candidate: string) => boolean): string | undefined {
+  return candidates.find((candidate) => existsSync(candidate));
+}
+
+export interface ExecutableCommand {
+  command: string;
+  argsPrefix: string[];
+}
+
+export function executableCommand(binaryPath: string, platform: NodeJS.Platform = process.platform): ExecutableCommand {
+  if (platform === "win32" && /\.js$/i.test(binaryPath)) {
+    return { command: process.execPath, argsPrefix: [binaryPath] };
+  }
+  return { command: binaryPath, argsPrefix: [] };
+}
+
+export function resolveBundledBin(
+  packageName: string,
+  binName: string,
+  fallbackCommand: string,
+  deps: ResolveBundledBinDeps = {},
+): string {
+  const resolvePackageJson = deps.resolvePackageJson ?? defaultResolvePackageJson;
+  const readPackageJson = deps.readPackageJson ?? defaultReadPackageJson;
+  const existsSync = deps.existsSync ?? defaultExistsSync;
+  const platform = deps.platform ?? process.platform;
+
+  try {
+    const packageJsonPath = resolvePackageJson(`${packageName}/package.json`);
+    const packageDir = dirname(packageJsonPath);
+    const binEntry = binEntryFor(readPackageJson(packageJsonPath), binName);
+    if (!binEntry) return fallbackCommand;
+
+
+    const packageBinCandidate = firstExisting(
+      commandCandidates(resolve(packageDir, binEntry), platform),
+      existsSync,
+    );
+    if (packageBinCandidate) return packageBinCandidate;
+  } catch {
+    // Fall through to PATH fallback.
+  }
+
+  return fallbackCommand;
+}