ucode-agent 1.0.0

package/src/tools/index.js

@@ -0,0 +1,394 @@
+/**
+ * index.js — the tool registry: schemas, argument checking, dispatch, and the
+ * line the user reads while each one runs.
+ */
+
+import { ToolFailure } from '../core/failure.js';
+import { readFile, readFiles, writeFile, batchWrite, editFile, multiEdit } from './files.js';
+import { listDir, glob, grep } from './search.js';
+import { runCommand, runCommands } from './shell.js';
+import { webSearch } from './web.js';
+import { clip, READ_LINES } from './shared.js';
+
+export { setRoot, setConfirm, getRoot } from './shared.js';
+
+const str = (description) => ({ type: 'string', description });
+const int = (description) => ({ type: 'integer', description });
+const bool = (description) => ({ type: 'boolean', description });
+
+export const tools = [
+  {
+    name: 'read_file',
+    description:
+      'Read a text file. Comes back as numbered lines — the numbers are for you to ' +
+      'refer to and must never appear in an edit_file argument. Long files arrive in ' +
+      'pages; pass offset to keep going.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: str('File path, relative to the project root.'),
+        offset: int('First line to read, 1-based. Defaults to 1.'),
+        limit: int(`How many lines. Defaults to ${READ_LINES}.`),
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'read_files',
+    description:
+      'Read several text files in one call. Use this whenever you need more than one ' +
+      'file - it is one round trip instead of one per file, so it is much faster than ' +
+      'calling read_file repeatedly. Same numbered-line output as read_file, one block ' +
+      'per file. A missing file is reported in its place without failing the others.',
+    parameters: {
+      type: 'object',
+      properties: {
+        paths: {
+          type: 'array',
+          description: 'File paths, relative to the project root. Up to 20.',
+          items: { type: 'string' },
+        },
+        limit: int(`Lines per file. Defaults to ${READ_LINES}.`),
+      },
+      required: ['paths'],
+    },
+  },
+  {
+    name: 'write_file',
+    description:
+      'Create a file, or replace all of its contents. For a change to part of an ' +
+      'existing file use edit_file instead — this one throws away everything that was ' +
+      'there. Missing parent directories are created.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: str('File path, relative to the project root.'),
+        content: str('The complete text of the file.'),
+      },
+      required: ['path', 'content'],
+    },
+  },
+  {
+    name: 'batch_write',
+    description:
+      'Create or replace several files in one call. Use this to lay out a whole ' +
+      'project at once instead of calling write_file over and over — it is the ' +
+      'difference between one round trip and twenty.',
+    parameters: {
+      type: 'object',
+      properties: {
+        files: {
+          type: 'array',
+          description: 'The files to write.',
+          items: {
+            type: 'object',
+            properties: {
+              path: str('File path, relative to the project root.'),
+              content: str('The complete text of the file.'),
+            },
+            required: ['path', 'content'],
+          },
+        },
+      },
+      required: ['files'],
+    },
+  },
+  {
+    name: 'edit_file',
+    description:
+      'Replace one exact piece of text in a file. old_string must match the file ' +
+      'character for character, including indentation, and must occur exactly once — ' +
+      'the edit is refused on zero matches and on two. This is the normal way to ' +
+      'change existing code.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: str('File path, relative to the project root.'),
+        old_string: str('The exact text to replace. Must be unique in the file.'),
+        new_string: str('What to put there instead.'),
+      },
+      required: ['path', 'old_string', 'new_string'],
+    },
+  },
+  {
+    name: 'multi_edit',
+    description:
+      'Several exact replacements in one file, applied in order, each seeing the ' +
+      'result of the last. Same rules as edit_file for each one. If any of them is ' +
+      'ambiguous or missing, none are written at all. Prefer this to calling ' +
+      'edit_file repeatedly on the same file.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: str('File path, relative to the project root.'),
+        edits: {
+          type: 'array',
+          description: 'The replacements, in the order they should be applied.',
+          items: {
+            type: 'object',
+            properties: {
+              old_string: str('The exact text to replace. Must be unique at that point.'),
+              new_string: str('What to put there instead.'),
+            },
+            required: ['old_string', 'new_string'],
+          },
+        },
+      },
+      required: ['path', 'edits'],
+    },
+  },
+  {
+    name: 'list_dir',
+    description: 'List what is in one directory, with file sizes.',
+    parameters: {
+      type: 'object',
+      properties: { path: str('Directory path. Defaults to the project root.') },
+      required: [],
+    },
+  },
+  {
+    name: 'glob',
+    description:
+      'Find files by name pattern, most recently changed first. Understands **, *, ? ' +
+      'and {a,b}. node_modules, .git, dist and similar are skipped unless the pattern ' +
+      'names one of them.',
+    parameters: {
+      type: 'object',
+      properties: {
+        pattern: str('Glob pattern, e.g. "src/**/*.{ts,tsx}".'),
+        path: str('Directory to look under. Defaults to the project root.'),
+      },
+      required: ['pattern'],
+    },
+  },
+  {
+    name: 'grep',
+    description:
+      'Search inside files with a regular expression. Returns file:line: text for ' +
+      'every match. Pass glob to limit which files get read.',
+    parameters: {
+      type: 'object',
+      properties: {
+        pattern: str('A JavaScript regular expression.'),
+        path: str('File or directory to search. Defaults to the project root.'),
+        glob: str('Optional filename filter, e.g. "**/*.js".'),
+        ignore_case: bool('Match case-insensitively. Defaults to false.'),
+      },
+      required: ['pattern'],
+    },
+  },
+  {
+    name: 'run_command',
+    description:
+      'Run a shell command and get back its output and exit code. It runs without ' +
+      'asking, so never run something destructive the user did not ask for. There is ' +
+      'no keyboard: pass the non-interactive flag to anything that would ask a question. ' +
+      'Dev servers (npm run dev, vite, next dev, uvicorn...) are started in the ' +
+      'background automatically and the result comes back as soon as the server says ' +
+      'it is ready, with the URL it is listening on - do not start one twice.',
+    parameters: {
+      type: 'object',
+      properties: {
+        command: str('The whole command line.'),
+        cwd: str('Directory to run it in. Defaults to the project root.'),
+        timeout_ms: int('Kill it after this many milliseconds. Default 120000.'),
+        background: bool('Start it detached and return its PID. For servers.'),
+      },
+      required: ['command'],
+    },
+  },
+  {
+    name: 'run_commands',
+    description:
+      'Run several shell commands at once, up to max_parallel at a time. Good for ' +
+      'independent work — install, lint and test together rather than one after ' +
+      'another. Each entry takes the same fields as run_command.',
+    parameters: {
+      type: 'object',
+      properties: {
+        commands: {
+          type: 'array',
+          description: 'The commands to run.',
+          items: {
+            type: 'object',
+            properties: {
+              command: str('The whole command line.'),
+              cwd: str('Directory to run it in. Defaults to the project root.'),
+              timeout_ms: int('Kill it after this many milliseconds. Default 120000.'),
+              background: bool('Start it detached and return its PID.'),
+            },
+            required: ['command'],
+          },
+        },
+        max_parallel: {
+          type: 'integer',
+          description: 'How many may run at once. Default 3.',
+          minimum: 1,
+          maximum: 10,
+        },
+      },
+      required: ['commands'],
+    },
+  },
+  {
+    name: 'web_search',
+    description:
+      'Search the web and get back titles, links and summaries. For anything the ' +
+      'project files and your own knowledge cannot settle: current versions, recent ' +
+      'releases, an unfamiliar error, documentation for an API you do not know. Cite ' +
+      'the URLs you actually used.',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: str('What to look up.'),
+        max_results: int('How many results, 1-10. Defaults to 5.'),
+      },
+      required: ['query'],
+    },
+  },
+];
+
+const run = {
+  read_file: readFile,
+  read_files: readFiles,
+  write_file: writeFile,
+  batch_write: batchWrite,
+  edit_file: editFile,
+  multi_edit: multiEdit,
+  list_dir: listDir,
+  glob,
+  grep,
+  run_command: runCommand,
+  run_commands: runCommands,
+  web_search: webSearch,
+};
+
+/** Tools that change the project or execute code. */
+export const MUTATING = new Set([
+  'write_file', 'batch_write', 'edit_file', 'multi_edit', 'run_command', 'run_commands',
+]);
+
+/** Tools with no side effects, so several may run at the same time. */
+export const PARALLEL_SAFE = new Set(['read_file', 'read_files', 'list_dir', 'glob', 'grep', 'web_search']);
+
+/** Tools withheld in plan mode. Withholding beats asking a model not to. */
+export const WRITES = new Set([
+  'write_file', 'batch_write', 'edit_file', 'multi_edit', 'run_command', 'run_commands',
+]);
+
+// ---------------------------------------------------------------------------
+// Argument checking
+// ---------------------------------------------------------------------------
+
+/**
+ * Check the model's arguments against the schema before anything runs.
+ *
+ * Catching it here means the model gets a precise sentence about what it got
+ * wrong and can correct itself, instead of a TypeError thrown from somewhere
+ * inside fs that means nothing to anybody.
+ */
+function check(name, args) {
+  const schema = tools.find((t) => t.name === name).parameters;
+  const problems = [];
+
+  if (args === null || typeof args !== 'object' || Array.isArray(args)) {
+    return ['the arguments must be a JSON object'];
+  }
+
+  for (const key of schema.required ?? []) {
+    if (args[key] === undefined || args[key] === null) problems.push(`"${key}" is required and missing`);
+  }
+
+  for (const [key, value] of Object.entries(args)) {
+    const spec = schema.properties[key];
+    if (!spec) {
+      problems.push(`"${key}" is not an argument of ${name} (it takes: ${Object.keys(schema.properties).join(', ')})`);
+      continue;
+    }
+    if (value === undefined || value === null) continue;
+
+    const actual = Array.isArray(value) ? 'array' : typeof value;
+    const wanted = spec.type === 'integer' ? 'number' : spec.type;
+    // A number sent as a string is close enough — the tool coerces it anyway.
+    if (wanted === 'number' && actual === 'string' && value.trim() !== '' && !Number.isNaN(Number(value))) continue;
+    if (actual !== wanted) problems.push(`"${key}" should be ${spec.type} but was ${actual}`);
+  }
+
+  return problems;
+}
+
+export async function runTool(name, args = {}, opts = {}) {
+  const impl = run[name];
+  if (!impl) {
+    throw new ToolFailure({
+      kind: 'no_such_tool',
+      attempted: `calling ${name}`,
+      failed: `There is no tool called "${name}".`,
+      fix: `The tools you have are: ${tools.map((t) => t.name).join(', ')}.`,
+    });
+  }
+
+  const problems = check(name, args);
+  if (problems.length) {
+    throw new ToolFailure({
+      kind: 'bad_args',
+      attempted: `calling ${name}`,
+      failed: `The arguments were wrong: ${problems.join('; ')}.`,
+      fix: `Call ${name} again with them corrected. Its schema is: ${JSON.stringify(
+        tools.find((t) => t.name === name).parameters
+      )}`,
+      detail: { problems },
+    });
+  }
+
+  return impl(args, opts);
+}
+
+/**
+ * The line shown while a call runs: "Listing src", "Running npm test".
+ *
+ * Present tense, no trailing full stop — it is a label on something happening
+ * now, not a sentence about something that happened. It is built from the call
+ * itself rather than from what the model said it would do, so it is always an
+ * account of the real work.
+ */
+export function describe(name, args = {}) {
+  switch (name) {
+    case 'read_file':
+      return `Reading ${clip(args.path)}${args.offset > 1 ? ` from line ${args.offset}` : ''}`;
+    case 'read_files': {
+      const names = (args.paths ?? []).map((p) => String(p));
+      const joined = names.join(', ');
+      return names.length && joined.length <= 60 ? `Reading ${joined}` : `Reading ${names.length} files`;
+    }
+    case 'write_file':
+      return `Writing ${clip(args.path)}`;
+    case 'batch_write': {
+      const n = args.files?.length ?? 0;
+      const first = args.files?.[0]?.path;
+      return n === 1 && first ? `Writing ${clip(first)}` : `Writing ${n} files`;
+    }
+    case 'edit_file':
+      return `Editing ${clip(args.path)}`;
+    case 'multi_edit':
+      return `Editing ${clip(args.path)}, ${args.edits?.length ?? 0} changes`;
+    case 'list_dir':
+      return !args.path || args.path === '.'
+        ? 'Listing the project root'
+        : `Listing ${clip(args.path)}`;
+    case 'glob':
+      return `Finding ${clip(args.pattern)}`;
+    case 'grep':
+      return `Searching for ${clip(args.pattern, 40)}${args.glob ? ` in ${clip(args.glob, 20)}` : ''}`;
+    case 'run_command':
+      return `Running ${clip(args.command, 70)}${args.background ? ' in the background' : ''}`;
+    case 'run_commands':
+      return `Running ${args.commands?.length ?? 0} commands together`;
+    case 'web_search':
+      return `Searching the web for ${clip(args.query, 60)}`;
+    case 'load_skill':
+      return `Loading the ${clip(args.name, 40)} skill`;
+    default:
+      return `${name} ${clip(JSON.stringify(args), 60)}`;
+  }
+}

package/src/tools/search.js

@@ -0,0 +1,192 @@
+/**
+ * search.js — finding things: what is in a directory, which files match a
+ * name pattern, and which lines match a regular expression.
+ */
+
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { ToolFailure } from '../core/failure.js';
+import {
+  resolveIn, guard, result, fsFailure, looksBinary, bytes, walk, globToRegExp,
+  SKIP, MAX_GLOB_HITS, MAX_GREP_HITS, WALK_WIDTH,
+} from './shared.js';
+
+export async function listDir({ path: p = '.' }) {
+  const target = resolveIn(p || '.', 'list_dir');
+  await guard(target, `list ${target.abs}`);
+  const attempted = `listing ${target.show}`;
+
+  let entries;
+  try {
+    entries = await fs.readdir(target.abs, { withFileTypes: true });
+  } catch (err) {
+    throw fsFailure(err, attempted, target.show);
+  }
+
+  const dirs = entries.filter((e) => e.isDirectory()).map((e) => `${e.name}/`);
+
+  // Every size looked up at once rather than one stat after another.
+  const files = await Promise.all(
+    entries
+      .filter((e) => !e.isDirectory())
+      .map(async (entry) => {
+        if (!entry.isFile()) return `${entry.name} (link or device)`;
+        try {
+          return `${entry.name} (${bytes((await fs.stat(path.join(target.abs, entry.name))).size)})`;
+        } catch {
+          // A file that disappeared between the listing and the stat is not
+          // worth failing the whole call over.
+          return entry.name;
+        }
+      })
+  );
+
+  dirs.sort();
+  files.sort();
+
+  return result(
+    `${target.show}/\n${[...dirs, ...files].join('\n') || '(empty)'}`,
+    `${dirs.length} dir${dirs.length === 1 ? '' : 's'}, ${files.length} file${files.length === 1 ? '' : 's'}`
+  );
+}
+
+export async function glob({ pattern, path: p = '.' }) {
+  if (typeof pattern !== 'string' || !pattern.trim()) {
+    throw new ToolFailure({
+      kind: 'bad_args',
+      attempted: 'matching files by name',
+      failed: 'The "pattern" argument was missing or empty.',
+      fix: 'Pass something like "**/*.js" or "src/**/*.{ts,tsx}".',
+    });
+  }
+
+  const target = resolveIn(p || '.', 'glob');
+  await guard(target, `search ${target.abs}`);
+
+  const re = globToRegExp(pattern.trim());
+  // If the pattern names an ignored folder outright, the user meant it.
+  const includeSkipped = [...SKIP].some((d) => pattern.includes(d));
+  const all = await walk(target.abs, { includeSkipped });
+  const matched = all.filter((rel) => re.test(rel));
+
+  if (matched.length === 0) {
+    return result(
+      `Nothing matched "${pattern}" under ${target.show}. Looked at ${all.length} files; ` +
+      'build and vendor folders are skipped unless the pattern names one.',
+      'no matches'
+    );
+  }
+
+  // Newest first: when hunting through an unfamiliar codebase, the files
+  // somebody touched recently are nearly always the ones that matter.
+  const dated = await Promise.all(
+    matched.slice(0, 2000).map(async (rel) => {
+      try {
+        return { rel, at: (await fs.stat(path.join(target.abs, rel))).mtimeMs };
+      } catch {
+        return { rel, at: 0 };
+      }
+    })
+  );
+  dated.sort((a, b) => b.at - a.at);
+
+  const shown = dated.slice(0, MAX_GLOB_HITS).map((f) => f.rel);
+  const extra = matched.length > shown.length
+    ? `\n[${matched.length - shown.length} more not shown]`
+    : '';
+
+  return result(
+    shown.join('\n') + extra,
+    `${matched.length} match${matched.length === 1 ? '' : 'es'}`
+  );
+}
+
+export async function grep({ pattern, path: p = '.', glob: filter, ignore_case = false }) {
+  if (typeof pattern !== 'string' || pattern === '') {
+    throw new ToolFailure({
+      kind: 'bad_args',
+      attempted: 'searching file contents',
+      failed: 'The "pattern" argument was missing or empty.',
+      fix: 'Pass a regular expression, for example "function\\\\s+\\\\w+".',
+    });
+  }
+
+  let re;
+  try {
+    re = new RegExp(pattern, ignore_case ? 'i' : '');
+  } catch (err) {
+    throw new ToolFailure({
+      kind: 'bad_args',
+      attempted: 'searching file contents',
+      failed: `"${pattern}" is not a valid regular expression: ${err.message}`,
+      fix: 'Escape the metacharacters ( . * + ? [ ] ( ) { } | \\ ) or use a simpler pattern.',
+      cause: err,
+    });
+  }
+
+  const target = resolveIn(p || '.', 'grep');
+  await guard(target, `search ${target.abs}`);
+
+  const stat = await fs.stat(target.abs).catch((err) => {
+    throw fsFailure(err, 'searching file contents', target.show);
+  });
+
+  let base = target.abs;
+  let candidates;
+  if (stat.isFile()) {
+    base = path.dirname(target.abs);
+    candidates = [path.basename(target.abs)];
+  } else {
+    candidates = await walk(target.abs);
+    if (filter) {
+      const fre = globToRegExp(filter);
+      candidates = candidates.filter((rel) => fre.test(rel));
+    }
+  }
+
+  const hits = [];
+  const inFiles = new Set();
+
+  // Files are read a batch at a time rather than one after another — the
+  // search itself is instant, it is the waiting on each read that adds up. The
+  // batch is scanned in its original order, so the same search always lists
+  // its matches the same way.
+  for (let at = 0; at < candidates.length && hits.length < MAX_GREP_HITS; at += WALK_WIDTH) {
+    const batch = candidates.slice(at, at + WALK_WIDTH);
+    const read = await Promise.all(batch.map((rel) =>
+      fs.readFile(path.join(base, rel)).then((buf) => ({ rel, buf }), () => ({ rel, buf: null }))
+    ));
+
+    for (const { rel, buf } of read) {
+      if (hits.length >= MAX_GREP_HITS) break;
+      if (!buf || looksBinary(buf.subarray(0, 4096))) continue;
+
+      const lines = buf.toString('utf8').split(/\r?\n/);
+      for (let i = 0; i < lines.length && hits.length < MAX_GREP_HITS; i++) {
+        re.lastIndex = 0;
+        if (!re.test(lines[i])) continue;
+        inFiles.add(rel);
+        const text = lines[i].trim();
+        hits.push(`${rel}:${i + 1}: ${text.length > 200 ? `${text.slice(0, 200)}…` : text}`);
+      }
+    }
+  }
+
+  if (hits.length === 0) {
+    return result(
+      `No line matched /${pattern}/ under ${target.show}` +
+      `${filter ? ` (limited to ${filter})` : ''}. Read ${candidates.length} files.`,
+      'no matches'
+    );
+  }
+
+  const capped = hits.length >= MAX_GREP_HITS
+    ? `\n[stopped at ${MAX_GREP_HITS} matches — narrow the pattern, or pass a glob]`
+    : '';
+
+  return result(
+    hits.join('\n') + capped,
+    `${hits.length} match${hits.length === 1 ? '' : 'es'} in ` +
+    `${inFiles.size} file${inFiles.size === 1 ? '' : 's'}`
+  );
+}