@mammothb/pi-hashline 0.2.0 → 0.2.1

package/README.md

@@ -0,0 +1,49 @@
+# pi-hashline
+
+Hashline anchoring for pi — content-addressed read/edit with stale-edit
+protection.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `read` | Read files with `\u00b6PATH#TAG` headers. Copy the header to use with `edit`. |
+| `edit` | Edit files using hashline anchoring. Validates tags before writes — stale tags are rejected. |
+| `write` | Create or overwrite files. Returns a `\u00b6PATH#TAG` header for immediate editing. |
+| `grep` | Search with ripgrep. Matching files get `\u00b6PATH#TAG` headers. |
+
+## Usage
+
+```sh
+pi -e ./index.ts
+```
+
+## Grammar
+
+The hashline grammar is documented in [src/prompt.md](src/prompt.md) —
+this is the same reference injected into the LLM's system prompt.  Key
+operations:
+
+- `replace N..M:` — replace lines N through M with body rows
+- `delete N..M` — delete lines N through M
+- `insert before|after N:` — insert body rows relative to line N
+- `insert head:|tail:` — insert at file boundaries
+
+Body rows use `+TEXT` syntax.  There are no `-` rows.
+
+## Recovery
+
+Stale-tag edits (file changed between read and edit) are automatically
+recovered via two strategies:
+
+1. **Structured-patch 3-way merge** — apply edits to the cached snapshot,
+   create a structured patch, apply to live content.
+2. **Anchor-content replay** — when anchors still match, apply edits
+   directly to the live file.
+
+## Peer Dependencies
+
+- `@earendil-works/pi-coding-agent`
+- `@earendil-works/pi-ai`
+- `@earendil-works/pi-tui`
+- `typebox`

package/index.ts

@@ -10,16 +10,16 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { createEditTool } from "./src/edit";
-import { createGrepTool } from "./src/grep";
-import { injectPrompt } from "./src/prompt";
-import { createReadTool } from "./src/read";
-import { InMemorySnapshotStore } from "./src/snapshots";
-import { createWriteTool } from "./src/write";
+import { createEditTool } from "./src/edit.js";
+import { createGrepTool } from "./src/grep.js";
+import { InMemorySnapshotStore } from "./src/lib/hashline/snapshots.js";
+import { injectPrompt } from "./src/prompt.js";
+import { createReadTool } from "./src/read.js";
+import { createWriteTool } from "./src/write.js";
 
-export * from "./src/format";
-export * from "./src/snapshots";
-export * from "./src/types";
+export * from "./src/lib/hashline/format.js";
+export * from "./src/lib/hashline/snapshots.js";
+export * from "./src/lib/hashline/types.js";
 
 export default function (pi: ExtensionAPI) {
   const snapshots = new InMemorySnapshotStore();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mammothb/pi-hashline",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Hashline anchoring for pi — content-addressed read/edit with stale-edit protection",
   "keywords": [
     "pi-package"
@@ -22,6 +22,6 @@
     "typebox": "*"
   },
   "dependencies": {
-    "diff": "^8.0.0"
+    "diff": "8.0.4"
   }
 }

package/src/edit.ts

@@ -14,64 +14,32 @@ import { constants } from "node:fs";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-
-import { applyEdits } from "./apply";
+import { applyEdits } from "./lib/hashline/apply.js";
 import {
   computeFileHash,
   formatHashlineHeader,
   formatNumberedLines,
-} from "./format";
-import { Patch, type PatchSection } from "./input";
+} from "./lib/hashline/format.js";
+import { Patch, type PatchSection } from "./lib/hashline/input.js";
 import {
   HEADTAIL_DRIFT_WARNING,
   MismatchError,
   missingTagMessage,
   nonExistentFileMessage,
   unrecognizedHashMessage,
-} from "./messages";
+} from "./lib/hashline/messages.js";
 import {
   detectLineEnding,
   normalizeToLF,
   restoreLineEndings,
-} from "./normalize";
-import { tryRecover } from "./recovery";
-import type { SnapshotStore } from "./snapshots";
-
-// ─── Schema ──────────────────────────────────────────────────────────
-
-const EditSchema = Type.Object({
-  edits: Type.String({
-    description:
-      "Hashline patch text: one or more ¶PATH#TAG sections followed by edit operations " +
-      "(replace N..M:, delete N..M, insert before|after|head|tail:). Copy the ¶PATH#TAG " +
-      "header from the read tool output.",
-  }),
-});
-
-// ─── Details type ────────────────────────────────────────────────────
-
-export interface EditToolDetails {
-  /** Per-file results. */
-  files: EditFileResult[];
-  /** Whether any files were changed. */
-  changed: boolean;
-}
-
-export interface EditFileResult {
-  /** Display-relative path. */
-  path: string;
-  /** New snapshot tag after the edit. */
-  fileHash: string;
-  /** Hashline header for the new version. */
-  header: string;
-  /** First changed line (1-indexed), or undefined for no-op. */
-  firstChangedLine?: number;
-  /** Warnings from parsing or drift. */
-  warnings?: string[];
-  /** Numbered preview lines around the change. */
-  preview: string;
-}
+} from "./lib/hashline/normalize.js";
+import { tryRecover } from "./lib/hashline/recovery.js";
+import type { SnapshotStore } from "./lib/hashline/snapshots.js";
+import {
+  type EditFileResult,
+  EditSchema,
+  type EditToolDetails,
+} from "./schema.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────
 

package/src/grep.ts

@@ -1,7 +1,7 @@
 /**
  * Hashline grep tool override.
  *
- * Overrides the built-in `grep` tool to emit `¶PATH#TAG` headers for each
+ * Overrides the built-in `grep` tool to emit `\u00b6PATH#TAG` headers for each
  * file with matches. Uses ripgrep (`rg --json`) for fast, gitignore-aware
  * search. After finding matches, reads each matching file to compute its
  * content hash and record a snapshot — so the agent can immediately `edit`
@@ -13,79 +13,26 @@ import { constants } from "node:fs";
 import { access, readFile } from "node:fs/promises";
 import { isAbsolute, relative, resolve } from "node:path";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-
-import { computeFileHash, formatHashlineHeader } from "./format";
-import { normalizeToLF } from "./normalize";
-import type { SnapshotStore } from "./snapshots";
-
-// ─── Schema ──────────────────────────────────────────────────────────
-
-const GrepSchema = Type.Object({
-  pattern: Type.String({
-    description: "The regex pattern to search for (ripgrep syntax)",
-  }),
-  path: Type.Optional(
-    Type.String({
-      description:
-        "File or directory to search in (default: current working directory)",
-    }),
-  ),
-  glob: Type.Optional(
-    Type.String({
-      description:
-        "Filter files by glob pattern, e.g. '*.ts' or '**/*.spec.ts'",
-    }),
-  ),
-  context: Type.Optional(
-    Type.Number({
-      description:
-        "Number of lines to show before and after each match (default: 0)",
-    }),
-  ),
-  ignoreCase: Type.Optional(
-    Type.Boolean({
-      description: "Case-insensitive search (default: false)",
-    }),
-  ),
-  literal: Type.Optional(
-    Type.Boolean({
-      description:
-        "Treat pattern as literal string instead of regex (default: false)",
-    }),
-  ),
-});
-
-// ─── Details type ────────────────────────────────────────────────────
-
-export interface GrepToolDetails {
-  /** Number of files with matches. */
-  filesWithMatches: number;
-  /** Total matching lines across all files. */
-  totalMatches: number;
-  /** Per-file results. */
-  files: GrepFileResult[];
-}
-
-export interface GrepFileResult {
-  /** Display-relative path. */
-  path: string;
-  /** Content hash of the full file (for subsequent editing). */
-  fileHash: string;
-  /** Hashline header for this file snapshot. */
-  header: string;
-  /** Number of matches in this file. */
-  matchCount: number;
-}
-
-// ─── Constants ───────────────────────────────────────────────────────
+import {
+  computeFileHash,
+  formatHashlineHeader,
+} from "./lib/hashline/format.js";
+import { normalizeToLF } from "./lib/hashline/normalize.js";
+import type { SnapshotStore } from "./lib/hashline/snapshots.js";
+import {
+  type GrepFileResult,
+  GrepSchema,
+  type GrepToolDetails,
+} from "./schema.js";
+
+// -- Constants ----------------------------------------------------------
 
 const DEFAULT_MAX_BYTES = 50 * 1024;
 const DEFAULT_MAX_FILES = 50;
 const MAX_CONCURRENT_READS = 8;
 const GREP_MAX_LINE_LENGTH = 500;
 
-// ─── Helpers ─────────────────────────────────────────────────────────
+// -- Helpers ------------------------------------------------------------
 
 function resolveDisplayPath(rawPath: string, cwd: string): string {
   const resolved = resolve(cwd, rawPath);
@@ -100,7 +47,7 @@ function resolveDisplayPath(rawPath: string, cwd: string): string {
   return resolved;
 }
 
-// ─── rg invocation ───────────────────────────────────────────────────
+// -- rg invocation ------------------------------------------------------
 
 interface RgMatch {
   path: string;
@@ -228,7 +175,7 @@ function runRg(
   });
 }
 
-// ─── Tool creator ────────────────────────────────────────────────────
+// -- Tool creator -------------------------------------------------------
 
 export function createGrepTool(
   snapshots: SnapshotStore,
@@ -237,13 +184,13 @@ export function createGrepTool(
     name: "grep",
     label: "Grep",
     description:
-      "Search file contents using ripgrep. Results include ¶PATH#TAG headers " +
+      "Search file contents using ripgrep. Results include \u00b6PATH#TAG headers " +
       "so you can immediately edit matching files without re-reading them. " +
       "Requires ripgrep (rg) to be installed.",
     promptSnippet:
-      "Search file contents — matching files get ¶PATH#TAG headers for immediate editing",
+      "Search file contents — matching files get \u00b6PATH#TAG headers for immediate editing",
     promptGuidelines: [
-      "Use grep to find code by pattern. Every matching file starts with a ¶PATH#TAG header — use that tag to edit the file without re-reading it. Use read if you need to see the full file content around the match.",
+      "Use grep to find code by pattern. Every matching file starts with a \u00b6PATH#TAG header — use that tag to edit the file without re-reading it. Use read if you need to see the full file content around the match.",
       "Use glob to filter by file extension (e.g. '*.ts'), context to show surrounding lines, ignoreCase for case-insensitive search, and literal to match a fixed string instead of regex.",
     ],
     parameters: GrepSchema,

package/src/{apply.ts → lib/hashline/apply.ts}

@@ -7,8 +7,8 @@
  * line preserve order (before-anchor → replacement → after-anchor).
  */
 
-import { cloneCursor } from "./tokenizer";
-import type { Anchor, ApplyResult, Edit } from "./types";
+import { cloneCursor } from "./tokenizer.js";
+import type { Anchor, ApplyResult, Edit } from "./types.js";
 
 // ─── Internal types ──────────────────────────────────────────────────
 

package/src/{format.ts → lib/hashline/format.ts}

@@ -6,7 +6,7 @@
 
 import { createHash } from "node:crypto";
 
-import type { Cursor } from "./types";
+import type { Cursor } from "./types.js";
 
 /** File-section header prefix: `¶path#hash`. */
 export const HL_FILE_PREFIX = "¶";

package/src/{input.ts → lib/hashline/input.ts}

@@ -11,9 +11,9 @@
 
 import * as path from "node:path";
 
-import { parsePatch } from "./parser";
-import { Tokenizer } from "./tokenizer";
-import type { Edit, SplitOptions } from "./types";
+import { parsePatch } from "./parser.js";
+import { Tokenizer } from "./tokenizer.js";
+import type { Edit, SplitOptions } from "./types.js";
 
 // ─── Header parsing ──────────────────────────────────────────────────
 

package/src/{messages.ts → lib/hashline/messages.ts}

@@ -4,7 +4,7 @@
  * keeps wording stable across the rendering paths that surface them.
  */
 
-import { HL_FILE_HASH_SEP, HL_FILE_PREFIX } from "./format";
+import { HL_FILE_HASH_SEP, HL_FILE_PREFIX } from "./format.js";
 
 // ─── Error messages ──────────────────────────────────────────────────
 

package/src/{parser.ts → lib/hashline/parser.ts}

@@ -7,10 +7,10 @@
  * requires file text + language detection and happens at apply time.
  */
 
-import { HL_PAYLOAD_REPLACE } from "./format";
-import type { BlockTarget, Token } from "./tokenizer";
-import { Tokenizer } from "./tokenizer";
-import type { Anchor, Cursor, Edit, ParsedRange } from "./types";
+import { HL_PAYLOAD_REPLACE } from "./format.js";
+import type { BlockTarget, Token } from "./tokenizer.js";
+import { Tokenizer } from "./tokenizer.js";
+import type { Anchor, Cursor, Edit, ParsedRange } from "./types.js";
 
 // ─── Warning / error message constants ───────────────────────────────
 
@@ -291,7 +291,6 @@ function feedToken(state: ParseState, token: Token): void {
 
   switch (token.kind) {
     case "envelope-begin":
-    case "envelope-separator":
     case "blank":
       // Silently consumed
       return;

package/src/{recovery.ts → lib/hashline/recovery.ts}

@@ -14,14 +14,14 @@
  */
 
 import { applyPatch, structuredPatch } from "diff";
-import { applyEdits } from "./apply";
+import { applyEdits } from "./apply.js";
 import {
   RECOVERY_EXTERNAL_WARNING,
   RECOVERY_SESSION_CHAIN_WARNING,
   RECOVERY_SESSION_REPLAY_WARNING,
-} from "./messages";
-import type { SnapshotStore } from "./snapshots";
-import type { Edit } from "./types";
+} from "./messages.js";
+import type { SnapshotStore } from "./snapshots.js";
+import type { Edit } from "./types.js";
 
 // ─── Recovery result ─────────────────────────────────────────────────
 

package/src/{snapshots.ts → lib/hashline/snapshots.ts}

@@ -16,7 +16,7 @@
  * edit onto the live content.
  */
 
-import { computeFileHash } from "./format";
+import { computeFileHash } from "./format.js";
 
 /**
  * One full-file version observed at a point in time. The tag the model sees

package/src/{tokenizer.ts → lib/hashline/tokenizer.ts}

@@ -17,8 +17,8 @@ import {
   HL_INSERT_TAIL,
   HL_PAYLOAD_REPLACE,
   HL_REPLACE_KEYWORD,
-} from "./format";
-import type { Anchor, Cursor, ParsedRange } from "./types";
+} from "./format.js";
+import type { Anchor, Cursor, ParsedRange } from "./types.js";
 
 // ─── BlockTarget (the target of a hunk header) ───────────────────────
 
@@ -42,7 +42,6 @@ export type Token =
   | (TokenBase & { kind: "blank" })
   | (TokenBase & { kind: "envelope-begin" })
   | (TokenBase & { kind: "envelope-end" })
-  | (TokenBase & { kind: "envelope-separator" })
   | (TokenBase & { kind: "abort" })
   | (TokenBase & { kind: "header"; path: string; fileHash?: string })
   | (TokenBase & { kind: "op-block"; target: BlockTarget })
@@ -51,10 +50,9 @@ export type Token =
 
 // ─── Envelope / abort markers ────────────────────────────────────────
 
-const ENVELOPE_BEGIN = "<<<";
-const ENVELOPE_END = ">>>";
-const ENVELOPE_SEPARATOR = "---";
-const ABORT_MARKER = "...";
+const ENVELOPE_BEGIN = "*** Begin Patch";
+const ENVELOPE_END = "*** End Patch";
+const ABORT_MARKER = "*** Abort";
 
 // ─── Line-number scanner ─────────────────────────────────────────────
 
@@ -290,9 +288,6 @@ function classifyLine(line: string, lineNum: number): Token {
   if (trimmed === ENVELOPE_END) {
     return { kind: "envelope-end", lineNum };
   }
-  if (trimmed === ENVELOPE_SEPARATOR) {
-    return { kind: "envelope-separator", lineNum };
-  }
   if (trimmed === ABORT_MARKER) {
     return { kind: "abort", lineNum };
   }
@@ -373,7 +368,6 @@ export class Tokenizer {
     return (
       trimmed === ENVELOPE_BEGIN ||
       trimmed === ENVELOPE_END ||
-      trimmed === ENVELOPE_SEPARATOR ||
       trimmed === ABORT_MARKER
     );
   }
@@ -389,6 +383,3 @@ export function cloneCursor(cursor: Cursor): Cursor {
   }
   return cursor;
 }
-
-// Re-export for convenience
-export type { Anchor, Cursor, ParsedRange } from "./types";

package/src/read.ts

@@ -1,7 +1,7 @@
 /**
  * Hashline read tool override.
  *
- * Overrides the built-in `read` tool to emit `¶PATH#TAG` headers and
+ * Overrides the built-in `read` tool to emit `\u00b6PATH#TAG` headers and
  * record content snapshots. Text files get tagged; images delegate to the
  * native read implementation.
  */
@@ -13,33 +13,16 @@ import {
   createReadToolDefinition,
   type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-
 import {
   computeFileHash,
   formatHashlineHeader,
   formatNumberedLines,
-} from "./format";
-import type { SnapshotStore } from "./snapshots";
+} from "./lib/hashline/format.js";
+import type { SnapshotStore } from "./lib/hashline/snapshots.js";
+import { ReadSchema, type ReadToolDetails } from "./schema.js";
 
 const DEFAULT_MAX_BYTES = 50 * 1024;
 
-const ReadSchema = Type.Object({
-  path: Type.String({
-    description: "Path to the file to read (relative or absolute)",
-  }),
-  offset: Type.Optional(
-    Type.Number({
-      description: "Line number to start reading from (1-indexed)",
-    }),
-  ),
-  limit: Type.Optional(
-    Type.Number({
-      description: "Maximum number of lines to read",
-    }),
-  ),
-});
-
 /** File extensions handled by the native read tool (images, etc.). */
 const IMAGE_EXTENSIONS = new Set([
   ".png",
@@ -71,19 +54,6 @@ function resolvePath(rawPath: string, cwd: string): string {
   return resolved;
 }
 
-export interface ReadToolDetails {
-  /** Total lines in the file (before offset/limit). */
-  totalLines: number;
-  /** Total bytes in the file. */
-  totalBytes: number;
-  /** Whether the displayed output was truncated. */
-  truncated: boolean;
-  /** Content hash of the full file. */
-  fileHash: string;
-  /** Hashline header for this file snapshot. */
-  header: string;
-}
-
 function errorResult(message: string): {
   content: { type: "text"; text: string }[];
   details: ReadToolDetails;
@@ -124,12 +94,12 @@ export function createReadTool(
     label: "Read",
     description:
       "Read the contents of a file. Supports text files and images (jpg, png, gif, webp). " +
-      "Every text file view includes a ¶PATH#TAG header — copy this tag when editing " +
+      "Every text file view includes a \u00b6PATH#TAG header — copy this tag when editing " +
       "the file so the edit tool can validate you're working against the current version.",
     promptSnippet:
-      "Read file contents — every output includes a ¶PATH#TAG header required by the edit tool",
+      "Read file contents — every output includes a \u00b6PATH#TAG header required by the edit tool",
     promptGuidelines: [
-      "Use read to inspect file content instead of cat or tail. Every text output starts with a ¶PATH#TAG header — copy the entire header (including the tag) into edit tool calls to validate you're editing the current file version.",
+      "Use read to inspect file content instead of cat or tail. Every text output starts with a \u00b6PATH#TAG header — copy the entire header (including the tag) into edit tool calls to validate you're editing the current file version.",
       "Use offset/limit to read large files in sections. Tags are per-file, not per-section — any section of a file carries the same tag.",
     ],
     parameters: ReadSchema,
@@ -142,14 +112,17 @@ export function createReadTool(
       const ext = extname(absolutePath).toLowerCase();
       if (IMAGE_EXTENSIONS.has(ext)) {
         // Native read details type differs from hashline. Safe cast.
+        // biome-ignore lint/suspicious/noExplicitAny: native tool type mismatch in override
+        const onUpdateCast = onUpdate as any;
         const result = nativeRead(ctx).execute(
           toolCallId,
           params,
           signal,
-          onUpdate,
+          onUpdateCast,
           ctx,
         );
-        return result;
+        // biome-ignore lint/suspicious/noExplicitAny: native tool type mismatch in override
+        return result as any;
       }
 
       // Check readability.

package/src/schema.ts

@@ -0,0 +1,147 @@
+/**
+ * TypeBox schemas and Details types for all four hashline tools.
+ * Centralized here so the API surface is visible in one place.
+ */
+
+import { Type } from "typebox";
+
+// -- Edit tool ------------------------------------------------------------
+
+export const EditSchema = Type.Object({
+  edits: Type.String({
+    description:
+      "Hashline patch text: one or more \u00b6PATH#TAG sections followed by edit operations " +
+      "(replace N..M:, delete N..M, insert before|after|head|tail:). Copy the \u00b6PATH#TAG " +
+      "header from the read tool output.",
+  }),
+});
+
+export interface EditToolDetails {
+  /** Per-file results. */
+  files: EditFileResult[];
+  /** Whether any files were changed. */
+  changed: boolean;
+}
+
+export interface EditFileResult {
+  /** Display-relative path. */
+  path: string;
+  /** New snapshot tag after the edit. */
+  fileHash: string;
+  /** Hashline header for the new version. */
+  header: string;
+  /** First changed line (1-indexed), or undefined for no-op. */
+  firstChangedLine?: number;
+  /** Warnings from parsing or drift. */
+  warnings?: string[];
+  /** Numbered preview lines around the change. */
+  preview: string;
+}
+
+// -- Read tool ------------------------------------------------------------
+
+export const ReadSchema = Type.Object({
+  path: Type.String({
+    description: "Path to the file to read (relative or absolute)",
+  }),
+  offset: Type.Optional(
+    Type.Number({
+      description: "Line number to start reading from (1-indexed)",
+    }),
+  ),
+  limit: Type.Optional(
+    Type.Number({
+      description: "Maximum number of lines to read",
+    }),
+  ),
+});
+
+export interface ReadToolDetails {
+  /** Total lines in the file (before offset/limit). */
+  totalLines: number;
+  /** Total bytes in the file. */
+  totalBytes: number;
+  /** Whether the displayed output was truncated. */
+  truncated: boolean;
+  /** Content hash of the full file. */
+  fileHash: string;
+  /** Hashline header for this file snapshot. */
+  header: string;
+}
+
+// -- Write tool -----------------------------------------------------------
+
+export const WriteSchema = Type.Object({
+  path: Type.String({
+    description: "Path to the file to write (relative or absolute)",
+  }),
+  content: Type.String({
+    description: "Content to write to the file",
+  }),
+});
+
+export interface WriteToolDetails {
+  /** Total lines written. */
+  totalLines: number;
+  /** Content hash of the written file. */
+  fileHash: string;
+  /** Hashline header for the new version. */
+  header: string;
+}
+
+// -- Grep tool ------------------------------------------------------------
+
+export const GrepSchema = Type.Object({
+  pattern: Type.String({
+    description: "The regex pattern to search for (ripgrep syntax)",
+  }),
+  path: Type.Optional(
+    Type.String({
+      description:
+        "File or directory to search in (default: current working directory)",
+    }),
+  ),
+  glob: Type.Optional(
+    Type.String({
+      description:
+        "Filter files by glob pattern, e.g. '*.ts' or '**/*.spec.ts'",
+    }),
+  ),
+  context: Type.Optional(
+    Type.Number({
+      description:
+        "Number of lines to show before and after each match (default: 0)",
+    }),
+  ),
+  ignoreCase: Type.Optional(
+    Type.Boolean({
+      description: "Case-insensitive search (default: false)",
+    }),
+  ),
+  literal: Type.Optional(
+    Type.Boolean({
+      description:
+        "Treat pattern as literal string instead of regex (default: false)",
+    }),
+  ),
+});
+
+export interface GrepToolDetails {
+  /** Number of files with matches. */
+  filesWithMatches: number;
+  /** Total matching lines across all files. */
+  totalMatches: number;
+  /** Per-file results. */
+  files: GrepFileResult[];
+}
+
+export interface GrepFileResult {
+  /** Display-relative path. */
+  path: string;
+  /** Content hash of the full file (for subsequent editing). */
+  fileHash: string;
+  /** Hashline header for this file snapshot. */
+  header: string;
+  /** Number of matches in this file. */
+  matchCount: number;
+}

package/src/write.ts

@@ -3,46 +3,23 @@
  *
  * Overrides the built-in `write` tool to record content snapshots so the
  * agent can immediately `edit` the newly created file with a hashline tag.
- * The result includes a `¶PATH#TAG` header matching the read tool output
+ * The result includes a `\u00b6PATH#TAG` header matching the read tool output
  * format.
  */
 
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-
 import {
   computeFileHash,
   formatHashlineHeader,
   formatNumberedLines,
-} from "./format";
-import { normalizeToLF } from "./normalize";
-import type { SnapshotStore } from "./snapshots";
-
-// ─── Schema ──────────────────────────────────────────────────────────
-
-const WriteSchema = Type.Object({
-  path: Type.String({
-    description: "Path to the file to write (relative or absolute)",
-  }),
-  content: Type.String({
-    description: "Content to write to the file",
-  }),
-});
-
-// ─── Details type ────────────────────────────────────────────────────
-
-export interface WriteToolDetails {
-  /** Total lines written. */
-  totalLines: number;
-  /** Content hash of the written file. */
-  fileHash: string;
-  /** Hashline header for the new version. */
-  header: string;
-}
+} from "./lib/hashline/format.js";
+import { normalizeToLF } from "./lib/hashline/normalize.js";
+import type { SnapshotStore } from "./lib/hashline/snapshots.js";
+import { WriteSchema, type WriteToolDetails } from "./schema.js";
 
-// ─── Helpers ─────────────────────────────────────────────────────────
+// -- Helpers ------------------------------------------------------------
 
 function resolveDisplayPath(rawPath: string, cwd: string): string {
   const resolved = resolve(cwd, rawPath);
@@ -57,7 +34,7 @@ function resolveDisplayPath(rawPath: string, cwd: string): string {
   return resolved;
 }
 
-// ─── Tool creator ────────────────────────────────────────────────────
+// -- Tool creator -------------------------------------------------------
 
 export function createWriteTool(
   snapshots: SnapshotStore,
@@ -66,13 +43,13 @@ export function createWriteTool(
     name: "write",
     label: "Write",
     description:
-      "Create or overwrite a file. The result includes a ¶PATH#TAG header — " +
+      "Create or overwrite a file. The result includes a \u00b6PATH#TAG header — " +
       "copy this tag when editing the file so the edit tool can validate " +
       "you're working against the current version.",
     promptSnippet:
-      "Create or overwrite files — returns a ¶PATH#TAG header for immediate editing",
+      "Create or overwrite files — returns a \u00b6PATH#TAG header for immediate editing",
     promptGuidelines: [
-      "Use write to create new files or completely overwrite existing ones. The result includes a ¶PATH#TAG header — use this tag to edit the file immediately without re-reading.",
+      "Use write to create new files or completely overwrite existing ones. The result includes a \u00b6PATH#TAG header — use this tag to edit the file immediately without re-reading.",
     ],
     parameters: WriteSchema,