@hncode/hncode 0.5.6 → 0.6.0

package/src/tools/memory.js

@@ -1,88 +1,80 @@
-// 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}`;
-    }
-  },
-};
+// 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 saved.
+
+Use it for something still true next week that you would otherwise rediscover: a build or test command that
+works here, a layout quirk, a convention the user asked for, a decision already made, a gotcha that cost a
+debugging cycle.
+
+Not for: what is already in AGENTS.md or the code (read it — that is the source); the current task or its
+progress (that is TodoList; this file outlives the task); secrets, tokens, credentials, or anything the user
+asked you to keep quiet; one-off details.
+
+One short note per call, in the user's language. Prefer several small notes over one long entry.
+project (default) follows the repository; global 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.js

@@ -35,17 +35,21 @@ export function forgetReadPool(ctx) {
 }
 export const spec = {
   name: 'Read',
-  description: 'Read a text file. Returns the whole file by default; use line_offset / n_lines for a range.',
+  description: 'Read a text file. With no line arguments it returns the whole file; pass start_line and '
+    + 'end_line for a range. BOTH BOUNDS ARE INCLUSIVE: start_line=3, end_line=5 returns THREE lines — 3, 4 '
+    + 'and 5. A negative start_line counts from the end (-100 = the last 100 lines). Every returned line is '
+    + 'prefixed with its 1-based number.',
   parameters: {
     type: 'object',
     properties: {
       path: { type: 'string', description: 'Path to the text file.' },
-      line_offset: {
+      start_line: {
         type: 'integer',
-        description: '1-based start line. Negative counts from the end (e.g. -100 = last 100 lines).',
-        default: 1,
+        description: '1-based FIRST line to return, INCLUSIVE — it is a line that is returned, not the line '
+          + 'before the first one. Omit to start at the first line, or pass a negative value to count from the '
+          + 'end (-100 = last 100 lines).',
       },
-      n_lines: { type: 'integer', minimum: 1, description: 'Lines to read (default: the rest of the file).' },
+      end_line: { type: 'integer', minimum: 1, description: '1-based LAST line to return, INCLUSIVE — it is a line that is returned, not the line after the last one. start_line=3, end_line=5 returns lines 3, 4 and 5. Omit to read to the end of the file.' },
     },
     required: ['path'],
   },
@@ -72,30 +76,30 @@ export const spec = {
     // staleness hashes recorded below because they were computed from the
     // TRUNCATED text rather than the file on disk.
     const text = buf.toString('utf8');
-    // A FILE ENDING IN A NEWLINE HAS ONE FEWER LINE THAN `split` REPORTS.
-    //
-    // `"a\nb\n".split("\n")` is `["a", "b", ""]` — the trailing newline leaves an empty element, and
-    // counting it made a ten-line file report `lines 1-11 of 11`. The numbers on each line were right;
-    // the TOTAL was one too high, so a caller planning an edit at the end of the file aimed at a row that
-    // does not exist.
-    //
-    // Only the element the trailing newline produced is dropped: a file that genuinely ends with a blank
-    // line (`"a\n\n"`) keeps it, because that is real content.
-    const lines = normalizeText(text).split("\n");
-    if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
+    // A FILE ENDING IN A NEWLINE HAS ONE FEWER LINE THAN `split` REPORTS.
+    //
+    // `"a\nb\n".split("\n")` is `["a", "b", ""]` — the trailing newline leaves an empty element, and
+    // counting it made a ten-line file report `lines 1-11 of 11`. The numbers on each line were right;
+    // the TOTAL was one too high, so a caller planning an edit at the end of the file aimed at a row that
+    // does not exist.
+    //
+    // Only the element the trailing newline produced is dropped: a file that genuinely ends with a blank
+    // line (`"a\n\n"`) keeps it, because that is real content.
+    const lines = normalizeText(text).split("\n");
+    if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
     const total = lines.length;
-    // Default: every line. An explicit n_lines still narrows the window.
-    const nLines = args.n_lines ? args.n_lines : total;
-    let start = args.line_offset !== undefined ? args.line_offset : 1;
+    // Default: every line. `start_line` / `end_line` narrow the window, and either may be omitted.
+    let start = args.start_line !== undefined ? Number(args.start_line) : 1;
     if (start < 0) start = Math.max(1, total + 1 + start);
     start = Math.max(1, Math.min(start, total));
-    const end = Math.min(start + nLines - 1, total);
+    const end = args.end_line !== undefined
+      ? Math.min(Math.max(start, Number(args.end_line)), total)
+      : total;
     let out = '';
     out += `${args.path} (lines ${start}-${end} of ${total})\n`;
     for (let i = start; i <= end; i++) out += `${i}\t${lines[i - 1]}\n`;
-    // No trailing "truncated" banner: without an explicit n_lines every line is
-    // returned, so the only way to stop early is a deliberate range request — the
-    // header already states which lines those were.
+    // No trailing "truncated" banner: without an explicit end_line every line is returned, so the only way
+    // to stop early is a deliberate range request — the header already states which lines those were.
 
     // --- Record a hash fingerprint so a later Edit can verify the AI is
     // editing against the same content it read (snippet-staleness guard). ---

package/src/tools/todo.js

@@ -3,21 +3,16 @@
 
 export const spec = {
   name: 'TodoList',
-  description: `Track multi-step work. Pass the COMPLETE list; it replaces the current one. Items: title + status (pending | in_progress | done).
+  description: `Track multi-step work. Pass the COMPLETE list; it replaces the current one.
 
-When to use it:
-- Non-trivial work with several ordered steps, or a request that asks for more than one thing.
-- NOT for a straightforward task you can finish in a step or two, and never as a single-item list.
+Use it for non-trivial work with several ordered steps, or a request asking for more than one thing. Not for a task you can finish in a step or two, and never for a single item.
 
-Maintaining the list:
-- Keep exactly ONE item in_progress at a time until everything is done.
-- Never move an item straight from pending to done: set it to in_progress first, so the list reflects
-  what is actually happening. Do not tick off several items in one update after the fact.
-- Step titles are short (5-7 words), one line each.
-- Update the list as you go, before starting the next step, not in a batch at the end.
-- If your understanding changes, replace the whole list with the corrected one and say why.
-- Finish with every item done, or explicitly say which you abandoned and why. Do not leave the list stale.
-- Do not repeat the list back to the user after updating it — the UI already shows it.`,
+- Exactly ONE item in_progress at a time.
+- Never pending → done: set in_progress first. Do not tick several off in one update after the fact.
+- Titles 5-7 words, one line. Update before starting the next step, not in a batch at the end.
+- If your understanding changes, replace the whole list and say why.
+- Finish with every item done, or say which you abandoned and why — never leave it stale.
+- Do not repeat the list back to the user; the UI already shows it.`,
   parameters: {
     type: 'object',
     properties: {

package/src/tools/validate-args.js

@@ -0,0 +1,78 @@
+/**
+ * Reject a tool call whose arguments do not match the tool's own schema.
+ *
+ * WHY THIS IS AN ERROR AND NOT A NUDGE
+ * ------------------------------------
+ * An unknown parameter used to be accepted in silence, and that silence is expensive: the model sends
+ * `line_offset` to a tool that takes `start_line`, gets a plausible answer computed from defaults, and has no
+ * way to learn that the argument it took trouble to compute was thrown away. The failure then looks like "the
+ * tool is broken" rather than "the call was wrong", and the next attempt usually makes the same mistake with
+ * a different spelling.
+ *
+ * So a call carrying a key the schema does not declare is refused before it runs, and the message NAMES the
+ * key and lists the ones the tool accepts. `required` properties are checked in the same place: a missing
+ * `path` is the same class of mistake and should not reach a tool that will only fail on it later.
+ *
+ * Deliberately NOT a full JSON-Schema validator. It checks object shape, unknown keys, missing required keys
+ * and primitive types, which is what a hand-written tool description needs; a tool that wants to be stricter
+ * still validates inside `execute`.
+ */
+
+/** The JSON type name for a value, in the vocabulary a schema uses. */
+function typeOf(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (Number.isInteger(value)) return 'integer';
+  return typeof value;
+}
+
+/** Whether a value satisfies one schema type name. `number` accepts an integer. */
+function matchesType(value, type) {
+  const actual = typeOf(value);
+  if (type === 'number') return actual === 'number' || actual === 'integer';
+  if (type === 'integer') return actual === 'integer';
+  return actual === type;
+}
+
+/**
+ * Validate arguments against a tool's parameter schema.
+ *
+ * @param {object|undefined|null} args The parsed arguments.
+ * @param {{type?: string, properties?: object, required?: string[]}} [schema] The tool's `parameters`.
+ * @returns {string|null} An error message, or null when the call may run.
+ */
+export function validateToolArgs(args, schema) {
+  // A tool with no schema takes anything; there is nothing to be wrong about.
+  if (!schema || !schema.properties) return null;
+  // A tool whose schema is a free-form object (the shape has no declared properties) also accepts anything.
+  const properties = schema.properties || {};
+  const declared = Object.keys(properties);
+  if (declared.length === 0) return null;
+
+  const isObject = args !== null && typeof args === 'object' && !Array.isArray(args);
+  if (!isObject) {
+    return `the arguments must be a JSON object with keys: ${declared.join(', ')}`;
+  }
+
+  const unknown = Object.keys(args).filter((key) => !(key in properties));
+  if (unknown.length > 0) {
+    const also = declared.length > 0 ? ` It accepts: ${declared.join(', ')}.` : '';
+    return `${unknown.map((k) => `"${k}"`).join(', ')} ${unknown.length === 1 ? 'is not a parameter' : 'are not parameters'}`
+      + ` of this tool.${also}`;
+  }
+
+  const required = Array.isArray(schema.required) ? schema.required : [];
+  const missing = required.filter((key) => args[key] === undefined);
+  if (missing.length > 0) {
+    return `missing required ${missing.length === 1 ? 'parameter' : 'parameters'}: ${missing.join(', ')}`;
+  }
+
+  for (const [key, value] of Object.entries(args)) {
+    const type = properties[key] && properties[key].type;
+    if (type && !matchesType(value, type)) {
+      return `"${key}" must be ${type === 'integer' ? 'an' : 'a'} ${type}, got ${typeOf(value)}`;
+    }
+  }
+
+  return null;
+}