@hncode/hncode 0.2.0 → 0.3.1

package/src/tools/edit.js

@@ -6,31 +6,90 @@ import fs from 'node:fs';
 import { resolvePath, ensureDir } from './utils.js';
 import { hashStr, normalizeText } from './read.js';
 
-// Hash the <start..end> 1-based line slice of an already-normalized line array.
-function hashLines(lines, start, end) {
-  return hashStr((lines.slice(start - 1, end) || []).join('\n'));
-}
+// Re-exported from read.js so the staleness guard has ONE definition of the
+// region hash. Previously read.js and edit.js each had their own copy; any
+// drift between them would silently disable staleness detection.
+import { hashRegion as hashLines } from './read.js';
 
 export const spec = {
   name: 'Edit',
-  description: 'Replace an exact substring (old_string) with new_string. Fails if old_string is missing or ambiguous (unless replace_all).',
+description: 'Edit a file. PREFERRED: line-range mode (path + start_line/end_line/new_content) — replace by line numbers when you have Read the file and know the positions. Use line-range mode whenever possible; fall back to exact-substring mode (path + old_string/new_string) only when the exact text is known and a line range is not convenient.',
   parameters: {
     type: 'object',
     properties: {
       path: { type: 'string', description: 'Path to the file to edit.' },
-      old_string: { type: 'string', description: 'Exact text to replace, including whitespace and newlines.' },
-      new_string: { type: 'string', description: 'Replacement text.' },
+      old_string: { type: 'string', description: 'Exact text to replace, including whitespace and newlines. Omit when using start_line/end_line.' },
+      new_string: { type: 'string', description: 'Replacement text for old_string.' },
       replace_all: { type: 'boolean', default: false, description: 'Replace all occurrences of old_string.' },
+start_line: { type: 'integer', minimum: 1, description: 'PREFERRED MODE. 1-based first line to replace (requires end_line and new_content). Use this line-range mode first.' },
+      end_line: { type: 'integer', minimum: 1, description: 'PREFERRED MODE. 1-based last line to replace (inclusive; requires start_line).' },
+      new_content: { type: 'string', description: 'PREFERRED MODE. Replacement text for the line range [start_line, end_line]. Requires start_line and end_line.' },
     },
-    required: ['path', 'old_string', 'new_string'],
+// Either line-range mode (start_line+end_line+new_content) OR exact-substring
+    // mode (old_string+new_string). Line-range is the preferred route — see the
+    // tool description and the PREFERRED MODE notes on the params.
+    anyOf: [
+      { required: ['path', 'start_line', 'end_line', 'new_content'] },
+      { required: ['path', 'old_string', 'new_string'] },
+    ],
   },
   async execute(args, ctx) {
     let p;
     try { p = resolvePath(args.path, ctx); } catch (e) { return e.message; }
     let content;
     try { content = fs.readFileSync(p, 'utf8'); } catch (e) { return `Error reading ${args.path}: ${e.message}`; }
-    const { old_string, new_string, replace_all = false } = args;
-    if (old_string === '') return `Error: old_string must not be empty.`;
+    const { start_line, end_line, new_content } = args;
+
+    // ---- LINE-RANGE mode ---------------------------------------------------
+    // `start_line`..`end_line` replace the lines at those 1-based positions,
+    // with NO old_string involved at all. This is the path for "change line 12"
+    // where spelling out the exact current text is awkward. It is fully
+    // self-contained: validate -> check the Read cache -> splice -> write ->
+    // refresh the cache -> return.
+    if (start_line != null && end_line != null) {
+      const start = Number(start_line) | 0, end = Number(end_line) | 0;
+      if (start < 1 || end < start) {
+        return `Error: invalid line range ${start_line}-${end_line} (expected 1-based, start <= end).`;
+      }
+      const eol = content.includes('\r\n') ? '\r\n' : '\n';
+      const lines = content.split(/\r\n|\r|\n/);
+      if (end > lines.length) {
+        return `Error: end_line ${end_line} exceeds file length (${lines.length} lines).`;
+      }
+      // STALENESS: the range must sit inside a region this turn actually Read and
+      // that still matches. Same guarantee as the substring path, checked here
+      // directly (no old_string to search for).
+      const stale = checkStaleRange(p, lines, start, end, ctx);
+      if (stale) return stale;
+
+      const inserted = normalizeText(new_content).split('\n');
+      // The lines being REPLACED, captured before the splice. The TUI renders an
+      // Edit's diff from the tool ARGUMENTS, and line-range mode has no
+      // `old_string` to diff against — so without reporting them here the edit
+      // drew NO diff at all (no +/- rows, no +N/-N counts). Reporting them lets
+      // the caller diff `old_content` -> `new_content`.
+      const replacedText = lines.slice(start - 1, end).join('\n');
+      const out = [...lines.slice(0, start - 1), ...inserted, ...lines.slice(end)];
+      const normUpdated = out.join('\n');
+      const updated = eol === '\r\n' ? normUpdated.split('\n').join('\r\n') : normUpdated;
+      try {
+        ensureDir(p);
+        fs.writeFileSync(p, updated, 'utf8');
+      } catch (e) { return `Error writing ${args.path}: ${e.message}`; }
+      refreshReadPool(p, normUpdated, { start, end: start + inserted.length - 1 }, ctx);
+      const removed = end - start + 1;
+      // Publish the diff for the UI. The Edit line is drawn from these, so a
+      // line-range edit shows the same +/- rows and +N/-N counts as a substring
+      // edit instead of nothing. `ctx.lastEditDiff` is consumed (and cleared) by
+      // the agent loop right after this tool returns.
+      if (ctx) ctx.lastEditDiff = { old: replacedText, new: normalizeText(new_content), startLine: start };
+      return `Edited ${args.path}: replaced lines ${start}-${end} (${removed} line${removed === 1 ? '' : 's'}) with ${inserted.length} line${inserted.length === 1 ? '' : 's'}.`;
+    }
+
+
+    // ---- SUBSTRING mode (old_string -> new_string) --------------------------
+    let { old_string, new_string, replace_all = false } = args;
+    if (old_string === '' || old_string == null) return `Error: old_string must not be empty.`;
 
     // --- Newline normalization (Windows CRLF) ---
     // The Read tool normalizes \r\n -> \n, so an agent builds old_string/new_string
@@ -96,6 +155,14 @@ export const spec = {
       }
     }
     const occurrences = replace_all ? count : 1;
+    // Publish the diff for the UI (same contract as the line-range path above).
+    if (ctx) {
+      const startLine = (() => {
+        const at = normContent.split('\n').indexOf(String(normOld).split('\n')[0]);
+        return at >= 0 ? at + 1 : 1;
+      })();
+      ctx.lastEditDiff = { old: normalizeText(old_string), new: normalizeText(new_string), startLine };
+    }
     return `Edited ${args.path}: replaced ${occurrences} occurrence(s).`;
   },
 };
@@ -135,4 +202,48 @@ function checkStale(p, normContent, normOld, ctx) {
   // (3) The file changed on disk since it was Read and the edit target is not in
   //     an intact Read region. Reject so a stale snippet cannot corrupt the file.
   return `Edit rejected: ${p} changed since it was Read (the edited region is not in an intact Read snapshot). Re-run Read to get the current content, then Edit.`;
-}
+}
+// ---- helpers for the line-range path ---------------------------------------
+
+// Same guarantee as checkStale, but for an explicit [start, end] line range:
+// every line in the range must sit inside a region that was Read this turn and
+// whose content still matches. Returns an error string, or null when safe.
+function checkStaleRange(p, curLines, start, end, ctx) {
+  if (!ctx || !ctx.readPool) return null; // no Read happened; nothing to verify
+  const entry = ctx.readPool.get(p);
+  if (!entry) return null;                // never Read this turn; allow
+
+  const normContent = curLines.join('\n');
+  const curFileHash = hashStr(normContent);
+
+  // A region covers the range when it fully contains it AND still hashes the
+  // same as when it was Read.
+  const covered = entry.regions.some(
+    (r) => start >= r.start && end <= r.end && hashLines(curLines, r.start, r.end) === r.hash,
+  );
+  if (covered) return null;
+
+  if (curFileHash === entry.fileHash) {
+    // No "(read so far: …)" listing: the range is what the model must act on, and
+    // echoing the regions it HAS read only invited it to reason about them instead
+    // of re-reading the target lines.
+    return `Edit rejected: lines ${start}-${end} were not read in ${p}. Read the target lines first (Read with line_offset / n_lines), then Edit.`;
+  }
+  return `Edit rejected: ${p} changed since it was Read (lines ${start}-${end} are not in an intact Read snapshot). Re-run Read to get the current content, then Edit.`;
+}
+
+// Refresh the region cache after a successful edit: drop regions that no longer
+// match the NEW content, and record the freshly-written span. Mirrors the
+// re-arm block used by the substring path.
+function refreshReadPool(p, normUpdated, written, ctx) {
+  if (!ctx || !ctx.readPool) return;
+  const entry = ctx.readPool.get(p);
+  if (!entry) return;
+  const newLines = normUpdated.split('\n');
+  entry.fileHash = hashStr(normUpdated);
+  entry.lines = newLines.length;
+  const kept = entry.regions.filter((r) => hashLines(newLines, r.start, r.end) === r.hash);
+  kept.push({ start: written.start, end: Math.min(newLines.length, Math.max(written.start, written.end)), hash: hashLines(newLines, written.start, Math.min(newLines.length, Math.max(written.start, written.end))) });
+  entry.regions = kept;
+  try { const st = fs.statSync(p); entry.size = st.size; entry.mtimeMs = st.mtimeMs; } catch {}
+}

package/src/tools/file-lines.js

@@ -24,13 +24,46 @@ export const spec = {
     const stat = fs.statSync(p);
     if (!stat.isFile()) return `Error: not a file: ${args.path}`;
 
-    // Count LINES only — never the content. Splitting on the same newline forms
-    // Read normalizes keeps the count consistent with Read's own total.
-    const lines = fs.readFileSync(p, 'utf8').split(/\r\n|\r|\n/);
-    // A file ending in a newline splits with a trailing '' element; that is the
-    // terminator of the previous line, not a line of its own.
-    if (lines.length > 1 && lines[lines.length - 1] === '') lines.pop();
-
-    return `Lines: ${lines.length}`;
+    // Count LINES only — never the content. Read the file in bounded chunks and
+    // count newlines, so a huge file is not pulled wholesale into memory just to
+    // answer "how many lines". Any of \r\n, \r, or \n counts as one line break,
+    // matching the newline forms Read normalizes.
+    let fd;
+    try { fd = fs.openSync(p, 'r'); } catch { return `Error: cannot open ${args.path}`; }
+    const CHUNK = 256 * 1024;
+    const buf = Buffer.allocUnsafe(CHUNK);
+    let lineBreaks = 0;                // count of \r\n, \r, or \n sequences
+    let prevCR = false;
+    let lastWasBreak = false;          // whether the last byte seen was a line break
+    let read = 0;
+    try {
+      for (;;) {
+        const n = fs.readSync(fd, buf, 0, CHUNK, read);
+        if (n <= 0) break;
+        for (let i = 0; i < n; i++) {
+          const b = buf[i];
+          if (b === 0x0a) {           // \n
+            if (!prevCR) lineBreaks++;
+            prevCR = false;
+            lastWasBreak = true;
+          } else if (b === 0x0d) {    // \r
+            lineBreaks++;
+            prevCR = true;
+            lastWasBreak = true;
+          } else {
+            prevCR = false;
+            lastWasBreak = false;
+          }
+        }
+        if (n < CHUNK) break;
+        read += n;
+      }
+    } finally {
+      try { fs.closeSync(fd); } catch {}
+    }
+    // "a\nb\nc" is 3 lines; "a\nb\nc\n" is also 3 (the trailing \n terminates
+    // the last line, it does not open a new one). So drop the final break.
+    const lines = 1 + lineBreaks - (lastWasBreak ? 1 : 0);
+    return `Lines: ${Math.max(1, lines)}`;
   },
 };

package/src/tools/glob.js

@@ -6,7 +6,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { normalizeInput } from './utils.js';
 import { walkFiles } from './ignore.js';
-import { globRegex, expandBraces } from './matchers.js';
+import { globToRegexSource, expandBraces } from './matchers.js';
 
 export const spec = {
   name: 'Glob',
@@ -22,17 +22,29 @@ export const spec = {
     required: ['pattern'],
   },
   async execute(args, ctx) {
-    const fromDir = args.path ? args.path : '.';
+    // `pattern` is required, but the model can still omit it. Return an error
+    // string like every other tool instead of throwing — an uncaught throw here
+    // aborts the whole turn.
+    if (typeof args.pattern !== 'string' || !args.pattern.trim()) {
+      return 'Error: `pattern` is required (e.g. "src/**/*.ts").';
+    }
+    const fromDir = typeof args.path === 'string' && args.path ? args.path : '.';
     const p = normalizeInput(fromDir);
     let base;
     try { base = path.resolve(ctx.cwd || ctx.workspace, p); } catch (e) { return `Error: ${e.message}`; }
     if (!fs.existsSync(base)) return `Error: path does not exist: ${fromDir}`;
     if (!fs.statSync(base).isDirectory()) return `Error: --path is not a directory: ${fromDir}`;
 
-    const alts = expandBraces(args.pattern);
-    const re = new RegExp('^(?:' + alts.map((a) => globRegex(a).source.slice(1, -1)).join('|') + ')$');
+const alts = expandBraces(args.pattern);
+    // Each alt is already anchored (globToRegexSource includes ^ and $), so
+    // join them into one anchored alternation. The previous code inferred the
+    // anchors by slicing the first/last char off globRegex(), which was fragile:
+    // a brace pattern has per-alt anchors that slicing stripped into the wrong
+    // shape.
+    const re = new RegExp('^(?:' + alts.map((a) => globToRegexSource(a)).join('|') + ')$');
+
 
-    const files = walkFiles(base, { includeIgnored: !!args.include_ignored, includeDirs: false });
+    const files = walkFiles(base, { includeIgnored: !!args.include_ignored, includeDirs: !!args.include_dirs });
     const matches = [];
     for (const abs of files) {
       const rel = path.relative(base, abs).split(path.sep).join('/');

package/src/tools/grep.js

@@ -42,8 +42,14 @@ export const spec = {
 };
 
 function hasRg() {
-  try { cp.spawnSync('rg', ['--version'], { stdio: 'ignore' }); return true; }
-  catch { return false; }
+  try {
+    // spawnSync does NOT throw when the binary is missing — it returns
+    // { error: ENOENT, status: null }. The old try/catch therefore always
+    // reported "rg available", and grepRg() then returned an empty stdout as
+    // "No matches found" instead of falling back to the JS walker.
+    const r = cp.spawnSync('rg', ['--version'], { stdio: 'ignore' });
+    return !r.error && r.status === 0;
+  } catch { return false; }
 }
 
 function buildRgArgs(args, base) {
@@ -70,10 +76,13 @@ function grepRg(args, base, ctx) {
       maxBuffer: 64 * 1024 * 1024,
       encoding: 'utf8',
     });
+    // spawn failure: `r.error` set, status null. Must fall back to JS, not
+    // return an empty result as "No matches found".
+    if (r.error) return grepJs(args, base, ctx);
     out = r.stdout || '';
     if (r.status > 1 && r.stderr) return `rg error: ${r.stderr.trim()}`;
   } catch (e) {
-    return `rg unavailable: ${e.message}; falling back`;
+    return grepJs(args, base, ctx);
   }
   return paginate(out, args);
 }
@@ -118,6 +127,10 @@ function grepJs(args, base, ctx) {
       const lines = txt.split('\n');
       let count = 0;
       for (let i = 0; i < lines.length; i++) {
+        // `re` carries the `g` flag, so RegExp.test() advances lastIndex and
+        // the NEXT call starts mid-string — every other matching line was
+        // skipped. Reset lastIndex before each test.
+        re.lastIndex = 0;
         if (re.test(lines[i])) {
           count++;
           if (mode === 'files_with_matches') { out.push(abs); break; }

package/src/tools/index.js

@@ -12,6 +12,9 @@ import * as fetchUrlMod from './fetch-url.js';
 import * as webSearchMod from './web-search.js';
 import * as readMediaFileMod from './read-media-file.js';
 import * as fileLinesMod from './file-lines.js';
+import * as askUserQuestionMod from './ask-user-question.js';
+import { spec as agentSpec } from './agent.js';
+import { spec as agentSwarmSpec } from './agent-swarm.js';
 import { TaskListSpec, TaskOutputSpec, TaskStopSpec, TaskWaitSpec } from './tasks.js';
 import { pluginTools } from '../plugin.js';
 
@@ -28,6 +31,9 @@ const builtinTools = [
   webSearchMod.spec,
   readMediaFileMod.spec,
   fileLinesMod.spec,
+  askUserQuestionMod.spec,
+  agentSpec,
+  agentSwarmSpec,
   TaskListSpec,
   TaskOutputSpec,
   TaskStopSpec,
@@ -44,8 +50,19 @@ export function combinedTools() {
 export const tools = builtinTools;
 export { builtinTools };
 
-const byName = new Map(builtinTools.map((t) => [t.name, t]));
-export function getTool(name) { return byName.get(name); }
+// NOTE: the map is built lazily over combinedTools() so plugin-registered
+// tools are resolvable. The previous Map was built from builtinTools only,
+// so `llmTools()` advertised a plugin tool to the model but `getTool(name)`
+// returned undefined and the call failed with `unknown tool`.
+let _byName = null;
+function byNameMap() {
+  if (!_byName) {
+    _byName = new Map();
+    for (const t of combinedTools()) if (!_byName.has(t.name)) _byName.set(t.name, t);
+  }
+  return _byName;
+}
+export function getTool(name) { return byNameMap().get(name); }
 export function toolNames() { return combinedTools().map((t) => t.name); }
 
 // Schemas for sending to an LLM (OpenAI `tools` array).

package/src/tools/matchers.js

@@ -1,71 +1,75 @@
-// Shared glob matching used by Glob, Grep and the .gitignore matcher.
-// Semantics: `*` matches within a path segment; `**` (optionally followed by `/`)
-// matches across segments; `?` matches one non-separator char; `[class]` char
-// classes; `{a,b}` brace expansion. `/` is the path separator used for matching.
-
-export function expandBraces(str) {
-  const i = str.indexOf('{');
-  if (i === -1) return [str];
-  let depth = 1, j = i + 1, parts = [], part = '', ok = false;
-  while (j < str.length && depth > 0) {
-    const c = str[j];
-    if (c === '{') { depth++; part += c; }
-    else if (c === '}') { depth--; if (depth === 0) { parts.push(part); ok = true; break; } else part += c; }
-    else if (c === ',' && depth === 1) { parts.push(part); part = ''; }
-    else part += c;
-    j++;
-  }
-  if (!ok) return [str];
-  const out = [];
-  const before = str.slice(0, i), after = str.slice(j + 1);
-  for (const p of parts) {
-    for (const b of expandBraces(before)) for (const pp of expandBraces(p)) for (const a of expandBraces(after)) out.push(b + pp + a);
-  }
-  return out;
-}
-
-function escapeRegex(c) {
-  return /[.*+?^${}()|[\]\\]/.test(c) ? '\\' + c : c;
-}
-
-export function globToRegexSource(pattern) {
-  let src = '^';
-  for (let i = 0; i < pattern.length; i++) {
-    const c = pattern[i];
-    if (c === '*' && pattern[i + 1] === '*') {
-      src += '[\\s\\S]*'; i++;
-      if (pattern[i + 1] === '/') i++;
-    } else if (c === '*') {
-      src += '[^/]*';
-    } else if (c === '?') {
-      src += '[^/]';
-    } else if (c === '[') {
-      let j = i + 1, negated = false;
-      if (pattern[j] === '!' || pattern[j] === '^') { negated = true; j++; }
-      let body = '';
-      while (j < pattern.length && pattern[j] !== ']') body += pattern[j++];
-      if (pattern[j] === ']') {
-        if (negated) body = '/' + body;
-        src += negated ? '[^' + body + ']' : '[' + body + ']';
-        i = j;
-      } else {
-        src += escapeRegex(c);
-      }
-    } else {
-      src += escapeRegex(c);
-    }
-  }
-  return src + '$';
-}
-
-// Match the whole string against a single pattern (anchored, like globToRegex).
-export function globRegex(pattern) {
-  const alts = expandBraces(pattern);
-  if (alts.length === 1) return new RegExp('^' + globToRegexSource(alts[0]));
-  return new RegExp('^(?:' + alts.map(globToRegexSource).join('|') + ')');
-}
-
-// True if `s` matches `pattern` (full match on `s`).
-export function matchGlob(pattern, s) {
-  return globRegex(pattern).test(s);
-}
+// Shared glob matching used by Glob, Grep and the .gitignore matcher.
+// Semantics: `*` matches within a path segment; `**` (optionally followed by `/`)
+// matches across segments; `?` matches one non-separator char; `[class]` char
+// classes; `{a,b}` brace expansion. `/` is the path separator used for matching.
+
+export function expandBraces(str) {
+  const i = str.indexOf('{');
+  if (i === -1) return [str];
+  let depth = 1, j = i + 1, parts = [], part = '', ok = false;
+  while (j < str.length && depth > 0) {
+    const c = str[j];
+    if (c === '{') { depth++; part += c; }
+    else if (c === '}') { depth--; if (depth === 0) { parts.push(part); ok = true; break; } else part += c; }
+    else if (c === ',' && depth === 1) { parts.push(part); part = ''; }
+    else part += c;
+    j++;
+  }
+  if (!ok) return [str];
+  const out = [];
+  const before = str.slice(0, i), after = str.slice(j + 1);
+  for (const p of parts) {
+    for (const b of expandBraces(before)) for (const pp of expandBraces(p)) for (const a of expandBraces(after)) out.push(b + pp + a);
+  }
+  return out;
+}
+
+function escapeRegex(c) {
+  return /[.*+?^${}()|[\]\\]/.test(c) ? '\\' + c : c;
+}
+
+// Regex SOURCE (anchored, with ^ and $) for a single plain pattern.
+export function globToRegexSource(pattern) {
+  let src = '^';
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern[i];
+    if (c === '*' && pattern[i + 1] === '*') {
+      src += '[\\s\\S]*'; i++;
+      if (pattern[i + 1] === '/') i++;
+    } else if (c === '*') {
+      src += '[^/]*';
+    } else if (c === '?') {
+      src += '[^/]';
+    } else if (c === '[') {
+      let j = i + 1, negated = false;
+      if (pattern[j] === '!' || pattern[j] === '^') { negated = true; j++; }
+      let body = '';
+      while (j < pattern.length && pattern[j] !== ']') body += pattern[j++];
+      if (pattern[j] === ']') {
+        if (negated) body = '/' + body;
+        src += negated ? '[^' + body + ']' : '[' + body + ']';
+        i = j;
+      } else {
+        src += escapeRegex(c);
+      }
+    } else {
+      src += escapeRegex(c);
+    }
+  }
+  return src + '$';
+}
+
+// Match the whole string against a single pattern (anchored, like globToRegex).
+// The single-alternative path wraps globToRegexSource directly; the multi
+// (brace) path joins every alternative in braces so a `{a,b}` pattern cannot
+// match a substring that only matches one branch.
+export function globRegex(pattern) {
+  const alts = expandBraces(pattern);
+  if (alts.length === 1) return new RegExp(globToRegexSource(alts[0]));
+  return new RegExp('^(?:' + alts.map((a) => globToRegexSource(a)).join('|') + ')$');
+}
+
+// True if `s` matches `pattern` (full match on `s`).
+export function matchGlob(pattern, s) {
+  return globRegex(pattern).test(s);
+}

package/src/tools/read-media-file.js

@@ -36,15 +36,29 @@ export const spec = {
       if (stat.size > MAX_IMAGE_SIZE) {
         return `Error: image too large (${(stat.size / 1024 / 1024).toFixed(1)}MB, max 20MB): ${args.path}`;
       }
-      const data = fs.readFileSync(p);
-      const base64 = data.toString('base64');
+      // A tool result is plain TEXT that goes back into the model's context on
+      // the next request. A 20MB image becomes ~27MB of base64, which blows the
+      // context window and (for OpenAI/Anthropic chat completions) is not a
+      // recognised image payload anyway — the model only sees a wall of text.
+      // Return a REFERENCE the caller can act on instead of the bytes.
       const mimeType = ext === '.jpg' || ext === '.jpeg' ? 'image/jpeg'
         : ext === '.png' ? 'image/png'
         : ext === '.gif' ? 'image/gif'
         : ext === '.webp' ? 'image/webp'
         : ext === '.bmp' ? 'image/bmp'
         : 'image/unknown';
-      return `data:${mimeType};base64,${base64}`;
+      const sizeKB = Math.max(1, Math.round(stat.size / 1024));
+      const abs = p.replace(/\\/g, '/');
+      // Keep a small inline preview ONLY for tiny files (< 64KB), where the
+      // base64 is at most ~87KB and genuinely usable by a multimodal client.
+      if (stat.size <= 64 * 1024) {
+        const base64 = fs.readFileSync(p).toString('base64');
+        return `data:${mimeType};base64,${base64}`;
+      }
+      return `[Image: ${mimeType}] ${args.path} (${sizeKB}KB, ${stat.width || '?'}x${stat.height || '?'} unknown)\n`
+        + `Path: ${abs}\n`
+        + `This image is too large to inline as base64 (would be ~${Math.round(stat.size * 4 / 3 / 1024)}KB of text). `
+        + `To view it, use a client that renders image paths, or resize it first.`;
     }
     
     const fileType = VIDEO_EXT.includes(ext) ? 'video' : AUDIO_EXT.includes(ext) ? 'audio' : 'unknown';

package/src/tools/read.js

@@ -22,6 +22,8 @@ function hashLines(lines, start, end) {
   const slice = (lines.slice(start - 1, end) || []).join('\n');
   return hashStr(slice);
 }
+// Public alias so edit.js (and the line-range path) share ONE implementation.
+export const hashRegion = hashLines;
 
 export const spec = {
   name: 'Read',