@hncode/hncode 0.1.0

package/src/tools/grep.js

@@ -0,0 +1,152 @@
+// Grep tool — mirrors the hncode Grep tool schema & behavior.
+// Primary path uses ripgrep (`rg`) for full fidelity; falls back to a pure-JS
+// walker when rg is unavailable or multiline searching is requested.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import cp from 'node:child_process';
+import { normalizeInput, isProbablyTextFile, truncateBuf } from './utils.js';
+import { walkFiles } from './ignore.js';
+import { matchGlob } from './matchers.js';
+
+export const spec = {
+  name: 'Grep',
+  description: 'Search file contents by regex. output_mode: content (default) | files_with_matches | count_matches. Honors ignore files unless include_ignored.',
+  parameters: {
+    type: 'object',
+    properties: {
+      pattern: { type: 'string', description: 'The regular expression to search for.' },
+      path: { type: 'string', description: 'Directory or file to search (default: cwd).', default: '.' },
+      glob: { type: 'string', description: 'Glob filter for which files are searched (e.g. *.ts).' },
+      type: { type: 'string', description: 'File-type filter (ripgrep -t, e.g. ts, py, go).' },
+      output_mode: { type: 'string', enum: ['content', 'files_with_matches', 'count_matches'], default: 'content', description: 'Matching lines, matching files, or per-file counts.' },
+      '-i': { type: 'boolean', default: false, description: 'Case-insensitive search.' },
+      '-n': { type: 'boolean', default: false, description: 'Prefix each match with its 1-based line number.' },
+      '-A': { type: 'integer', minimum: 0, description: 'Lines of context after each match.' },
+      '-B': { type: 'integer', minimum: 0, description: 'Lines of context before each match.' },
+      '-C': { type: 'integer', minimum: 0, description: 'Lines of context around each match (alias for -A/-B).' },
+      head_limit: { type: 'integer', minimum: 0, description: 'Limit output to the first N matches/lines.' },
+      offset: { type: 'integer', minimum: 0, description: 'Leading matches/lines to skip.' },
+      multiline: { type: 'boolean', default: false, description: 'Match across newlines.' },
+      include_ignored: { type: 'boolean', default: false, description: 'Search ignored files too.' },
+    },
+    required: ['pattern'],
+  },
+  async execute(args, ctx) {
+    const p = normalizeInput(args.path || '.');
+    const base = path.resolve(ctx.cwd || ctx.workspace, p);
+    if (!fs.existsSync(base)) return `Error: path does not exist: ${args.path}`;
+    if (!args.multiline && hasRg()) return grepRg(args, base, ctx);
+    return grepJs(args, base, ctx);
+  },
+};
+
+function hasRg() {
+  try { cp.spawnSync('rg', ['--version'], { stdio: 'ignore' }); return true; }
+  catch { return false; }
+}
+
+function buildRgArgs(args, base) {
+  const a = ['--no-heading', '--line-number', '--no-config', '-e', args.pattern];
+  if (args['-i']) a.push('-i');
+  const before = args['-B'] || (args['-C'] || 0);
+  const after = args['-A'] || (args['-C'] || 0);
+  if (before) a.push('-B', String(before));
+  if (after) a.push('-A', String(after));
+  if (args.glob) a.push('-g', args.glob);
+  if (args.type) a.push('-t', args.type);
+  if (args.output_mode === 'files_with_matches') a.push('-l');
+  else if (args.output_mode === 'count_matches') a.push('-c');
+  if (args.include_ignored) a.push('--no-ignore');
+  a.push('--', base);
+  return a;
+}
+
+function grepRg(args, base, ctx) {
+  let out;
+  try {
+    const r = cp.spawnSync('rg', buildRgArgs(args, base), {
+      cwd: ctx.cwd || ctx.workspace,
+      maxBuffer: 64 * 1024 * 1024,
+      encoding: 'utf8',
+    });
+    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 paginate(out, args);
+}
+
+function grepJs(args, base, ctx) {
+  const flags = 'g' + (args['-i'] ? 'i' : '') + (args.multiline ? 's' : '');
+  const re = new RegExp(args.pattern, flags);
+  const files = walkFiles(base, { includeIgnored: !!args.include_ignored, includeDirs: false });
+  const filtered = files.filter((abs) => {
+    if (args.glob) {
+      const rel = path.relative(base, abs).split(path.sep).join('/');
+      if (!matchGlob(args.glob, rel) && !matchGlob(args.glob, path.basename(abs))) return false;
+    }
+    if (args.type) {
+      const ext = path.extname(abs).toLowerCase().slice(1);
+      if (ext !== args.type) return false;
+    }
+    return true;
+  });
+
+  const out = [];
+  for (const abs of filtered) {
+    let txt;
+    try {
+      const buf = fs.readFileSync(abs);
+      if (!isProbablyTextFile(buf)) continue;
+      txt = truncateBuf(buf);
+    } catch { continue; }
+    const mode = args.output_mode;
+
+    if (args.multiline) {
+      const ms = Array.from(txt.matchAll(re));
+      if (ms.length === 0) continue;
+      if (mode === 'files_with_matches') { out.push(abs); continue; }
+      if (mode === 'count_matches') { out.push(`${abs}:${ms.length}`); continue; }
+      const lines = txt.split('\n');
+      for (const mm of ms) {
+        const lineNo = txt.slice(0, mm.index).split('\n').length; // 1-based
+        emitContext(out, abs, lineNo - 1, lines, args);
+      }
+    } else {
+      const lines = txt.split('\n');
+      let count = 0;
+      for (let i = 0; i < lines.length; i++) {
+        if (re.test(lines[i])) {
+          count++;
+          if (mode === 'files_with_matches') { out.push(abs); break; }
+          if (mode === 'count_matches') continue;
+          emitContext(out, abs, i, lines, args);
+        }
+      }
+      if (count > 0 && mode === 'count_matches') out.push(`${abs}:${count}`);
+    }
+  }
+  return paginate(out.join('\n'), args);
+}
+
+function emitContext(out, file, idx, lines, a) {
+  const before = a['-C'] || a['-B'] || 0;
+  const after = a['-C'] || a['-A'] || 0;
+  const start = Math.max(0, idx - before);
+  const end = Math.min(lines.length - 1, idx + after);
+  for (let k = start; k <= end; k++) {
+    if (k === idx) out.push(`${file}:${k + 1}:${lines[k]}`);
+    else out.push(`${file}-${k + 1}-${lines[k]}`);
+  }
+}
+
+function paginate(raw, args) {
+  if (raw === '' || raw === undefined || raw === null) return 'No matches found.';
+  let lines = raw.split('\n').filter((l) => l.length > 0);
+  if (args.offset) lines = lines.slice(args.offset);
+  if (args.head_limit) lines = lines.slice(0, args.head_limit);
+  if (lines.length === 0) return 'No matches found.';
+  return lines.join('\n');
+}

package/src/tools/ignore.js

@@ -0,0 +1,99 @@
+// Best-effort .gitignore / .ignore / .rgignore matcher for Glob & Grep.
+import fs from 'node:fs';
+import path from 'node:path';
+import { globToRegexSource } from './matchers.js';
+
+const IGNORE_FILES = ['.gitignore', '.ignore', '.rgignore'];
+const cache = new Map();
+
+export function parseIgnoreFile(text) {
+  const out = [];
+  for (let line of text.split(/\r?\n/)) {
+    line = line.replace(/\s+#.*$/, ''); // strip trailing comments? no: only outside string; good enough
+    line = line.trimEnd();
+    if (!line || line.startsWith('#')) continue;
+    let negate = false;
+    if (line.startsWith('!')) { negate = true; line = line.slice(1); }
+    let dirOnly = false;
+    if (line.endsWith('/')) { dirOnly = true; line = line.slice(0, -1); }
+    let anchor = false;
+    if (line.startsWith('/')) { anchor = true; line = line.slice(1); }
+    if (!line) continue;
+    out.push({ raw: line, negate, dirOnly, anchor });
+  }
+  return out;
+}
+
+export function ignorePatternsFor(dir) {
+  let cached = cache.get(dir);
+  if (cached) return cached;
+  const arr = [];
+  for (const name of IGNORE_FILES) {
+    try {
+      const txt = fs.readFileSync(path.join(dir, name), 'utf8');
+      arr.push(...parseIgnoreFile(txt));
+    } catch {}
+  }
+  cache.set(dir, arr);
+  return arr;
+}
+
+function globToRegex(pattern) {
+  return new RegExp(globToRegexSource(pattern));
+}
+
+export function matchPattern(pat, relPath, isDir) {
+  if (pat.dirOnly && !isDir) return false;
+  const re = globToRegex(pat.raw);
+  if (pat.anchor) return re.test(relPath);
+  if (re.test(relPath)) return true;
+  const parts = relPath.split('/');
+  for (let i = 0; i < parts.length; i++) {
+    if (re.test(parts.slice(i).join('/'))) return true;
+  }
+  return false;
+}
+
+// Walk dir applying ignore patterns from root..leaf. Returns list of absolute files
+// (and dirs if includeDirs), honoring ignore unless includeIgnored.
+export function walkFiles(base, opts = {}) {
+  const results = [];
+  const { includeIgnored = false, includeDirs = false } = opts;
+  const baseAbs = path.resolve(base);
+  _walk(baseAbs, '', [], results, { includeIgnored, includeDirs });
+  // sort by mtime desc for a "most recent first" feel
+  results.sort((a, b) => {
+    try { return fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs; } catch { return b < a ? 1 : -1; }
+  });
+  if (results.length > 1000) results.length = 1000;
+  try { if (!includeDirs) return results.filter(p => { try { return fs.statSync(p).isFile(); } catch { return false; } }); } catch { return results; }
+  return results;
+}
+
+function _walk(dir, relPrefix, parentPatterns, results, opts) {
+  const { includeIgnored, includeDirs } = opts;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+  const acc = parentPatterns.concat(ignorePatternsFor(dir));
+  for (const ent of entries) {
+    const rel = relPrefix ? relPrefix + '/' + ent.name : ent.name;
+    const abs = path.join(dir, ent.name);
+    let isDir;
+    try { isDir = ent.isDirectory(); } catch { try { isDir = fs.statSync(abs).isDirectory(); } catch { isDir = false; } }
+    // ignore decision
+    let ignored = false;
+    for (const pat of acc) {
+      if (matchPattern(pat, rel, isDir)) ignored = !pat.negate;
+    }
+    if (ignored && !includeIgnored) {
+      if (isDir) continue; // prune dir subtree
+      continue;
+    }
+    if (isDir) {
+      if (includeDirs) results.push(abs);
+      _walk(abs, rel, acc, results, opts);
+    } else {
+      results.push(abs);
+    }
+  }
+}

package/src/tools/index.js

@@ -0,0 +1,61 @@
+// Toolbelt registry. Each entry exposes the JSON schema (matching hncode's tools)
+// plus an async execute(args, ctx) returning a result string.
+
+import * as readMod from './read.js';
+import * as writeMod from './write.js';
+import * as editMod from './edit.js';
+import * as globMod from './glob.js';
+import * as grepMod from './grep.js';
+import * as bashMod from './bash.js';
+import * as todoMod from './todo.js';
+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 { TaskListSpec, TaskOutputSpec, TaskStopSpec, TaskWaitSpec } from './tasks.js';
+import { pluginTools } from '../plugin.js';
+
+// Built-in tools.
+const builtinTools = [
+  readMod.spec,
+  writeMod.spec,
+  editMod.spec,
+  globMod.spec,
+  grepMod.spec,
+  bashMod.spec,
+  todoMod.spec,
+  fetchUrlMod.spec,
+  webSearchMod.spec,
+  readMediaFileMod.spec,
+  fileLinesMod.spec,
+  TaskListSpec,
+  TaskOutputSpec,
+  TaskStopSpec,
+  TaskWaitSpec,
+];
+
+// 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).
+export function combinedTools() {
+  return [...builtinTools, ...pluginTools];
+}
+
+export const tools = builtinTools;
+export { builtinTools };
+
+const byName = new Map(builtinTools.map((t) => [t.name, t]));
+export function getTool(name) { return byName.get(name); }
+export function toolNames() { return combinedTools().map((t) => t.name); }
+
+// Schemas for sending to an LLM (OpenAI `tools` array).
+export function llmTools() {
+  return combinedTools().map((t) => ({
+    type: 'function',
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+    },
+  }));
+}

package/src/tools/matchers.js

@@ -0,0 +1,71 @@
+// 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);
+}

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

@@ -0,0 +1,54 @@
+// 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}`;
+      }
+      const data = fs.readFileSync(p);
+      const base64 = data.toString('base64');
+      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 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.`;
+  },
+};

package/src/tools/read.js

@@ -0,0 +1,99 @@
+// Read tool — mirrors the hncode Read tool schema & behavior.
+
+import fs from 'node:fs';
+import { resolvePath, isProbablyTextFile } from './utils.js';
+
+// Normalize newlines so a text file's hash is stable regardless of CRLF/LF.
+export function normalizeText(s) {
+  return String(s).split(/\r\n|\r|\n/).join('\n');
+}
+// FNV-1a-ish 32-bit hash of a string (cheap, deterministic).
+export function hashStr(s) {
+  const str = normalizeText(s);
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = (h * 0x01000193) >>> 0;
+  }
+  return h.toString(36);
+}
+// Hash the exact <start..end> 1-based line slice of `lines`.
+function hashLines(lines, start, end) {
+  const slice = (lines.slice(start - 1, end) || []).join('\n');
+  return hashStr(slice);
+}
+
+export const spec = {
+  name: 'Read',
+  description: 'Read a text file. Returns the whole file by default; use line_offset / n_lines for a range.',
+  parameters: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'Path to the text file.' },
+      line_offset: {
+        type: 'integer',
+        description: '1-based start line. Negative counts from the end (e.g. -100 = last 100 lines).',
+        default: 1,
+      },
+      n_lines: { type: 'integer', minimum: 1, description: 'Lines to read (default: the rest of the file).' },
+    },
+    required: ['path'],
+  },
+  async execute(args, ctx) {
+    let p;
+    try { p = resolvePath(args.path, ctx); } catch (e) { return e.message; }
+    let buf;
+    try { buf = fs.readFileSync(p); } catch (e) { return `Error reading ${args.path}: ${e.message}`; }
+    if (!isProbablyTextFile(buf)) {
+      return `Cannot read: ${args.path} appears to be a binary file (use a tool suited for binary).`;
+    }
+    let st;
+    try { st = fs.statSync(p); } catch { st = null; }
+    // NO truncation: the caller asked for the file, so the whole file is returned
+    // (line ranges still work via line_offset / n_lines). The old 1000-line and
+    // 128 KB caps silently cut the content, which also corrupted the
+    // staleness hashes recorded below because they were computed from the
+    // TRUNCATED text rather than the file on disk.
+    const text = buf.toString('utf8');
+    const lines = normalizeText(text).split('\n');
+    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;
+    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);
+    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.
+
+    // --- Record a hash fingerprint so a later Edit can verify the AI is
+    // editing against the same content it read (snippet-staleness guard). ---
+    // Store the FULL file's normalized content hash plus this call's line
+    // range + region hash. Edit compares old_string's location against these.
+    if (ctx) {
+      const pool = (ctx.readPool = ctx.readPool || new Map());
+      let entry = pool.get(p);
+      if (!entry) {
+        entry = {
+          mtimeMs: st ? st.mtimeMs : 0,
+          size: st ? st.size : 0,
+          fileHash: hashStr(text),
+          lines: total,            // current total line count at read time
+          regions: [],             // {start, end, hash} of each read slice
+        };
+        pool.set(p, entry);
+      }
+      entry.mtimeMs = st ? st.mtimeMs : entry.mtimeMs;
+      entry.size = st ? st.size : entry.size;
+      entry.fileHash = hashStr(text);
+      entry.lines = total;
+      // Record this call's exact region (only the lines actually returned).
+      entry.regions.push({ start, end, hash: hashLines(lines, start, end) });
+    }
+    return out;
+  },
+};

package/src/tools/tasks.js

@@ -0,0 +1,126 @@
+// TaskList / TaskOutput / TaskStop — manage background Bash tasks spawned with
+// run_in_background.
+
+import cp from 'node:child_process';
+
+export const TaskListSpec = {
+  name: 'TaskList',
+  description: 'List background tasks (from Bash run_in_background). Reports id, status, description.',
+  parameters: { type: 'object', properties: {}, required: [] },
+  async execute(_args, ctx) {
+    const tasks = Object.values(ctx.tasks || {}).sort((a, b) => b.start - a.start);
+    if (tasks.length === 0) return 'No background tasks.';
+    return tasks.map((t) => `#${t.id} [${t.status}] pid=${t.pid} ${t.description || t.command}`).join('\n');
+  },
+};
+
+export const TaskOutputSpec = {
+  name: 'TaskOutput',
+  description: 'Get the output of a background task (Bash run_in_background) by task_id. head_limit caps the lines returned.',
+  parameters: {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string', description: 'Task id returned when the task was started.' },
+      head_limit: { type: 'integer', minimum: 0, description: 'Max output lines returned.' },
+    },
+    required: ['task_id'],
+  },
+  async execute(args, ctx) {
+    const t = (ctx.tasks || {})[args.task_id];
+    if (!t) return `No such task: ${args.task_id}`;
+    const lines = t.output ? t.output.split('\n').filter((l) => l.length > 0) : [];
+    const capped = args.head_limit ? lines.slice(0, args.head_limit) : lines;
+    const tail = lines.length > (capped.length);
+    let out = `#${t.id} [${t.status}] (pid ${t.pid})\n${capped.join('\n')}`;
+    if (tail) out += `\n... [${lines.length - capped.length} more lines; use head_limit]`;
+    return out;
+  },
+};
+
+export const TaskStopSpec = {
+  name: 'TaskStop',
+  description: 'Stop a running background task (Bash run_in_background) by task_id. Use only when the task must be cancelled.',
+  parameters: {
+    type: 'object',
+    properties: {
+      task_id: { type: 'string', description: 'Background task id to stop.' },
+      reason: { type: 'string', description: 'Short reason recorded on stop.' },
+    },
+    required: ['task_id'],
+  },
+  async execute(args, ctx) {
+    const t = (ctx.tasks || {})[args.task_id];
+    if (!t) return `No such task: ${args.task_id}`;
+    if (t.status !== 'running') return `Task ${t.id} is not running (status: ${t.status}).`;
+    const reason = args.reason || 'Stopped by TaskStop';
+    try {
+      if (process.platform === 'win32' && t.pid) {
+        try { cp.spawnSync('taskkill', ['/pid', String(t.pid), '/t', '/f'], { stdio: 'ignore' }); } catch {}
+      } else if (t.pid) {
+        try { process.kill(t.pid, 'SIGTERM'); } catch {}
+      }
+    } catch (e) {
+      return `Failed to stop ${t.id}: ${e.message}`;
+    }
+    t.status = 'stopped';
+    t.stopReason = reason;
+    t.end = Date.now();
+    return `Stopped task ${t.id}. reason: ${reason}`;
+  },
+};
+
+// WaitFor — block until a background task finishes (or the timeout elapses).
+// Mirrors kimi-code's task-wait: a timeout is not an error; the result lists
+// the tasks still running so the caller can wait again.
+export const TaskWaitSpec = {
+  name: 'TaskWait',
+  description: 'Wait for background tasks (Bash run_in_background) to finish, timeout in seconds (1-600). With task_id, waits for that task; without it, returns when any running task finishes. A timeout is not an error; still-running tasks are listed, so you may call it again.',
+  parameters: {
+    type: 'object',
+    properties: {
+      timeout: { type: 'integer', minimum: 1, maximum: 600, description: 'Max seconds to wait (1-600).' },
+      task_id: { type: 'string', description: 'Task id to wait for; omit to wait for any running task.' },
+    },
+    required: ['timeout'],
+  },
+  async execute(args, ctx) {
+    const tasks = ctx.tasks || {};
+    const target = args.task_id ? tasks[args.task_id] : null;
+    if (args.task_id && !target) return `No such task: ${args.task_id}`;
+    const secs = Math.max(1, Math.min(600, Number(args.timeout) || 1));
+    const deadline = Date.now() + secs * 1000;
+    const signal = ctx && ctx.signal;
+
+    const isDone = (t) => t && t.status !== 'running';
+    const anyRunning = () => Object.values(tasks).some((t) => t.status === 'running');
+
+    // Nothing to wait for at call time.
+    if (args.task_id) {
+      if (isDone(target)) return `Task ${target.id} already ${target.status}${target.code !== undefined ? ` (exit ${target.code})` : ''}.`;
+    } else if (!anyRunning()) {
+      return 'No background tasks are running.';
+    }
+
+    await new Promise((resolve) => {
+      const tick = setInterval(() => {
+        const done = args.task_id ? isDone(target) : !anyRunning();
+        if (done || Date.now() >= deadline || (signal && signal.aborted)) {
+          clearInterval(tick);
+          resolve();
+        }
+      }, 100);
+    });
+
+    if (signal && signal.aborted) return 'Interrupted by user';
+    const still = Object.values(tasks).filter((t) => t.status === 'running');
+    if (args.task_id) {
+      if (isDone(target)) {
+        return `Task ${target.id} finished: ${target.status}${target.code !== undefined ? ` (exit ${target.code})` : ''}${target.stopReason ? ` — ${target.stopReason}` : ''}.`;
+      }
+      return `Task ${target.id} still running after ${secs}s.`;
+    }
+    if (!still.length) return 'All background tasks have finished.';
+    const list = still.map((t) => `#${t.id} ${t.description || t.command}`).join('; ');
+    return `Timeout after ${secs}s; still running: ${list}`;
+  },
+};