@hncode/hncode 0.1.0

package/src/tools/bash.js

@@ -0,0 +1,240 @@
+// Bash tool — mirrors the kimi-code Bash tool schema & behavior.
+// Runs commands via PowerShell (pwsh). Supports
+// timeout/cwd/run_in_background/disable_timeout. Background tasks are tracked so
+// TaskList/TaskOutput can inspect them.
+
+import fs from 'node:fs';
+import cp from 'node:child_process';
+import { resolvePath, truncateBuf } from './utils.js';
+
+// kimi-code's timeout policy (agent-core-v2/agent/tools/os/bash/bash.ts).
+export const DEFAULT_TIMEOUT_S = 60;
+export const MAX_TIMEOUT_S = 5 * 60;
+export const DEFAULT_BACKGROUND_TIMEOUT_S = 10 * 60;
+export const MAX_BACKGROUND_TIMEOUT_S = 24 * 60 * 60;
+
+// ---- output sanitizing -------------------------------------------------------
+// Captured output can contain terminal control sequences (colours, cursor
+// moves, `\r` spinners, bells, …). hncode's renderer passes result strings to
+// the terminal verbatim, so a surviving escape fights the differential
+// renderer ("text bleeding onto the next row"). It also inflates the token
+// count of what we send back to the model. Strip everything a terminal would
+// interpret as a command, keeping only `\n` and `\t`.
+const OSC_RE = /\u001B\][\s\S]*?(?:\u0007|\u001B\\)/g;
+const CSI_RE = /\u001B\[[0-9:;<=>?]*[ -/]*[@-~]/g;
+const ESC_SINGLE_RE = /\u001B(?:[ -/][0-~]|[0-~])/g;
+const C0_RE = /[\u0000-\u0008\u000B-\u001F]/g;
+
+export function sanitizeShellOutput(text) {
+  const s = String(text ?? '');
+  if (!s) return s;
+  return s
+    .replace(OSC_RE, '')
+    .replace(CSI_RE, '')
+    .replace(ESC_SINGLE_RE, '')
+    .replace(C0_RE, '');
+}
+
+// PowerShell emits UTF-8 by default, so decode output as UTF-8.
+function decodeBuffer(buf) {
+  if (buf.length === 0) return '';
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(buf);
+  } catch {
+    try { return new TextDecoder('gbk').decode(buf); } catch { return buf.toString('utf8'); }
+  }
+}
+function decodeChunks(chunks) {
+  return decodeBuffer(Buffer.concat(chunks));
+}
+
+function killTree(child) {
+  try {
+    if (child.killed) return;
+    if (process.platform === 'win32') {
+      try { cp.spawnSync('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore' }); } catch {}
+    } else {
+      child.kill('SIGTERM');
+    }
+  } catch {}
+  setTimeout(() => { try { child.kill('SIGKILL'); } catch {} }, 1000);
+}
+
+export const spec = {
+  name: 'Bash',
+  description: 'Run a shell command via pwsh. Returns combined stdout+stderr. timeout default 60s (max 300s); run_in_background detaches and returns a task id.',
+  parameters: {
+    type: 'object',
+    properties: {
+      command: { type: 'string', description: 'Shell command to execute.' },
+      description: { type: 'string', description: 'Short description (shown in task lists; required for background tasks).' },
+      timeout: { type: 'integer', minimum: 1, description: 'Seconds before the command is killed. Foreground default 60s/max 300s; background default 600s/max 86400s.' },
+      cwd: { type: 'string', description: 'Working directory (default: workspace/project root).' },
+      run_in_background: { type: 'boolean', default: false, description: 'Run detached and return a task id instead of waiting.' },
+      disable_timeout: { type: 'boolean', default: false, description: 'Disable the timeout (background only).' },
+    },
+    required: ['command'],
+  },
+  async execute(args, ctx) {
+    if (!args.command || !String(args.command).length) return 'Command cannot be empty.';
+    const cwdRaw = args.cwd || ctx.workspace;
+    let cwd;
+    try { cwd = resolvePath(cwdRaw, ctx); } catch (e) { return e.message; }
+    if (!fs.existsSync(cwd)) return `Error: cwd does not exist: ${cwdRaw}`;
+
+    if (args.run_in_background) return spawnBackground(args, cwd, ctx);
+
+    const bg = false;
+    const cap = bg ? MAX_BACKGROUND_TIMEOUT_S : MAX_TIMEOUT_S;
+    const def = bg ? DEFAULT_BACKGROUND_TIMEOUT_S : DEFAULT_TIMEOUT_S;
+    const timeoutMs = args.disable_timeout ? undefined : Math.min(args.timeout ?? def, cap) * 1000;
+    const command = args.command;
+    // stdin is 'ignore' (NUL / /dev/null): leaving it as an open pipe made any
+    // command that reads stdin (`cat`, `npm init`, …) block until the timeout.
+    const child = cp.spawn('pwsh', ['-Command', command], { cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+
+    const chunks = [];
+    let settled = false;
+    // Live stream sink: hand decoded output to the agent (ctx.onOutput) so the UI
+    // can show a running command's output in real time, exactly like the
+    // finished "Used Bash" row does. Foreground runs only — a background task's
+    // output is read through TaskOutput.
+    //
+    // Decoding is STREAMING (a multi-byte char can be split across chunks) and
+    // sanitizing runs over the whole accumulated text, then only the NEW tail is
+    // emitted: stripping per-chunk would cut an escape sequence in half and leak
+    // the remainder into the display.
+    const sink = typeof ctx.onOutput === 'function' ? ctx.onOutput : null;
+    const liveDecoder = sink ? new TextDecoder('utf-8') : null;
+    let liveAcc = '';
+    let liveSent = 0;
+    const push = (d) => {
+      chunks.push(d);
+      if (!sink || settled) return;
+      try {
+        liveAcc += liveDecoder.decode(d, { stream: true });
+        const clean = sanitizeShellOutput(liveAcc);
+        if (clean.length > liveSent) {
+          const delta = clean.slice(liveSent);
+          liveSent = clean.length;
+          sink(delta);
+        }
+      } catch {}
+    };
+    if (child.stdout) child.stdout.on('data', push);
+    if (child.stderr) child.stderr.on('data', push);
+
+    let timer = null;
+    if (timeoutMs) timer = setTimeout(() => { killTree(child); }, timeoutMs);
+
+    // Esc / Ctrl-C in the TUI aborts the turn: kill the running command too,
+    // otherwise a long command keeps running after the user interrupted.
+    const signal = ctx.signal;
+    const onAbort = () => { killTree(child); };
+    if (signal) {
+      if (signal.aborted) return 'Interrupted by user';
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      if (signal) signal.removeEventListener('abort', onAbort);
+    };
+
+    return new Promise((resolve) => {
+      // Expose a detach hook so the TUI's ctrl+b can move a long-running
+      // foreground command into the background WITHOUT killing it: the child
+      // keeps running, gets registered as a task, and this promise resolves
+      // immediately with a "moved to background" note so the agent continues.
+      if (ctx) {
+        ctx._foreground = {
+          command: args.command,
+          description: args.description || args.command,
+          child, chunks,
+          detach: () => {
+            if (settled) return null;
+            settled = true;
+            cleanup();
+            // Stop treating this as foreground: drop the abort listener so an
+            // Esc after detaching does not kill the now-background task.
+            if (signal) signal.removeEventListener('abort', onAbort);
+            const id = registerBackgroundTask(args, child, ctx, chunks);
+            resolve(`Moved to background as task #${id}. It keeps running; inspect with TaskList / TaskOutput {task_id: "${id}"}.`);
+            return id;
+          },
+        };
+      }
+      child.on('close', (code) => {
+        cleanup();
+        if (ctx) ctx._foreground = null;
+        if (settled) return;
+        settled = true;
+        if (signal && signal.aborted) { resolve('Interrupted by user'); return; }
+        let out = truncateBuf(sanitizeShellOutput(decodeChunks(chunks)));
+        out += `\n[exit code: ${code === null ? 'killed' : code}]`;
+        resolve(out);
+      });
+      child.on('error', (e) => {
+        cleanup();
+        if (ctx) ctx._foreground = null;
+        if (settled) return;
+        settled = true;
+        resolve(truncateBuf(sanitizeShellOutput(decodeChunks(chunks))) + `\n[error: ${e.message}]`);
+      });
+    });
+  },
+};
+
+// Register an already-spawned child (foreground -> background detach) as a task.
+// Reuses the same task shape and lazy output decoding as spawnBackground. The
+// foreground path's existing stdout/stderr listeners keep writing into the SAME
+// `existingChunks` array the task reads, so we must NOT add new listeners here
+// (doing so doubled every line of output).
+function registerBackgroundTask(args, child, ctx, existingChunks) {
+  const id = `task_${Date.now()}`;
+  const task = {
+    id, pid: child.pid, command: args.command,
+    description: args.description || args.command,
+    status: 'running', start: Date.now(),
+    _chunks: existingChunks || [],
+  };
+  Object.defineProperty(task, 'output', {
+    enumerable: true,
+    get() { return sanitizeShellOutput(decodeChunks(this._chunks)); },
+  });
+  ctx.tasks[id] = task;
+  child.on('close', (code) => { task.status = code === 0 ? 'done' : 'failed'; task.code = code; task.end = Date.now(); });
+  return id;
+}
+
+function spawnBackground(args, cwd, ctx) {
+  const command = args.command;
+  const child = cp.spawn('pwsh', ['-Command', command], { cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+  const id = `task_${Date.now()}`;
+  const task = {
+    id, pid: child.pid, command: args.command,
+    description: args.description || args.command,
+    status: 'running', start: Date.now(),
+    _chunks: [],
+  };
+  // Decode lazily: the accumulated bytes are decoded only when the output is
+  // actually read, so a chatty background task costs nothing until queried.
+  Object.defineProperty(task, 'output', {
+    enumerable: true,
+    get() { return sanitizeShellOutput(decodeChunks(this._chunks)); },
+  });
+  ctx.tasks[id] = task;
+  const push = (d) => { task._chunks.push(d); };
+  if (child.stdout) child.stdout.on('data', push);
+  if (child.stderr) child.stderr.on('data', push);
+  child.on('close', (code) => { task.status = code === 0 ? 'done' : 'failed'; task.code = code; task.end = Date.now(); });
+  // Background timeout: default 600s, capped at 86400s; `disable_timeout` removes
+  // it. The timer is unref'd so it never keeps the process alive on its own.
+  if (!args.disable_timeout) {
+    const bgTimeoutMs = Math.min(args.timeout ?? DEFAULT_BACKGROUND_TIMEOUT_S, MAX_BACKGROUND_TIMEOUT_S) * 1000;
+    const t = setTimeout(() => { killTree(child); task.status = 'failed'; task.stopReason = 'timed out'; }, bgTimeoutMs);
+    if (t.unref) t.unref();
+  }
+  child.unref();
+  return `Background task #${id} started (pid ${child.pid}): ${args.description || args.command}
+Inspect with TaskList (running tasks) and TaskOutput {task_id: "${id}"} (output).`;
+}

package/src/tools/edit.js

@@ -0,0 +1,138 @@
+// Edit tool — mirrors the hncode Edit tool schema & behavior.
+// Snippet-based exact replacement (old_string -> new_string), NOT a whole-file rewrite,
+// 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 { 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'));
+}
+
+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).',
+  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.' },
+      replace_all: { type: 'boolean', default: false, description: 'Replace all occurrences of old_string.' },
+    },
+    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.`;
+
+    // --- Newline normalization (Windows CRLF) ---
+    // The Read tool normalizes \r\n -> \n, so an agent builds old_string/new_string
+    // with LF. But the file on disk may be CRLF, making a raw LF match fail. We
+    // normalize the FILE content to LF for matching, then restore the file's own
+    // line ending style when writing back, so we never corrupt or mix endings.
+    const eol = content.includes('\r\n') ? '\r\n' : '\n';
+    const normContent = content.split(/\r\n|\r|\n/).join('\n');
+    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}.`;
+    if (count > 1 && !replace_all) {
+      return `Error: old_string matched ${count} occurrences in ${args.path}. Use replace_all=true or make old_string unique.`;
+    }
+
+    // --- Staleness guard: the AI must edit against content it actually Read.
+    // 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);
+    if (stale) return stale;
+
+    const normUpdated = replace_all
+      ? normContent.replaceAll(normOld, normNew)
+      : normContent.replace(normOld, normNew);
+    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}`; }
+    // Silently re-arm the Read snapshot for the edited region so the AI can keep
+    // editing on top of its own change WITHOUT another Read: we recompute the
+    // affected line range + hash from the NEW content and refresh the pool. We
+    // also drop any previously-recorded region whose content no longer matches
+    // (those are genuinely stale now). Nothing here is told to the model.
+    if (ctx && ctx.readPool) {
+      const entry = ctx.readPool.get(p);
+      if (entry) {
+        const newLines = normUpdated.split('\n');
+        entry.fileHash = hashStr(normUpdated);
+        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];
+        let at = newLines.indexOf(anchor);
+        if (at < 0) at = newLines.indexOf(String(normOld).split('\n')[0]);
+        if (at >= 0) {
+          const newSpan = String(normNew).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
+          // the freshly-edited span. Regions that no longer match are dropped.
+          const kept = entry.regions.filter((r) => hashLines(newLines, r.start, r.end) === r.hash);
+          kept.push({ start, end, hash: hashLines(newLines, start, end) });
+          entry.regions = kept;
+        } else {
+          // Could not locate the site: drop stale regions so nothing false stays.
+          entry.regions = entry.regions.filter((r) => hashLines(newLines, r.start, r.end) === r.hash);
+        }
+        try { const st = fs.statSync(p); entry.size = st.size; entry.mtimeMs = st.mtimeMs; } catch {}
+      }
+    }
+    const occurrences = replace_all ? count : 1;
+    return `Edited ${args.path}: replaced ${occurrences} occurrence(s).`;
+  },
+};
+
+// 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
+  const entry = ctx.readPool.get(p);
+  if (!entry) return null; // this file was never Read this turn; allow
+
+  const curLines = normContent.split('\n');
+  const curFileHash = hashStr(normContent);
+
+  // Locate the edit target's first line in the CURRENT file (1-based).
+  const firstLine = String(normOld).split('\n')[0];
+  const idx = curLines.indexOf(firstLine);
+  const editLine = idx >= 0 ? idx + 1 : -1;
+
+  // (1) The edit target must sit inside a region the AI actually Read, and that
+  //     region's content must still match what was Read. Reading the WHOLE file
+  //     records a region covering every line, so this also covers "read full,
+  //     edit a part". This is what rejects "read lines 1-3, edit line 7".
+  if (editLine > 0) {
+    const coveredByIntactRegion = entry.regions.some(
+      (r) => editLine >= r.start && editLine <= r.end && hashLines(curLines, r.start, r.end) === r.hash,
+    );
+    if (coveredByIntactRegion) return null;
+  }
+
+  // (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.
+  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 so far: lines ${ranges}). Read the target lines first (Read with line_offset / n_lines), 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.`;
+}

package/src/tools/fetch-url.js

@@ -0,0 +1,108 @@
+// FetchURL tool — fetch a web page's main text content (Node built-in fetch, no deps).
+
+import os from 'node:os';
+
+const MAX_BYTES = 200 * 1024; // generous cap for large pages
+
+// Strip HTML tags and collapse whitespace into readable plain text.
+export function htmlToText(html) {
+  let s = String(html || '');
+  // Drop script/style contents entirely.
+  s = s.replace(/<script[\s\S]*?<\/script>/gi, ' ')
+        .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+        .replace(/<noscript[\s\S]*?<\/noscript>/gi, ' ');
+  // Replace block-level tags with newlines so paragraphs survive.
+  s = s.replace(/<(br|p|div|li|h[1-6]|tr|section|article|blockquote)[^>]*>/gi, '\n')
+        .replace(/<\/(p|div|li|h[1-6]|tr|section|article|blockquote|ul|ol)>/gi, '\n');
+  // Decode a few common entities to ASCII.
+  s = s.replace(/&nbsp;/gi, ' ')
+        .replace(/&amp;/gi, '&')
+        .replace(/&lt;/gi, '<')
+        .replace(/&gt;/gi, '>')
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;|&apos;/gi, "'")
+        .replace(/&mdash;/gi, '—')
+        .replace(/&ndash;/gi, '–');
+  // Remove any remaining tags and collapse whitespace.
+  s = s.replace(/<[^>]*>/g, ' ');
+  s = s.replace(/[ \t]+/g, ' ').replace(/\n\s*\n+/g, '\n').trim();
+  return s;
+}
+
+// Reject non-http(s) URLs. No SSRF guard: hncode is a local tool the user
+// controls, the model may legitimately fetch a localhost service or intranet
+// page, and Bash can already run anything. Only enforce http/https.
+function rejectUrl(raw) {
+  if (!raw || typeof raw !== 'string') return 'Error: url must be a non-empty string.';
+  let u;
+  try { u = new URL(raw.trim()); } catch { return `Error: invalid URL: ${raw}`; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    return `Error: only http/https URLs are supported (got ${u.protocol}//).`;
+  }
+  return null; // ok
+}
+
+export const spec = {
+  name: 'FetchURL',
+  description: 'Fetch a URL and return its text (main page text, or the full body; a leading note says which). Any http/https URL, including localhost.',
+  parameters: {
+    type: 'object',
+    properties: {
+      url: { type: 'string', description: 'URL to fetch.' },
+    },
+    required: ['url'],
+  },
+  async execute(args, ctx) {
+    const rejected = rejectUrl(args.url);
+    if (rejected) return rejected;
+    const signal = (ctx && ctx.signal) || undefined;
+    try {
+      const res = await fetch(args.url.trim(), { signal, redirect: 'follow' });
+      if (!res.ok) {
+        return `Error: ${res.status} ${res.statusText} from ${args.url}`;
+      }
+      const contentType = (res.headers.get('content-type') || '').toLowerCase();
+      const isHtml = contentType.includes('text/html') || contentType.includes('application/xhtml');
+      let isTruncated = false;
+      let body;
+      if (res.body) {
+        const reader = res.body.getReader();
+        const chunks = [];
+        let got = 0;
+        while (got < MAX_BYTES) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          chunks.push(value);
+          got += value.length;
+          if (got >= MAX_BYTES) { isTruncated = true; break; }
+        }
+        if (isTruncated) { try { await reader.cancel(); } catch {} }
+        body = Buffer.concat(chunks);
+      } else {
+        body = Buffer.from(await res.arrayBuffer());
+      }
+
+      let text;
+      if (isHtml) {
+        text = htmlToText(body.toString('utf8'));
+      } else if (contentType.includes('json')) {
+        text = 'The returned content is the full response body, returned verbatim:\n\n' + body.toString('utf8');
+      } else if (contentType.includes('text/')) {
+        text = body.toString('utf8');
+      } else {
+        const type = contentType.split(';')[0] || 'unknown';
+        return `The response is binary (content-type: ${type}); no text content to return.`;
+      }
+      if (!text || !text.trim()) text = 'The response body is empty.';
+      let out = isHtml
+        ? 'The returned content is the main text extracted from the page.\n\n'
+        : 'The returned content is the full response body, returned verbatim.\n\n';
+      out += text;
+      if (isTruncated) out += `\n\n[... truncated; page larger than ${Math.round(MAX_BYTES / 1024)} KB]`;
+      return out;
+    } catch (e) {
+      const msg = e && e.name === 'AbortError' ? 'interrupted' : (e.message || String(e));
+      return `Error fetching ${args.url}: ${msg}`;
+    }
+  },
+};

package/src/tools/file-lines.js

@@ -0,0 +1,36 @@
+// FileLines tool — reports how many lines a file has. Line count ONLY: it never
+// returns file content (use Read for that). This lets an agent size a file
+// cheaply before deciding whether/where to Read it.
+
+import fs from 'node:fs';
+import { resolvePath } from './utils.js';
+
+export const spec = {
+  name: 'FileLines',
+  description: 'Count the lines of a file. Does NOT return content; use Read for that.',
+  parameters: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Path to the 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);
+    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}`;
+  },
+};

package/src/tools/glob.js

@@ -0,0 +1,47 @@
+// Glob tool — mirrors the hncode Glob tool schema & behavior.
+// Recursive glob from `path` (default cwd), honoring .gitignore/.ignore/.rgignore
+// unless include_ignored. Returns up to 100 matches sorted most-recent-modified first.
+
+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';
+
+export const spec = {
+  name: 'Glob',
+  description: 'Find files by glob pattern. Honors ignore files unless include_ignored. Up to 100 matches, newest first.',
+  parameters: {
+    type: 'object',
+    properties: {
+      pattern: { type: 'string', description: 'Glob pattern (e.g. src/**/*.ts).' },
+      path: { type: 'string', description: 'Directory to search from (default: project root).', default: '.' },
+      include_ignored: { type: 'boolean', default: false, description: 'Also match git-ignored paths.' },
+      include_dirs: { type: 'boolean', default: false, description: 'Include directories in results.' },
+    },
+    required: ['pattern'],
+  },
+  async execute(args, ctx) {
+    const fromDir = 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 files = walkFiles(base, { includeIgnored: !!args.include_ignored, includeDirs: false });
+    const matches = [];
+    for (const abs of files) {
+      const rel = path.relative(base, abs).split(path.sep).join('/');
+      const winRel = abs.replace(/\\/g, '/');
+      const base_ = path.basename(abs);
+      if (re.test(rel) || re.test(winRel) || re.test(base_)) matches.push(abs);
+    }
+    if (matches.length > 100) matches.length = 100;
+    if (matches.length === 0) return `No files matched \`${args.pattern}\` in ${fromDir}`;
+    return matches.join('\n');
+  },
+};