@hncode/hncode 0.3.6 → 0.4.0

package/src/tools/edit.js

@@ -3,9 +3,24 @@
 // so edits stay token-cheap (unlike kimi-code-cli's whole-file Edit).
 
 import fs from 'node:fs';
-import { resolvePath, ensureDir } from './utils.js';
+import path from 'node:path';
+import { resolvePath, ensureDir, checkpointBeforeWrite } from './utils.js';
 import { hashStr, normalizeText } from './read.js';
 
+// Typographic quotes -> straight quotes. A model almost always emits ASCII
+// quotes, but docs/blog/markdown often use curly ones; without this the edit
+// fails with "old_string not found" even though the text is visibly there.
+// Mirrors Claude Code's normalizeQuotes.
+const CURLY = [
+  ['\u2018', "'"], ['\u2019', "'"],   // ‘ ’
+  ['\u201c', '"'], ['\u201d', '"'],   // “ ”
+];
+export function normalizeQuotes(s) {
+  let out = String(s);
+  for (const [from, to] of CURLY) out = out.split(from).join(to);
+  return out;
+}
+
 // 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.
@@ -13,39 +28,61 @@ import { hashRegion as hashLines } from './read.js';
 
 export const spec = {
   name: 'Edit',
-  description: 'Edit a file. THE TWO MODES ARE MUTUALLY EXCLUSIVE — NEVER combine them:\n  - LINE-RANGE mode: path + start_line + end_line + new_content. Replaces lines [start_line, end_line] with new_content. PREFERRED — use it whenever you have Read the file and know the line numbers.\n  - EXACT-SUBSTRING mode: path + old_string + new_string. Replaces text exactly matching old_string. Use ONLY when the exact text is known and a line range is not convenient.\nDo NOT pass start_line/end_line together with old_string/new_string in one call, and do NOT pass any of these four keys when you are not using that mode. Omitting new_content or new_string is an error, not an empty replacement.',
+  description: 'Edit a file. THE TWO MODES ARE MUTUALLY EXCLUSIVE — NEVER combine them:\n  - LINE-RANGE mode: path + start_line + end_line + new_string. Replaces lines [start_line, end_line] with new_string. PRESERVE the exact indentation (spaces/tabs) of the lines you are replacing — copy it straight from the Read output, after its line-number prefix. PREFERRED — use it whenever you have Read the file and know the line numbers.\n  - EXACT-SUBSTRING mode: path + old_string + new_string. Replaces text exactly matching old_string. Use ONLY when the exact text is known and a line range is not convenient.\nDo NOT pass start_line/end_line together with old_string/new_string in one call, and do NOT pass any of these four keys when you are not using that mode. Omitting new_string is an error, not an empty replacement (in line-range mode pass new_string; in substring mode pass old_string + new_string).',
   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. Omit when using start_line/end_line.' },
-      new_string: { type: 'string', description: 'Replacement text for old_string.' },
+      new_string: { type: 'string', description: 'Replacement text. In SUBSTRING mode it replaces old_string. In LINE-RANGE mode it replaces lines [start_line, end_line]. In line-range mode PRESERVE the exact leading whitespace (indentation) from Read output; copy it exactly as it appears after the line-number prefix.' },
       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.' },
+      start_line: { type: 'integer', minimum: 1, description: 'PREFERRED MODE. 1-based first line to replace (requires end_line and new_string). 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.' },
     },
-    // Either line-range mode (start_line+end_line+new_content) OR exact-substring
+    // Either line-range mode (start_line+end_line+new_string) OR exact-substring
     // mode (old_string+new_string).
     // Line-range is the preferred route.
     anyOf: [
-      { required: ['path', 'start_line', 'end_line', 'new_content'] },
+      { required: ['path', 'start_line', 'end_line', 'new_string'] },
       { required: ['path', 'old_string', 'new_string'] },
     ],
   },
   async execute(args, ctx) {
+    // Validate BEFORE resolving the path. `resolvePath(undefined)` resolves to the
+    // workspace root rather than failing, so a truncated tool call (agent.js falls
+    // back to `{ raw, _rawLen }` when the streamed JSON will not parse) could
+    // target a DIRECTORY and produce a confusing EISDIR/ENOENT instead of "retry
+    // the call".
+    if (typeof args.path !== 'string' || !args.path.trim()) {
+      const truncated = args && args.raw
+        ? ` The arguments did not parse as JSON${args._rawLen ? ` (${args._rawLen} characters received)` : ''} — the call was most likely truncated. Retry, and keep \`old_string\` / \`new_string\` small (edit in several passes rather than one large replacement).`
+        : '';
+      return `Error: \`path\` is required and must be a non-empty string.${truncated}`;
+    }
     let p;
     try { p = resolvePath(args.path, ctx); } catch (e) { return e.message; }
+    // A Jupyter notebook is JSON, not text: a snippet edit corrupts it. Point the
+    // model at the notebook-aware path instead (mirrors Claude Code errorCode 5).
+    if (String(p).toLowerCase().endsWith('.ipynb')) {
+      return `Error: ${args.path} is a Jupyter notebook. Its .ipynb is JSON — edit the cells through a notebook-aware tool (or edit the JSON carefully), not a plain text Edit.`;
+    }
     let content;
-    try { content = fs.readFileSync(p, 'utf8'); } catch (e) { return `Error reading ${args.path}: ${e.message}`; }
-    const { start_line, end_line, new_content } = args;
+    try {
+      content = fs.readFileSync(p, 'utf8');
+    } catch (e) {
+      if (e && e.code === 'ENOENT') {
+        return `Error reading ${args.path}: file does not exist.${similarFileHint(p)}`;
+      }
+      return `Error reading ${args.path}: ${e.message}`;
+    }
+    const { start_line, end_line } = args;
     // The two modes are MUTUALLY EXCLUSIVE: sending line-range AND substring
     // parameters together is ambiguous — reject it rather than guessing which
     // one the caller meant. Only one family may be present in `args`.
-    const hasRangeKeys = args.start_line != null || args.end_line != null || args.new_content != null;
-    const hasSubKeys = args.old_string != null || args.new_string != null;
+    const hasRangeKeys = args.start_line != null || args.end_line != null;
+    const hasSubKeys = args.old_string != null;
     if (hasRangeKeys && hasSubKeys) {
-      return `Error: do not mix line-range mode and substring mode. Use EITHER (start_line/end_line/new_content) OR (old_string/new_string), never both.`;
+      return `Error: do not mix line-range mode and substring mode. Use EITHER (start_line/end_line/new_string) OR (old_string/new_string), never both.`;
     }
 
     // ---- LINE-RANGE mode ---------------------------------------------------
@@ -54,10 +91,21 @@ export const spec = {
     // 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.
+    // ONE bound without the other is its own mistake and an easy one to make: the
+    // call then falls past this block and reports a missing old_string, which
+    // sends the model looking in the wrong place.
+    if ((start_line != null) !== (end_line != null)) {
+      return 'Error: line-range mode needs BOTH start_line and end_line.';
+    }
     if (start_line != null && end_line != null) {
-      // Neither start/end alone is a valid range, and new_content is required —
-      // a missing one would put the literal string "undefined" in the file.
-      if (new_content == null) return `Error: new_content is required for line-range mode.`;
+      // Accept both spellings so old new_content callers keep working.
+      const new_string = args.new_string != null ? args.new_string : args.new_content;
+      // new_string is required — a missing one would put the literal string
+      // "undefined" in the file.
+      if (new_string == null) return `Error: new_string is required for line-range mode (pass an empty string to delete the lines).`;
+      if (typeof new_string !== 'string') {
+        return `Error: new_string must be a string (got ${new_string === null ? 'null' : typeof new_string}).`;
+      }
       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).`;
@@ -73,16 +121,18 @@ export const spec = {
       const stale = checkStaleRange(p, lines, start, end, ctx);
       if (stale) return stale;
 
-      const inserted = normalizeText(new_content).split('\n');
+      const inserted = normalizeText(new_string).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`.
+      // the caller diff the replaced region -> `new_string`.
       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;
+      // Checkpoint the pre-edit content so /undo can put it back (file-history.js).
+      checkpointBeforeWrite(p, ctx);
       try {
         ensureDir(p);
         fs.writeFileSync(p, updated, 'utf8');
@@ -93,13 +143,20 @@ export const spec = {
       // 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 };
+      if (ctx) ctx.lastEditDiff = { old: replacedText, new: normalizeText(new_string), 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;
+    // Reaching here means neither mode was usable: line-range needs
+    // start_line+end_line (handled above) and substring needs old_string. When
+    // BOTH are absent, say so — "old_string must not be empty" sends the model
+    // hunting for a stray empty string it never sent.
+    if (old_string == null && new_string == null) {
+      return 'Error: no edit mode given. Pass EITHER (start_line, end_line, new_string) OR (old_string, new_string).';
+    }
     if (old_string === '' || old_string == null) return `Error: old_string must not be empty.`;
     if (new_string == null) return `Error: new_string is required for substring mode.`;
 
@@ -113,8 +170,32 @@ export const spec = {
     const normOld = normalizeText(old_string);
     const normNew = normalizeText(new_string);
 
-    const count = normContent.split(normOld).length - 1;
-    if (count === 0) return `Error: old_string not found in ${args.path}.`;
+    let matchOld = normOld;    // the string that will actually be matched/replaced
+    let matchNew = normNew;
+    let count = normContent.split(matchOld).length - 1;
+    if (count === 0) {
+      // Quote-normalized retry: the file may use curly quotes while the model sent
+      // straight ones. Match on the normalized forms, then replace the ACTUAL
+      // substring found in the file so typography is preserved.
+      // Quote-normalized retry: the file may use curly quotes while the model sent
+      // straight ones. Match on the normalized forms, then replace the ACTUAL
+      // substring found in the file so typography is preserved. normalizeQuotes is
+      // 1 char -> 1 char, so indices line up between the two strings.
+      const normFileQ = normalizeQuotes(normContent);
+      if (normFileQ !== normContent) {
+        const normOldQ = normalizeQuotes(normOld);
+        const idx = normFileQ.indexOf(normOldQ);
+        if (idx >= 0) {
+          matchOld = normContent.slice(idx, idx + normOldQ.length);
+          matchNew = normNew;   // keep the model's new_string as written
+          count = normContent.split(matchOld).length - 1;
+        }
+      }
+    }
+    if (count === 0) {
+      const near = nearestLineHint(normContent, normOld);
+      return `Error: old_string not found in ${args.path}.${near}`;
+    }
     if (count > 1 && !replace_all) {
       return `Error: old_string matched ${count} occurrences in ${args.path}. Use replace_all=true or make old_string unique.`;
     }
@@ -123,13 +204,15 @@ export const spec = {
     // We stored per-region + whole-file hashes in ctx.readPool when Read ran.
     // If the file changed on disk since (external edit, stream, Ctrl-C side
     // effect), reject so a snippet edit cannot silently corrupt the file. ---
-    const stale = checkStale(p, normContent, normOld, ctx);
+    const stale = checkStale(p, normContent, matchOld, ctx);
     if (stale) return stale;
 
     const normUpdated = replace_all
-      ? normContent.replaceAll(normOld, normNew)
-      : normContent.replace(normOld, normNew);
+      ? normContent.replaceAll(matchOld, matchNew)
+      : normContent.replace(matchOld, matchNew);
     const updated = eol === '\r\n' ? normUpdated.split('\n').join('\r\n') : normUpdated;
+    // Checkpoint the pre-edit content so /undo can put it back (file-history.js).
+    checkpointBeforeWrite(p, ctx);
     try {
       ensureDir(p);
       fs.writeFileSync(p, updated, 'utf8');
@@ -147,11 +230,11 @@ export const spec = {
         entry.lines = newLines.length;
         // Locate the edit site in the NEW content: the first line of the new
         // text if present, else fall back to the old target's location.
-        const anchor = String(normNew).split('\n')[0];
+        const anchor = String(matchNew).split('\n')[0];
         let at = newLines.indexOf(anchor);
-        if (at < 0) at = newLines.indexOf(String(normOld).split('\n')[0]);
+        if (at < 0) at = newLines.indexOf(String(matchOld).split('\n')[0]);
         if (at >= 0) {
-          const newSpan = String(normNew).split('\n').length;
+          const newSpan = String(matchNew).split('\n').length;
           const start = at + 1;
           const end = Math.min(newLines.length, at + Math.max(1, newSpan));
           // Re-hash every surviving old region against the new content, and add
@@ -179,6 +262,73 @@ export const spec = {
   },
 };
 
+// Suggest a near-miss filename when a path does not exist: same directory, an
+// exact case-insensitive match, same stem with a different extension, or a
+// prefix match. Saves the model a round-trip of guessing (Claude Code's
+// "Did you mean X?").
+function similarFileHint(missingPath) {
+  const dir = path.dirname(missingPath);
+  const base = path.basename(missingPath);
+  const stem = base.replace(/\.[^.]*$/, '').toLowerCase();
+  let entries;
+  try { entries = fs.readdirSync(dir); } catch { return ''; }
+  const lower = base.toLowerCase();
+  // Levenshtein distance, capped — enough to catch a typo (confg -> config).
+  const lev = (a, b) => {
+    const m = a.length, n = b.length;
+    if (Math.abs(m - n) > 2) return 3;
+    let prev = Array.from({ length: n + 1 }, (_, j) => j);
+    for (let i = 1; i <= m; i++) {
+      const cur = [i];
+      for (let j = 1; j <= n; j++) {
+        cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+      }
+      prev = cur;
+    }
+    return prev[n];
+  };
+  let cand = entries.find((e) => e.toLowerCase() === lower);
+  if (!cand) {
+    let best = null, bestD = 3;
+    for (const e of entries) {
+      const d = lev(stem, e.replace(/\.[^.]*$/, '').toLowerCase());
+      if (d < bestD) { bestD = d; best = e; }
+    }
+    cand = best;
+  }
+  if (cand && cand !== base) return ` Did you mean "${path.join(dir, cand)}"?`;
+  return '';
+}
+
+// When old_string is not found, look for the closest line in the file and name
+// it, so the model can see what the text actually is instead of guessing.
+function nearestLineHint(content, oldStr) {
+  const want = String(oldStr).split('\n')[0].trim();
+  if (!want || want.length < 3) return '';
+  const lines = String(content).split('\n');
+  // Character bigrams: robust to small differences and cheap on long lines.
+  const grams = (s) => {
+    const set = new Set();
+    for (let i = 0; i + 1 < s.length; i++) set.add(s.slice(i, i + 2));
+    return set;
+  };
+  const wantGrams = grams(want);
+  if (!wantGrams.size) return '';
+  let best = -1, bestScore = 0;
+  for (let i = 0; i < lines.length; i++) {
+    const g = grams(lines[i].trim());
+    if (!g.size) continue;
+    let hit = 0;
+    for (const t of wantGrams) if (g.has(t)) hit++;
+    const score = hit / wantGrams.size;
+    if (score > bestScore) { bestScore = score; best = i; }
+  }
+  if (best >= 0 && bestScore >= 0.5) {
+    return ` The closest line is line ${best + 1}: ${JSON.stringify(lines[best].trim().slice(0, 120))}`;
+  }
+  return '';
+}
+
 // Returns an error message when the edit is stale, else null (safe to edit).
 function checkStale(p, normContent, normOld, ctx) {
   if (!ctx || !ctx.readPool) return null; // no Read happened; nothing to verify
@@ -205,15 +355,25 @@ function checkStale(p, normContent, normOld, ctx) {
   }
 
   // (2) Whole file unchanged since Read, but the edit target was never Read
-  //     (no region covers it). Tell the AI to read the target lines first.
+  //     (no region covers it). Name the exact lines so the model reads the right
+  //     window instead of guessing.
   if (curFileHash === entry.fileHash) {
-    const ranges = entry.regions.map((r) => `${r.start}-${r.end}`).join(', ') || 'none';
-    return `Edit rejected: you have not read the lines you are editing in ${p}. Read the target lines first (Read with line_offset / n_lines), then Edit.`;
+    const span = String(normOld).split('\n').length;
+    const at = editLine > 0 ? editLine : 1;
+    return `Edit rejected: you have not read the lines you are editing in ${p}. The target is around line ${at} (${span} line${span === 1 ? '' : 's'}). Read it first — ${args_readHint(p, at, span)} — then Edit.`;
   }
 
   // (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.`;
+  const at3 = editLine > 0 ? ` (target line ${editLine})` : '';
+  return `Edit rejected: ${p} changed since it was Read${at3}, and the edited region is not in an intact Read snapshot. Re-run ${args_readHint(p, editLine > 0 ? editLine : 1, String(normOld).split('\n').length)} to get the current content, then Edit.`;
+}
+
+// A ready-to-use Read call for the hint. Keeps the model from guessing line ranges.
+function args_readHint(p, at, span) {
+  const from = Math.max(1, at - 3);
+  const n = Math.max(span + 6, 10);
+  return `Read { path: ${JSON.stringify(p)}, line_offset: ${from}, n_lines: ${n} }`;
 }
 // ---- helpers for the line-range path ---------------------------------------
 
@@ -239,9 +399,9 @@ function checkStaleRange(p, curLines, start, end, ctx) {
     // 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: lines ${start}-${end} were not read in ${p}. Read them first — ${args_readHint(p, start, end - start + 1)} — 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.`;
+  return `Edit rejected: ${p} changed since it was Read (lines ${start}-${end} are not in an intact Read snapshot). Re-run ${args_readHint(p, start, end - start + 1)} to get the current content, then Edit.`;
 }
 
 // Refresh the region cache after a successful edit: drop regions that no longer

package/src/tools/file-lines.js

@@ -16,6 +16,11 @@ export const spec = {
     required: ['path'],
   },
   async execute(args, ctx) {
+    // See read.js: a missing path reaches resolvePath(undefined), which resolves to
+    // the workspace root rather than failing.
+    if (typeof args.path !== 'string' || !args.path.trim()) {
+      return 'Error: `path` is required and must be a non-empty string.';
+    }
     let p;
     try { p = resolvePath(args.path, ctx); } catch (e) { return e.message; }
 

package/src/tools/index.js

@@ -17,8 +17,10 @@ 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 * as memoryMod from './memory.js';
 import { pluginTools } from '../plugin.js';
 
+
 // Built-in tools.
 const builtinTools = [
   readMod.spec,
@@ -40,8 +42,10 @@ const builtinTools = [
   TaskOutputSpec,
   TaskStopSpec,
   TaskWaitSpec,
+  memoryMod.spec,
 ];
 
+
 // Combined list: built-ins + plugin-registered tools. Plugin tools appear after
 // built-ins so their names are visible, but built-in names take precedence in
 // the byName lookup (first one wins).

package/src/tools/memory.js

@@ -0,0 +1,88 @@
+// Memory tool — the agent records a durable note for FUTURE sessions.
+//
+// Distinct from /personal: that file is the USER's standing preferences and the
+// agent must never write it. This tool writes MEMORY.md, which is the agent's own
+// scratchpad, injected into the system prompt on later turns (see config.js's
+// readMemory). The point is to stop rediscovering the same facts every session —
+// build quirks, a command that works here, a decision the user already made.
+
+import { appendMemory, readMemoryRaw, memoryFile } from '../config.js';
+
+export const spec = {
+  name: 'Memory',
+  description: `Save a durable note for FUTURE sessions, or list what is already saved.
+
+Use it when you learn something that will still be true next week and that you would
+otherwise have to rediscover: a build/test command that works in this repo, a layout
+quirk, a convention the user asked for, a decision they already made, a gotcha that
+cost you a debugging cycle.
+
+Do NOT use it for:
+- things already in AGENTS.md or the code (read them instead — they are the source);
+- facts about the CURRENT task or its progress (use TodoList; this file outlives the task);
+- anything the user asked you to keep quiet, secrets, tokens, or credentials;
+- one-off details you will never need again.
+
+Write ONE short note per call, in the user's own language. Prefer several small notes
+over one long entry: a note that is wrong or stale later can be edited out of a file
+you can read back.
+
+Scope:
+- project (default) — stored in this workspace, follows the repository;
+- global — stored in your home directory, applies to every workspace.`,
+  parameters: {
+    type: 'object',
+    properties: {
+      action: {
+        type: 'string',
+        enum: ['add', 'list'],
+        description: 'add a note, or list what is stored. Defaults to add.',
+      },
+      note: {
+        type: 'string',
+        description: 'The note to save (one or two sentences). Required when action is add.',
+      },
+      scope: {
+        type: 'string',
+        enum: ['project', 'global'],
+        description: 'Which memory to write to. Defaults to project.',
+      },
+    },
+    required: [],
+  },
+  async execute(args, ctx) {
+    // A malformed argument must not throw: an uncaught error here aborts the turn.
+    const action = String(args.action || 'add').toLowerCase();
+    const scope = String(args.scope || 'project').toLowerCase() === 'global' ? 'global' : 'project';
+    const workspace = (ctx && (ctx.workspace || ctx.cwd)) || process.cwd();
+
+    if (action === 'list') {
+      const project = readMemoryRaw('project', workspace).trim();
+      const global = readMemoryRaw('global', workspace).trim();
+      const out = [];
+      out.push(`project (${memoryFile('project', workspace)}):`);
+      out.push(project || '  (empty)');
+      out.push('');
+      out.push(`global (${memoryFile('global', workspace)}):`);
+      out.push(global || '  (empty)');
+      return out.join('\n');
+    }
+
+    if (action !== 'add') {
+      return `Error: unknown action ${JSON.stringify(action)}; use "add" or "list".`;
+    }
+    const note = String(args.note == null ? '' : args.note).trim();
+    if (!note) return 'Error: `note` is required when action is "add".';
+    // Guard against the file quietly becoming a transcript. The tool is for durable
+    // facts, and a pasted log is neither durable nor a fact.
+    if (note.length > 600) {
+      return `Error: the note is ${note.length} characters; keep it under 600 (save a summary, not a dump).`;
+    }
+    try {
+      const file = appendMemory(scope, workspace, note);
+      return `Saved to ${scope} memory (${file}).`;
+    } catch (e) {
+      return `Error writing memory: ${e.message}`;
+    }
+  },
+};

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

@@ -1,68 +1,85 @@
-// ReadMediaFile tool — reads media files and returns base64 for images,
-// or metadata for other formats (video, audio).
-// Allows multimodal models to view images and identify media types.
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { resolvePath } from './utils.js';
-
-const MAX_IMAGE_SIZE = 20 * 1024 * 1024; // 20MB max for images
-const MAX_PREVIEW_SIZE = 100 * 1024;     // 100KB text preview for non-images
-
-const SUPPORTED_IMAGE_EXT = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp'];
-const VIDEO_EXT = ['.mp4', '.webm', '.mov', '.avi', '.mkv'];
-const AUDIO_EXT = ['.mp3', '.wav', '.ogg', '.flac', '.m4a'];
-
-export const spec = {
-  name: 'ReadMediaFile',
-  description: 'Read a media file. Images return base64; other formats return metadata.',
-  parameters: {
-    type: 'object',
-    properties: {
-      path: { type: 'string', description: 'Path to the media file.' },
-    },
-    required: ['path'],
-  },
-  async execute(args, ctx) {
-    let p;
-    try { p = resolvePath(args.path, ctx); } catch (e) { return e.message; }
-    
-    if (!fs.existsSync(p)) return `Error: file not found: ${args.path}`;
-    
-    const stat = fs.statSync(p);
-    const ext = path.extname(p).toLowerCase();
-    
-    if (SUPPORTED_IMAGE_EXT.includes(ext)) {
-      if (stat.size > MAX_IMAGE_SIZE) {
-        return `Error: image too large (${(stat.size / 1024 / 1024).toFixed(1)}MB, max 20MB): ${args.path}`;
-      }
-      // 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';
-      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';
-    const sizeMB = (stat.size / 1024 / 1024).toFixed(1);
-    return `[Media: ${fileType.toUpperCase()}] ${args.path} (${sizeMB}MB) - cannot preview in text mode.`;
-  },
-};
+// ReadMediaFile tool — hands a media file to the model as a REAL attachment.
+//
+// An image does not come back as a paragraph describing itself: it returns
+// `{ text, media: [{ type: 'image', mimeType, data }] }`, which the agent stores
+// as the tool result and llm.js converts into the shape each protocol wants
+// (`image_url` for OpenAI, an `image` block for Anthropic). That is what lets the
+// model actually look at a screenshot instead of reading its dimensions.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolvePath } from './utils.js';
+
+// Bytes, not a bit count. Raised well past the old 20MB/64KB limits: the point of
+// this tool is to LOOK at things, and a modern screenshot or photo routinely
+// exceeds them. Override with HNCODE_MEDIA_MAX_BYTES when a provider has its own
+// ceiling (most cap a single image at 5MB after base64).
+const DEFAULT_MAX_BYTES = 50 * 1024 * 1024;
+function maxBytes() {
+  const v = Number(process.env.HNCODE_MEDIA_MAX_BYTES);
+  return Number.isFinite(v) && v > 0 ? v : DEFAULT_MAX_BYTES;
+}
+
+const IMAGE_MIME = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.bmp': 'image/bmp',
+  '.svg': 'image/svg+xml',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+};
+const VIDEO_EXT = ['.mp4', '.webm', '.mov', '.avi', '.mkv'];
+const AUDIO_EXT = ['.mp3', '.wav', '.ogg', '.flac', '.m4a'];
+
+export const spec = {
+  name: 'ReadMediaFile',
+  description: 'Read a media file and attach it to the conversation. Images are sent to the model as an actual image; audio and video return metadata.',
+  parameters: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Path to the media file.' },
+      maxBytes: {
+        type: 'number',
+        description: 'Reject the file above this many bytes instead of the default limit.',
+      },
+    },
+    required: ['path'],
+  },
+  async execute(args, ctx) {
+    let p;
+    try { p = resolvePath(args.path, ctx); } catch (e) { return e.message; }
+
+    if (!fs.existsSync(p)) return `Error: file not found: ${args.path}`;
+    const stat = fs.statSync(p);
+    if (!stat.isFile()) return `Error: not a file: ${args.path}`;
+
+    const ext = path.extname(p).toLowerCase();
+    const abs = p.replace(/\\/g, '/');
+    const sizeKB = Math.max(1, Math.round(stat.size / 1024));
+
+    if (IMAGE_MIME[ext]) {
+      const cap = Number.isFinite(args.maxBytes) && args.maxBytes > 0 ? args.maxBytes : maxBytes();
+      if (stat.size > cap) {
+        return `Error: image too large (${(stat.size / 1024 / 1024).toFixed(1)}MB, max ${(cap / 1024 / 1024).toFixed(0)}MB): ${args.path}\n`
+          + 'Resize it, or raise the limit with HNCODE_MEDIA_MAX_BYTES.';
+      }
+      const mimeType = IMAGE_MIME[ext];
+      const data = fs.readFileSync(p).toString('base64');
+      const approxKB = Math.round(data.length / 1024);
+      return {
+        text: `[image] ${args.path} (${sizeKB}KB, ${mimeType})`,
+        media: [{ type: 'image', mimeType, data }],
+        // Kept for the TUI/web transcript, which renders a one-line receipt
+        // rather than the bytes.
+        _receipt: `Read image ${path.basename(abs)} (${sizeKB}KB, ~${approxKB}KB base64)`,
+      };
+    }
+
+    const fileType = VIDEO_EXT.includes(ext) ? 'video' : AUDIO_EXT.includes(ext) ? 'audio' : 'unknown';
+    const sizeMB = (stat.size / 1024 / 1024).toFixed(1);
+    return `[Media: ${fileType.toUpperCase()}] ${args.path} (${sizeMB}MB) - cannot be attached as an image.`;
+  },
+};