lazyclaw 4.2.2 → 5.0.0

package/mas/tools/os.mjs

@@ -0,0 +1,152 @@
+// os — clipboard, screenshot, notify, open_url, file_dialog. macOS and
+// linux paths implemented; everything else returns "unsupported".
+// ctx.platform overrideable for tests.
+
+import { spawn, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+function platformOf(ctx) { return ctx?.platform || process.platform; }
+
+function runCmd(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, opts);
+    let out = '', err = '';
+    child.stdout?.on('data', d => out += d.toString());
+    child.stderr?.on('data', d => err += d.toString());
+    child.on('error', e => resolve({ ok: false, error: e.message }));
+    child.on('close', code => resolve({ ok: code === 0, stdout: out, stderr: err, exitCode: code }));
+    if (opts.stdin) { child.stdin.write(opts.stdin); child.stdin.end(); }
+  });
+}
+
+const clipboard_read = {
+  name: 'clipboard_read', category: 'os', sensitive: true,
+  description: 'Read the OS clipboard (text).',
+  parameters: { type: 'object', properties: {} },
+  async exec(_args, ctx) {
+    const p = platformOf(ctx);
+    if (p === 'darwin') {
+      const r = spawnSync('pbpaste', [], { encoding: 'utf8' });
+      return r.status === 0 ? { ok: true, text: r.stdout } : { ok: false, error: r.stderr || 'pbpaste failed' };
+    }
+    if (p === 'linux') {
+      for (const [bin, args] of [['wl-paste', []], ['xclip', ['-selection', 'clipboard', '-o']], ['xsel', ['--clipboard', '--output']]]) {
+        const r = spawnSync(bin, args, { encoding: 'utf8' });
+        if (r.status === 0) return { ok: true, text: r.stdout };
+      }
+      return { ok: false, error: 'clipboard_read: no clipboard helper (install wl-clipboard or xclip)' };
+    }
+    return { ok: false, error: `clipboard_read: unsupported platform ${p}` };
+  },
+};
+
+const clipboard_write = {
+  name: 'clipboard_write', category: 'os', sensitive: true,
+  description: 'Write text to the OS clipboard.',
+  parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'] },
+  async exec(args, ctx) {
+    const p = platformOf(ctx);
+    if (p === 'darwin') return runCmd('pbcopy', [], { stdin: args.text });
+    if (p === 'linux') {
+      for (const [bin, ar] of [['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]]) {
+        const r = await runCmd(bin, ar, { stdin: args.text });
+        if (r.ok) return { ok: true };
+      }
+      return { ok: false, error: 'clipboard_write: no clipboard helper' };
+    }
+    return { ok: false, error: `clipboard_write: unsupported platform ${p}` };
+  },
+};
+
+const screenshot = {
+  name: 'screenshot', category: 'os', sensitive: true,
+  description: 'Capture a screenshot and write it to a PNG path (defaults to a tmpfile). Returns {path}.',
+  parameters: { type: 'object', properties: { path: { type: 'string' } } },
+  async exec(args, ctx) {
+    const p = platformOf(ctx);
+    const out = args?.path || path.join(os.tmpdir(), `lzc-${Date.now()}.png`);
+    if (p === 'darwin') {
+      const r = spawnSync('screencapture', ['-x', out]);
+      return r.status === 0 ? { ok: true, path: out } : { ok: false, error: 'screencapture failed' };
+    }
+    if (p === 'linux') {
+      for (const [bin, ar] of [['grim', [out]], ['gnome-screenshot', ['-f', out]], ['scrot', [out]]]) {
+        const r = spawnSync(bin, ar);
+        if (r.status === 0) return { ok: true, path: out };
+      }
+      return { ok: false, error: 'screenshot: no helper found (grim/gnome-screenshot/scrot)' };
+    }
+    return { ok: false, error: `screenshot: unsupported platform ${p}` };
+  },
+};
+
+const notify = {
+  name: 'notify', category: 'os', sensitive: false,
+  description: 'Post a desktop notification. Best-effort; failures do not surface to the user.',
+  parameters: {
+    type: 'object',
+    properties: { title: { type: 'string' }, body: { type: 'string' } },
+    required: ['title'],
+  },
+  async exec(args, ctx) {
+    const p = platformOf(ctx);
+    const title = args.title;
+    const body = args.body || '';
+    if (p === 'darwin') {
+      spawnSync('osascript', ['-e', `display notification ${JSON.stringify(body)} with title ${JSON.stringify(title)}`]);
+      return { ok: true };
+    }
+    if (p === 'linux') {
+      spawnSync('notify-send', [title, body]);
+      return { ok: true };
+    }
+    return { ok: false, error: `notify: unsupported platform ${p}` };
+  },
+};
+
+const open_url = {
+  name: 'open_url', category: 'os', sensitive: true,
+  description: 'Open a public URL in the default browser. http(s) only.',
+  parameters: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] },
+  async exec(args, ctx) {
+    try {
+      const u = new URL(args.url);
+      if (u.protocol !== 'http:' && u.protocol !== 'https:') return { ok: false, error: 'open_url: http(s) only' };
+    } catch { return { ok: false, error: 'open_url: bad URL' }; }
+    const p = platformOf(ctx);
+    if (p === 'darwin') return runCmd('open', [args.url]);
+    if (p === 'linux') return runCmd('xdg-open', [args.url]);
+    return { ok: false, error: `open_url: unsupported platform ${p}` };
+  },
+};
+
+const file_dialog = {
+  name: 'file_dialog', category: 'os', sensitive: true,
+  description: 'Show an OS file picker. Returns selected path (or null on cancel).',
+  parameters: {
+    type: 'object',
+    properties: { kind: { type: 'string', enum: ['open', 'save'] }, prompt: { type: 'string' } },
+  },
+  async exec(args, ctx) {
+    const p = platformOf(ctx);
+    if (p === 'darwin') {
+      const script = (args.kind === 'save')
+        ? 'POSIX path of (choose file name with prompt "' + (args.prompt || 'Save').replace(/"/g, '\\"') + '")'
+        : 'POSIX path of (choose file with prompt "'      + (args.prompt || 'Choose').replace(/"/g, '\\"') + '")';
+      const r = spawnSync('osascript', ['-e', script], { encoding: 'utf8' });
+      if (r.status !== 0) return { ok: true, path: null };
+      return { ok: true, path: r.stdout.trim() };
+    }
+    if (p === 'linux') {
+      const ar = args.kind === 'save' ? ['--file-selection', '--save'] : ['--file-selection'];
+      const r = spawnSync('zenity', ar, { encoding: 'utf8' });
+      if (r.status !== 0) return { ok: true, path: null };
+      return { ok: true, path: r.stdout.trim() };
+    }
+    return { ok: false, error: `file_dialog: unsupported platform ${p}` };
+  },
+};
+
+export const TOOLS = [clipboard_read, clipboard_write, screenshot, notify, open_url, file_dialog];

package/mas/tools/patch.mjs

@@ -0,0 +1,91 @@
+// patch — apply a unified-diff to one or more files. Uses a strict parser:
+// a hunk must match context lines exactly or the entire patch is rejected
+// so partial application can't corrupt the workspace.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const TOOL = {
+  name: 'patch',
+  category: 'fs',
+  sensitive: true,
+  description: 'Apply a unified-diff patch (multi-file allowed). Fails atomically on any context mismatch.',
+  parameters: {
+    type: 'object',
+    properties: { diff: { type: 'string', description: 'Unified diff body.' } },
+    required: ['diff'],
+  },
+  async exec(args, { cwd = process.cwd() } = {}) {
+    if (!args || typeof args.diff !== 'string' || !args.diff.trim()) return { ok: false, error: 'patch: diff required' };
+    const files = parseUnifiedDiff(args.diff);
+    if (!files.length) return { ok: false, error: 'patch: no file hunks parsed' };
+    const stage = []; // {abs, content}
+    for (const file of files) {
+      const abs = path.resolve(cwd, file.path);
+      if (!abs.startsWith(path.resolve(cwd))) return { ok: false, error: `patch: path escapes workspace: ${file.path}` };
+      let src;
+      try { src = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : ''; }
+      catch (e) { return { ok: false, error: `patch: read ${file.path}: ${e.message}` }; }
+      const applied = applyHunks(src, file.hunks);
+      if (!applied.ok) return { ok: false, error: `patch: ${file.path}: ${applied.error}` };
+      stage.push({ abs, content: applied.content });
+    }
+    for (const s of stage) fs.writeFileSync(s.abs, s.content);
+    return { ok: true, filesWritten: stage.length };
+  },
+};
+
+function parseUnifiedDiff(diff) {
+  const lines = diff.split('\n');
+  const out = [];
+  let i = 0;
+  while (i < lines.length) {
+    if (lines[i].startsWith('--- ') && lines[i + 1]?.startsWith('+++ ')) {
+      const newPath = lines[i + 1].slice(4).replace(/^b\//, '').trim();
+      i += 2;
+      const hunks = [];
+      while (i < lines.length && lines[i].startsWith('@@')) {
+        const header = lines[i++];
+        const body = [];
+        while (i < lines.length && !lines[i].startsWith('@@') && !lines[i].startsWith('--- ')) {
+          body.push(lines[i++]);
+        }
+        hunks.push({ header, body });
+      }
+      out.push({ path: newPath, hunks });
+    } else {
+      i++;
+    }
+  }
+  return out;
+}
+
+function applyHunks(src, hunks) {
+  let lines = src.split('\n');
+  let cursor = 0;
+  for (const hunk of hunks) {
+    const m = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(hunk.header);
+    if (!m) return { ok: false, error: `bad hunk header: ${hunk.header}` };
+    let lineIdx = Math.max(0, parseInt(m[1], 10) - 1);
+    const out = lines.slice(0, lineIdx);
+    for (const b of hunk.body) {
+      if (b === '') continue;
+      const op = b[0];
+      const text = b.slice(1);
+      if (op === ' ') {
+        if ((lines[lineIdx] ?? '') !== text) return { ok: false, error: `context mismatch at line ${lineIdx + 1}` };
+        out.push(text); lineIdx++;
+      } else if (op === '-') {
+        if ((lines[lineIdx] ?? '') !== text) return { ok: false, error: `delete mismatch at line ${lineIdx + 1}` };
+        lineIdx++;
+      } else if (op === '+') {
+        out.push(text);
+      } else if (op === '\\') {
+        //  — ignore
+      }
+    }
+    lines = out.concat(lines.slice(lineIdx));
+    cursor = lineIdx;
+  }
+  return { ok: true, content: lines.join('\n') };
+}

package/mas/tools/recall.mjs

@@ -0,0 +1,103 @@
+// recall tool — Phase B (v5 §4.5).
+//
+// FTS5-backed cross-scope recall. Reads from mas/index_db.mjs (the
+// SQLite mirror populated by Phase A's write-through hooks).
+//
+// Args:
+//   query:     required string
+//   scope:     optional array of 'sessions'|'skills'|'trajectories'|'memories'
+//              (default: all four)
+//   k:         optional integer, default 10, hard-capped at 50
+//   summarize: optional boolean (v5.1+ wires the trainer; v5.0 leaves
+//              summary null when set, so the agent gets raw hits.)
+//   filter:    optional object of UNINDEXED column equality filters
+//              (session_id, agent, outcome, trained_by, group_name, kind, since)
+
+import { openIndex, recall as indexRecall } from '../index_db.mjs';
+
+export const NAME = 'recall';
+export const DESCRIPTION =
+  'Search prior sessions, skills, trajectories, and memories by FTS5 query. Returns ranked snippets with metadata. Use this BEFORE asking the user to repeat themselves or before solving a problem from scratch.';
+export const PARAMETERS = {
+  type: 'object',
+  properties: {
+    query: { type: 'string', description: 'FTS5 MATCH query. Plain words are AND-ed.' },
+    scope: { type: 'array', items: { type: 'string', enum: ['sessions', 'skills', 'trajectories', 'memories'] } },
+    k: { type: 'integer', minimum: 1, maximum: 50 },
+    summarize: { type: 'boolean' },
+    filter: { type: 'object', additionalProperties: true },
+  },
+  required: ['query'],
+};
+
+const DEFAULT_SCOPES = ['sessions', 'skills', 'trajectories', 'memories'];
+const MAX_K = 50;
+
+let _stubRecall = null;
+export function __setRecall(fn) { _stubRecall = typeof fn === 'function' ? fn : null; }
+
+export async function exec(args, { configDir } = {}) {
+  if (!args || typeof args.query !== 'string' || !args.query.trim()) {
+    return { ok: false, error: 'recall: query is required' };
+  }
+  const query = args.query.trim();
+  const scopes = Array.isArray(args.scope) && args.scope.length ? args.scope : DEFAULT_SCOPES;
+  const k = Math.max(1, Math.min(MAX_K, Number(args.k) || 10));
+  const filter = args.filter && typeof args.filter === 'object' ? args.filter : {};
+  const t0 = Date.now();
+
+  let out;
+  if (_stubRecall) {
+    try {
+      out = await _stubRecall(query, { scope: scopes, k });
+    } catch (err) {
+      return { ok: false, error: `recall: stub threw — ${err?.message || err}` };
+    }
+  } else {
+    try {
+      openIndex(configDir);
+    } catch (err) {
+      return { ok: false, error: `recall: openIndex failed — ${err?.message || err}` };
+    }
+    try {
+      out = indexRecall(query, { configDir, scope: scopes, k });
+    } catch (err) {
+      return { ok: false, error: `recall: query failed — ${err?.message || err}` };
+    }
+  }
+
+  // Apply optional UNINDEXED filter (metadata-level equality / since predicate).
+  let hits = Array.isArray(out.hits) ? out.hits : [];
+  const filterKeys = Object.keys(filter);
+  if (filterKeys.length) {
+    hits = hits.filter((h) => {
+      const meta = h.metadata || {};
+      for (const key of filterKeys) {
+        if (key === 'since') {
+          if (Number(meta.ts || 0) < Number(filter.since)) return false;
+        } else if (String(meta[key] ?? '') !== String(filter[key])) {
+          return false;
+        }
+      }
+      return true;
+    });
+  }
+
+  return {
+    ok: true,
+    query,
+    hits: hits.slice(0, k),
+    summary: null,           // v5.0: raw hits only; v5.1 wires trainer.
+    summarizedBy: null,
+    latencyMs: Date.now() - t0,
+  };
+}
+
+export const TOOL = {
+  name: NAME,
+  category: 'learning',
+  sensitive: false,
+  description: DESCRIPTION,
+  parameters: PARAMETERS,
+  exec,
+};

package/mas/tools/registry.mjs

@@ -0,0 +1,93 @@
+// Tool registry — aggregates every first-party tool group plus any MCP-imported
+// tools so callers (tool_runner, splash renderer, agent toolset resolver) can
+// ask for them by name without knowing which file they live in.
+//
+// Each tool record: {name, category, sensitive, description, parameters, exec}
+//   - name: unique key (mcp tools use "mcp:<server>:<tool>")
+//   - category: 'exec' | 'fs' | 'net' | 'data' | 'agents' | 'learning' | ...
+//   - sensitive: when true, tool_runner requires `approve` hook before exec
+//   - parameters: JSON-Schema object (same shape as Phase 12a)
+//   - exec(args, ctx) -> {ok, ...}
+
+import * as bashTool from './bash.mjs';
+import * as readTool from './read.mjs';
+import * as writeTool from './write.mjs';
+import * as grepTool from './grep.mjs';
+
+function adaptLegacy(mod, { category, sensitive }) {
+  return {
+    name: mod.NAME,
+    category,
+    sensitive,
+    description: mod.DESCRIPTION,
+    parameters: mod.PARAMETERS,
+    exec: mod.exec,
+  };
+}
+
+// Built-in (Phase 12a) tools, adapted to v5 shape.
+const BUILTINS = [
+  adaptLegacy(bashTool,      { category: 'exec', sensitive: true  }),
+  adaptLegacy(readTool,      { category: 'fs',   sensitive: false }),
+  adaptLegacy(writeTool,     { category: 'fs',   sensitive: true  }),
+  adaptLegacy(grepTool,      { category: 'fs',   sensitive: false }),
+];
+
+import { TOOL as editTool }  from './edit.mjs';
+import { TOOL as patchTool } from './patch.mjs';
+import { TOOL as recallTool } from './recall.mjs';
+import { TOOLS as learningTools } from './learning.mjs';
+import { TOOLS as webTools } from './web.mjs';
+import { TOOLS as osTools } from './os.mjs';
+import { TOOLS as codingTools } from './coding.mjs';
+import { TOOLS as gitGroupTools } from './git.mjs';
+import { TOOLS as schedTools } from './scheduling.mjs';
+import { TOOLS as delTools } from './delegation.mjs';
+import { TOOLS as mediaTools } from './media.mjs';
+import { TOOLS as haTools } from './ha.mjs';
+import { TOOL  as clarifyTool } from './clarify.mjs';
+import { TOOLS as browserTools } from './browser.mjs';
+
+BUILTINS.push(editTool, patchTool);
+BUILTINS.push(recallTool);
+for (const t of learningTools) BUILTINS.push(t);
+for (const t of webTools) BUILTINS.push(t);
+for (const t of osTools) BUILTINS.push(t);
+for (const t of codingTools) BUILTINS.push(t);
+for (const t of gitGroupTools) BUILTINS.push(t);
+for (const t of schedTools) BUILTINS.push(t);
+for (const t of delTools) BUILTINS.push(t);
+for (const t of mediaTools) BUILTINS.push(t);
+for (const t of haTools) BUILTINS.push(t);
+BUILTINS.push(clarifyTool);
+for (const t of browserTools) BUILTINS.push(t);
+
+// Mutable; new groups (Tasks 2-14) push here; MCP client (Task 15) also pushes.
+const TOOLS = new Map();
+for (const t of BUILTINS) TOOLS.set(t.name, t);
+
+export function register(tool) {
+  if (!tool || typeof tool.name !== 'string') throw new Error('registry.register: tool.name required');
+  if (typeof tool.exec !== 'function')        throw new Error(`registry.register(${tool.name}): exec required`);
+  if (typeof tool.sensitive !== 'boolean')    throw new Error(`registry.register(${tool.name}): sensitive required`);
+  TOOLS.set(tool.name, tool);
+}
+
+export function registerGroup(group) {
+  if (!Array.isArray(group)) throw new Error('registry.registerGroup: array required');
+  for (const t of group) register(t);
+}
+
+export function unregister(name) { return TOOLS.delete(name); }
+
+export function lookup(name) { return TOOLS.get(name) || null; }
+
+export function listAll() { return [...TOOLS.values()]; }
+
+export function listNames() { return [...TOOLS.keys()]; }
+
+export function byCategory() {
+  const out = {};
+  for (const t of TOOLS.values()) (out[t.category] ||= []).push(t);
+  return out;
+}

package/mas/tools/scheduling.mjs

@@ -0,0 +1,62 @@
+// scheduling — cron_add / cron_remove / cron_list. Wraps cron.mjs but the
+// backend is overridable for tests via __setCronBackend.
+
+let _backend = null;
+export function __setCronBackend(b) { _backend = b; }
+
+async function getBackend() {
+  if (_backend) return _backend;
+  const cron = await import('../../cron.mjs').catch(() => null);
+  if (!cron) throw new Error('scheduling: cron.mjs not available');
+  return {
+    add:    async (j) => cron.add ? cron.add(j) : { ok: false, error: 'cron.add missing' },
+    list:   async ()  => cron.list ? cron.list() : [],
+    remove: async (n) => cron.remove ? cron.remove(n) : { ok: false, error: 'cron.remove missing' },
+  };
+}
+
+// Field-count validator independent of cron.mjs internals so we get a clean error.
+function looksLikeCronSpec(s) {
+  return typeof s === 'string' && s.trim().split(/\s+/).length === 5;
+}
+
+const cron_add = {
+  name: 'cron_add', category: 'scheduling', sensitive: true,
+  description: 'Schedule a recurring agent run or shell command.',
+  parameters: {
+    type: 'object',
+    properties: {
+      name:    { type: 'string' },
+      spec:    { type: 'string', description: '5-field cron spec.' },
+      command: { type: 'string' },
+    },
+    required: ['name', 'spec', 'command'],
+  },
+  async exec(args) {
+    if (!looksLikeCronSpec(args.spec)) return { ok: false, error: `cron_add: bad cron spec "${args.spec}"` };
+    const b = await getBackend();
+    return b.add({ name: args.name, spec: args.spec, command: args.command });
+  },
+};
+
+const cron_remove = {
+  name: 'cron_remove', category: 'scheduling', sensitive: true,
+  description: 'Remove a scheduled job by name.',
+  parameters: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+  async exec(args) {
+    const b = await getBackend();
+    return b.remove(args.name);
+  },
+};
+
+const cron_list = {
+  name: 'cron_list', category: 'scheduling', sensitive: true,
+  description: 'List scheduled jobs.',
+  parameters: { type: 'object', properties: {} },
+  async exec() {
+    const b = await getBackend();
+    return { ok: true, jobs: await b.list() };
+  },
+};
+
+export const TOOLS = [cron_add, cron_remove, cron_list];

package/mas/tools/skill_view.mjs

@@ -0,0 +1,43 @@
+// skill_view tool — Phase 20.
+//
+// Read-only progressive-disclosure loader: the mention-router injects a
+// compact skills *index* (name + one-line summary) into the system
+// prompt, and the agent calls skill_view to pull the FULL text of a
+// skill only when it decides one is relevant. This keeps skill bodies
+// out of the prompt until they're actually needed.
+//
+// Unlike bash/read/write/grep this tool is rooted at the lazyclaw
+// config dir (where skills live), not the task cwd, so it takes
+// configDir from the tool-runner opts rather than cwd.
+
+import * as skills from '../../skills.mjs';
+
+export const NAME = 'skill_view';
+export const DESCRIPTION =
+  'Load the full text of a named skill from the skills index (its When-to-Use, Procedure, Pitfalls and Verification sections). Call this when a skill listed in the index looks relevant to the current task.';
+export const PARAMETERS = {
+  type: 'object',
+  properties: {
+    name: { type: 'string', description: 'The skill name exactly as shown in the skills index.' },
+  },
+  required: ['name'],
+};
+
+export async function exec(args, { configDir } = {}) {
+  if (!args || typeof args.name !== 'string' || !args.name.trim()) {
+    return { ok: false, error: 'skill_view: name is required' };
+  }
+  const name = args.name.trim();
+  try {
+    const content = skills.loadSkill(name, configDir);
+    // Record the recall so the curator can age out never-used skills.
+    // Best-effort: a usage-write hiccup must never fail the tool call.
+    try {
+      const curator = await import('../../skills_curator.mjs');
+      curator.recordUsage(name, configDir, Date.now());
+    } catch { /* non-fatal */ }
+    return { ok: true, name, content };
+  } catch (err) {
+    return { ok: false, error: `skill_view: ${err?.message || err}` };
+  }
+}

package/mas/tools/web.mjs

@@ -0,0 +1,137 @@
+// web — web_fetch (undici, SSRF block), web_search (Brave/Tavily/SerpAPI when
+// an API key env var is set), url_extract (extract links from HTML).
+// SSRF policy: reject loopback, RFC1918 private, link-local, file:, ftp:,
+// and any non-http(s) scheme.
+
+import { fetch } from 'undici';
+import dns from 'node:dns/promises';
+
+const PRIVATE_V4 = [
+  /^10\./, /^192\.168\./, /^172\.(1[6-9]|2\d|3[0-1])\./,
+  /^127\./, /^169\.254\./, /^0\./, /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./,
+];
+
+async function isSafeUrl(url) {
+  let u;
+  try { u = new URL(url); } catch { return { ok: false, error: 'bad URL' }; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return { ok: false, error: `scheme ${u.protocol} blocked` };
+  const host = u.hostname.replace(/^\[|\]$/g, '');
+  if (host === 'localhost' || host === '0.0.0.0') return { ok: false, error: 'loopback blocked (SSRF)' };
+  if (PRIVATE_V4.some(re => re.test(host))) return { ok: false, error: 'private address blocked (SSRF)' };
+  if (host.includes(':')) return { ok: false, error: 'IPv6 disabled' };
+  if (!/^[a-z0-9.-]+$/i.test(host)) return { ok: false, error: 'bad host' };
+  try {
+    const addrs = await dns.lookup(host, { all: true });
+    for (const a of addrs) {
+      if (PRIVATE_V4.some(re => re.test(a.address))) return { ok: false, error: 'resolves to private address (SSRF)' };
+      if (a.address === '127.0.0.1' || a.address === '::1') return { ok: false, error: 'resolves to loopback (SSRF)' };
+    }
+  } catch (e) {
+    return { ok: false, error: `dns: ${e.message}` };
+  }
+  return { ok: true };
+}
+
+const web_fetch = {
+  name: 'web_fetch', category: 'net', sensitive: true,
+  description: 'Fetch a public URL. Loopback / private / non-http(s) URLs are blocked.',
+  parameters: {
+    type: 'object',
+    properties: {
+      url:     { type: 'string' },
+      method:  { type: 'string', enum: ['GET', 'POST'] },
+      headers: { type: 'object' },
+      body:    { type: 'string' },
+      maxBytes:{ type: 'number' },
+    },
+    required: ['url'],
+  },
+  async exec(args) {
+    const safe = await isSafeUrl(args.url);
+    if (!safe.ok) return { ok: false, error: `web_fetch: ${safe.error}` };
+    const maxBytes = Math.min(args.maxBytes || 2_000_000, 5_000_000);
+    try {
+      const res = await fetch(args.url, {
+        method: args.method || 'GET',
+        headers: args.headers || {},
+        body: args.body,
+        redirect: 'follow',
+      });
+      const buf = Buffer.from(await res.arrayBuffer());
+      const truncated = buf.length > maxBytes;
+      return {
+        ok: true, status: res.status,
+        headers: Object.fromEntries(res.headers),
+        body: buf.slice(0, maxBytes).toString('utf8'),
+        truncated,
+      };
+    } catch (e) { return { ok: false, error: `web_fetch: ${e.message}` }; }
+  },
+};
+
+const web_search = {
+  name: 'web_search', category: 'net', sensitive: false,
+  description: 'Search the public web via Brave (BRAVE_API_KEY), Tavily (TAVILY_API_KEY), or SerpAPI (SERPAPI_API_KEY).',
+  parameters: {
+    type: 'object',
+    properties: { query: { type: 'string' }, k: { type: 'number' } },
+    required: ['query'],
+  },
+  async exec(args, ctx) {
+    const env = ctx?.env || process.env;
+    if (env.BRAVE_API_KEY) return braveSearch(args, env.BRAVE_API_KEY);
+    if (env.TAVILY_API_KEY) return tavilySearch(args, env.TAVILY_API_KEY);
+    if (env.SERPAPI_API_KEY) return serpApiSearch(args, env.SERPAPI_API_KEY);
+    return { ok: false, error: 'web_search: no provider configured (set BRAVE_API_KEY / TAVILY_API_KEY / SERPAPI_API_KEY)' };
+  },
+};
+
+async function braveSearch({ query, k = 5 }, key) {
+  try {
+    const r = await fetch(`https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${k}`, {
+      headers: { 'X-Subscription-Token': key, 'Accept': 'application/json' },
+    });
+    const j = await r.json();
+    return { ok: true, results: (j?.web?.results || []).slice(0, k).map(x => ({ title: x.title, url: x.url, snippet: x.description })) };
+  } catch (e) { return { ok: false, error: `brave: ${e.message}` }; }
+}
+async function tavilySearch({ query, k = 5 }, key) {
+  try {
+    const r = await fetch('https://api.tavily.com/search', {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ api_key: key, query, max_results: k }),
+    });
+    const j = await r.json();
+    return { ok: true, results: (j?.results || []).slice(0, k).map(x => ({ title: x.title, url: x.url, snippet: x.content })) };
+  } catch (e) { return { ok: false, error: `tavily: ${e.message}` }; }
+}
+async function serpApiSearch({ query, k = 5 }, key) {
+  try {
+    const r = await fetch(`https://serpapi.com/search.json?q=${encodeURIComponent(query)}&num=${k}&api_key=${key}`);
+    const j = await r.json();
+    return { ok: true, results: (j?.organic_results || []).slice(0, k).map(x => ({ title: x.title, url: x.link, snippet: x.snippet })) };
+  } catch (e) { return { ok: false, error: `serpapi: ${e.message}` }; }
+}
+
+const url_extract = {
+  name: 'url_extract', category: 'net', sensitive: false,
+  description: 'Extract all href URLs from an HTML string.',
+  parameters: {
+    type: 'object',
+    properties: { html: { type: 'string' }, base: { type: 'string' } },
+    required: ['html'],
+  },
+  async exec(args) {
+    const urls = new Set();
+    const re = /href\s*=\s*["']([^"']+)["']/gi;
+    let m;
+    while ((m = re.exec(args.html))) {
+      try {
+        urls.add(args.base ? new URL(m[1], args.base).toString() : m[1]);
+      } catch { urls.add(m[1]); }
+    }
+    return { ok: true, urls: [...urls] };
+  },
+};
+
+export const TOOLS = [web_fetch, web_search, url_extract];