lazyclaw 4.3.0 → 5.0.1

package/mas/skill_synth.mjs

@@ -18,6 +18,8 @@
 import * as skills from '../skills.mjs';
 import { runTextCompletion } from './provider_adapters.mjs';
 import { redactSecrets, neutralizeRoleLabels } from './redact.mjs';
+import { indexSkill as _indexSkill } from './index_db.mjs';
+import { parseFrontmatter } from '../skills.mjs';
 
 const SECTION_RE = /^#{1,6}\s+/;
 const MAX_NAME_LEN = 48;
@@ -106,23 +108,69 @@ export function parseSynthOutput(text) {
 }
 
 // Build a complete SKILL.md: a flat-YAML frontmatter block followed by
-// the skill body. The frontmatter shape round-trips through
+// the skill body. v5: adds trained_by / trained_on_model / trajectory_ref /
+// confidence / cross_cli_tested (array) / anti_pattern (boolean) and a
+// group fallback. The frontmatter shape round-trips through
 // skills.parseFrontmatter(). `ts` is injected (not read from the clock)
 // so the output is deterministic and testable.
-export function assembleSkillDoc({ name, description = '', createdBy = 'agent', sourceTask = '', body = '', version = 1, ts = new Date() } = {}) {
+export function assembleSkillDoc({
+  name,
+  description = '',
+  createdBy = 'agent',
+  sourceTask = '',
+  body = '',
+  version = 1,
+  ts = new Date(),
+  // v5 additions:
+  trainedBy = null,
+  trainedOnModel = null,
+  trajectoryRef = null,
+  confidence = null,
+  crossCliTested = null,   // array of {provider, model, outcome, tested_at}
+  outcome = 'done',         // 'done' | 'failed' | 'abandoned'  (spec §0.1 C1)
+  group = null,
+} = {}) {
   const date = (ts instanceof Date ? ts : new Date(ts)).toISOString().slice(0, 10);
+  const isAntiPattern = outcome === 'failed';
+  const finalGroup = group || (isAntiPattern ? 'anti-pattern' : deriveGroup(name));
   const fm = [
     '---',
     `name: ${escapeYaml(stripControl(name))}`,
     `description: ${escapeYaml(description)}`,
     `version: ${version}`,
+    `group: ${escapeYaml(finalGroup)}`,
     `created_by: ${createdBy}`,
   ];
   if (sourceTask) fm.push(`source_task: ${sourceTask}`);
-  fm.push(`created_at: ${date}`, '---', '');
+  fm.push(`created_at: ${date}`);
+  if (trainedBy) fm.push(`trained_by: ${escapeYaml(trainedBy)}`);
+  if (trainedOnModel) fm.push(`trained_on_model: ${escapeYaml(trainedOnModel)}`);
+  if (trajectoryRef) fm.push(`trajectory_ref: ${escapeYaml(trajectoryRef)}`);
+  if (confidence !== null && confidence !== undefined) {
+    fm.push(`confidence: ${Number(confidence).toFixed(2)}`);
+  }
+  if (isAntiPattern) fm.push(`anti_pattern: true`);
+  if (Array.isArray(crossCliTested) && crossCliTested.length) {
+    fm.push('cross_cli_tested:');
+    for (const t of crossCliTested) {
+      fm.push(`  - provider: ${escapeYaml(t.provider || '')}`);
+      if (t.model) fm.push(`    model: ${escapeYaml(t.model)}`);
+      if (t.outcome) fm.push(`    outcome: ${escapeYaml(t.outcome)}`);
+      if (t.tested_at) fm.push(`    tested_at: ${escapeYaml(t.tested_at)}`);
+    }
+  }
+  fm.push('---', '');
   return `${fm.join('\n')}\n${String(body).trim()}\n`;
 }
 
+// Canonical fallback (spec §0.1 C5): filename hyphen prefix → 'legacy'.
+function deriveGroup(name) {
+  const s = String(name || '');
+  const dash = s.indexOf('-');
+  if (dash > 0) return s.slice(0, dash);
+  return 'legacy';
+}
+
 // Drop control characters (incl. newlines) from a single-line frontmatter
 // value so an embedded \n can't break out of its key into an injected one.
 function stripControl(v) {
@@ -157,43 +205,39 @@ export class SkillSynthError extends Error {
 // completion with no tools advertised, the agent's own role as the
 // system prompt. The difference is the ASK — a reusable skill in a
 // fixed section layout instead of free-text lessons.
-export async function synthesizeSkill({ agent, task, apiKey, baseUrl, fetchImpl } = {}) {
+export async function synthesizeSkill({
+  agent, task, apiKey, baseUrl, fetchImpl,
+  outcome = 'done',
+  trainedBy = null,
+  trainedOnModel = null,
+  trajectoryRef = null,
+  confidence = null,
+  crossCliTested = null,
+} = {}) {
   if (!agent || !task) throw new SkillSynthError('agent and task are required', 'SKILL_SYNTH_BAD_INPUT');
+  if (outcome !== 'done' && outcome !== 'failed' && outcome !== 'abandoned') {
+    throw new SkillSynthError(`bad outcome "${outcome}"`, 'SKILL_SYNTH_BAD_OUTCOME');
+  }
 
-  // Redact secrets from the transcript BEFORE it leaves for the model,
-  // so a token pasted into the task never reaches the LLM or the file.
   const transcript = redactSecrets(
     (Array.isArray(task.turns) ? task.turns : [])
       .map((t) => {
         const who = t.agent === 'user' ? 'User' : t.agent === 'system' ? 'System' : t.agent;
-        // Defang any forged role label inside the (model-controlled) body
-        // so a turn can't inject its own [System]/[User] authority line.
         return `[${who}] ${neutralizeRoleLabels(t.text || '')}`;
       })
       .join('\n\n') || '(no turns)'
   );
 
-  const userMessage =
-    `You just finished task "${task.title || '(untitled)'}" (id ${task.id}). Here is the full transcript:\n\n` +
-    transcript +
-    `\n\nDistil this into a REUSABLE skill that a future agent could load to handle a similar task faster. ` +
-    `Reply in EXACTLY this format and nothing else:\n\n` +
-    `name: <short kebab-case skill name>\n` +
-    `description: <one line, ≤ 120 chars, describing WHEN this skill applies>\n\n` +
-    `## When to Use\n<bullet conditions that signal this skill is relevant>\n\n` +
-    `## Procedure\n<numbered, concrete steps — real file paths / commands where known>\n\n` +
-    `## Pitfalls\n<gotchas and dead-ends you hit, so next time they're avoided>\n\n` +
-    `## Verification\n<how to confirm the task actually succeeded>\n\n` +
-    `Be concrete and specific to what happened. If the task was too trivial to be worth a reusable skill, reply with the single word NONE.`;
+  const userMessage = outcome === 'failed'
+    ? buildAntiPatternPrompt(task, transcript)
+    : buildSkillPrompt(task, transcript);
 
   const text = (await runTextCompletion({
     provider: agent.provider,
     model: agent.model,
     system: agent.role || '',
     userMessage,
-    apiKey,
-    baseUrl,
-    fetchImpl,
+    apiKey, baseUrl, fetchImpl,
   })).trim();
   if (!text || /^none\b/i.test(text)) return null;
 
@@ -201,8 +245,51 @@ export async function synthesizeSkill({ agent, task, apiKey, baseUrl, fetchImpl
   const description = sanitizeDescription(parsed.description);
   const body = sanitizeSkillBody(parsed.body);
   if (!body.trim()) return null;
-  const doc = assembleSkillDoc({ name: parsed.name, description, createdBy: 'agent', sourceTask: task.id, body });
-  return { name: parsed.name, description, body, doc, sourceTask: task.id };
+  const doc = assembleSkillDoc({
+    name: parsed.name,
+    description,
+    createdBy: 'agent',
+    sourceTask: task.id,
+    body,
+    outcome,
+    trainedBy,
+    trainedOnModel,
+    trajectoryRef,
+    confidence,
+    crossCliTested,
+  });
+  return { name: parsed.name, description, body, doc, sourceTask: task.id, outcome };
+}
+
+function buildSkillPrompt(task, transcript) {
+  return (
+    `You just finished task "${task.title || '(untitled)'}" (id ${task.id}). Here is the full transcript:\n\n` +
+    transcript +
+    `\n\nDistil this into a REUSABLE skill that a future agent could load to handle a similar task faster. ` +
+    `Reply in EXACTLY this format and nothing else:\n\n` +
+    `name: <short kebab-case skill name>\n` +
+    `description: <one line, ≤ 120 chars, describing WHEN this skill applies>\n\n` +
+    `## When to Use\n<bullet conditions that signal this skill is relevant>\n\n` +
+    `## Procedure\n<numbered, concrete steps — real file paths / commands where known>\n\n` +
+    `## Pitfalls\n<gotchas and dead-ends you hit, so next time they're avoided>\n\n` +
+    `## Verification\n<how to confirm the task actually succeeded>\n\n` +
+    `Be concrete and specific to what happened. If the task was too trivial to be worth a reusable skill, reply with the single word NONE.`
+  );
+}
+
+function buildAntiPatternPrompt(task, transcript) {
+  return (
+    `Task "${task.title || '(untitled)'}" (id ${task.id}) FAILED. Transcript:\n\n` +
+    transcript +
+    `\n\nDistil this into an ANTI-PATTERN note that a future agent will read and avoid. ` +
+    `Reply in EXACTLY this format and nothing else:\n\n` +
+    `name: <short kebab-case anti-pattern name, prefixed with "avoid-">\n` +
+    `description: <one line, ≤ 120 chars, describing the failure mode to avoid>\n\n` +
+    `## What Failed\n<concrete description of what was attempted and how it broke>\n\n` +
+    `## Why\n<root cause, with file paths or error messages where known>\n\n` +
+    `## Avoid\n<the rule the next agent should follow instead>\n\n` +
+    `Be specific. If the failure was too transient to generalise, reply with the single word NONE.`
+  );
 }
 
 // Install a synthesised skill without ever clobbering a human-authored
@@ -228,5 +315,17 @@ export function installSynthesized({ name, description = '', body = '', sourceTa
     ts,
   });
   const p = skills.installSkill(finalName, doc, configDir);
+  // Phase A: FTS5 mirror (spec §4.4). Group fallback per canonical C5.
+  try {
+    const { meta, body: skillBody } = parseFrontmatter(doc);
+    const group = meta.group
+      || (finalName.includes('-') ? finalName.split('-')[0] : 'legacy');
+    _indexSkill({
+      skill_name: finalName,
+      trained_by: meta.trained_by || createdBy === 'agent' ? 'agent' : 'user',
+      group_name: group,
+      content: skillBody,
+    }, configDir);
+  } catch { /* swallow */ }
   return { skill: finalName, path: p, version };
 }

package/mas/tool_runner.mjs

@@ -2,17 +2,8 @@
 // the agent is allowed to use the tool, runs the tool, audits the call,
 // and returns a uniform { ok, result?, error? } shape that the provider
 // adapters serialise into their respective tool-result content blocks.
-//
-// `bash`, `read`, `write`, `grep` ship with Phase 12a. `web_search`,
-// `web_fetch`, `slack_post` are advertised in the registry's
-// metadata-only entry so the dashboard can show them, but their `exec`
-// throws TOOL_NOT_IMPLEMENTED until later phases wire them up.
 
-import * as bashTool from './tools/bash.mjs';
-import * as readTool from './tools/read.mjs';
-import * as writeTool from './tools/write.mjs';
-import * as grepTool from './tools/grep.mjs';
-import * as skillViewTool from './tools/skill_view.mjs';
+import * as registry from './tools/registry.mjs';
 import * as audit from './audit.mjs';
 
 export class ToolError extends Error {
@@ -23,72 +14,30 @@ export class ToolError extends Error {
   }
 }
 
-const TOOLS = {
-  bash: bashTool,
-  read: readTool,
-  write: writeTool,
-  grep: grepTool,
-  skill_view: skillViewTool,
-};
-
-const NOT_IMPLEMENTED_TOOLS = ['web_search', 'web_fetch', 'slack_post'];
-
 export function listToolSchemas(names) {
   const out = [];
-  const wanted = Array.isArray(names) && names.length ? names : Object.keys(TOOLS);
+  const wanted = Array.isArray(names) && names.length ? names : registry.listNames();
   for (const name of wanted) {
-    const t = TOOLS[name];
+    const t = registry.lookup(name);
     if (!t) continue;
-    out.push({ name: t.NAME, description: t.DESCRIPTION, parameters: t.PARAMETERS });
+    out.push({ name: t.name, description: t.description, parameters: t.parameters });
   }
   return out;
 }
 
-export function isImplemented(name) {
-  return Boolean(TOOLS[name]);
-}
-
-export function knownTool(name) {
-  return TOOLS[name] !== undefined || NOT_IMPLEMENTED_TOOLS.includes(name);
-}
-
-// Run one tool call. The agent record's `tools` field is the whitelist;
-// when the call falls outside it, we throw ToolError('TOOL_DENIED') so
-// the caller can surface a structured error back to the LLM rather than
-// silently dropping the call.
-//
-// Tools that mutate state / run arbitrary code. When an `approve` hook is
-// supplied (e.g. backed by the gateway's remote exec-approval), these are
-// gated on a human decision before they run; read-only tools are not.
-const SENSITIVE_TOOLS = new Set(['bash', 'write']);
+export function isImplemented(name) { return registry.lookup(name) !== null; }
+export function knownTool(name)     { return registry.lookup(name) !== null; }
 
-// opts.cwd — where bash/read/write/grep root themselves; defaults to
-// process.cwd() so it can be overridden in tests.
-// opts.taskId — when set, every call is appended to the task's audit
-// log. Unit tests can omit it.
-// opts.approve — optional async (call) => { approved, reason }. When
-// present, a sensitive tool call is held until it resolves; a non-approval
-// blocks the tool (returns a structured error instead of executing).
 export async function runTool({ agent, tool, args, taskId, configDir, cwd, approve } = {}) {
   if (!agent || !Array.isArray(agent.tools)) {
     throw new ToolError('agent record with .tools[] is required', 'TOOL_BAD_AGENT');
   }
-  if (!knownTool(tool)) {
-    throw new ToolError(`unknown tool "${tool}"`, 'TOOL_UNKNOWN');
-  }
+  const impl = registry.lookup(tool);
+  if (!impl) throw new ToolError(`unknown tool "${tool}"`, 'TOOL_UNKNOWN');
   if (!agent.tools.includes(tool)) {
     throw new ToolError(`agent "${agent.name}" is not allowed to call tool "${tool}" (whitelist=[${agent.tools.join(', ')}])`, 'TOOL_DENIED');
   }
-  const impl = TOOLS[tool];
-  if (!impl) {
-    // Known but not yet implemented (web_search etc.) — Phase 12+x will fill in.
-    const result = { ok: false, error: `tool "${tool}" is registered but not implemented yet` };
-    audit.append({ taskId, agent: agent.name, tool, args, result, ok: false, configDir });
-    return result;
-  }
-  // Human-in-the-loop gate for sensitive tools. A denial (or an erroring
-  // hook — fail closed) blocks execution and is audited like any result.
-  if (typeof approve === 'function' && SENSITIVE_TOOLS.has(tool)) {
+  if (typeof approve === 'function' && impl.sensitive) {
     let verdict;
     try { verdict = await approve({ tool, args, agent: agent.name }); }
     catch (err) { verdict = { approved: false, reason: `approval error: ${err?.message || err}` }; }
@@ -100,7 +49,7 @@ export async function runTool({ agent, tool, args, taskId, configDir, cwd, appro
   }
   let result;
   try {
-    result = await impl.exec(args || {}, { cwd: cwd || process.cwd(), configDir });
+    result = await impl.exec(args || {}, { cwd: cwd || process.cwd(), configDir, taskId, agent });
   } catch (err) {
     result = { ok: false, error: `${tool} threw: ${err?.message || err}` };
   }

package/mas/tools/browser.mjs

@@ -0,0 +1,77 @@
+// browser — playwright-driven browser_navigate / click / back / screenshot.
+// Playwright is already a devDep (playwright.config.ts); we lazy-import and
+// return a structured error if it is missing at runtime. A persistent
+// headless Chromium context is reused across calls in the same process.
+
+let _backend = null;
+export function __setBrowserBackend(b) { _backend = b; }
+
+let _ctx = null;
+async function ensureCtx() {
+  if (_backend) return _backend;
+  if (_ctx) return _ctx;
+  let pw;
+  try { pw = await import('playwright'); }
+  catch { throw new Error('browser: playwright not installed (npm i playwright)'); }
+  const browser = await pw.chromium.launch({ headless: true });
+  const context = await browser.newContext();
+  const page = await context.newPage();
+  _ctx = {
+    navigate: async (url) => { await page.goto(url, { waitUntil: 'domcontentloaded' }); return { url: page.url(), title: await page.title() }; },
+    click:    async (sel) => { await page.click(sel); return { clicked: sel }; },
+    back:     async () => { await page.goBack(); return { url: page.url() }; },
+    screenshot: async (path) => { await page.screenshot({ path, fullPage: true }); return { path }; },
+  };
+  return _ctx;
+}
+
+function safeHttp(url) {
+  try {
+    const u = new URL(url);
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') return false;
+    return true;
+  } catch { return false; }
+}
+
+const browser_navigate = {
+  name: 'browser_navigate', category: 'browser', sensitive: true,
+  description: 'Navigate to an http(s) URL in a headless Chromium session.',
+  parameters: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] },
+  async exec(args) {
+    if (!safeHttp(args.url)) return { ok: false, error: 'browser_navigate: http(s) only' };
+    try { const ctx = await ensureCtx(); return { ok: true, ...(await ctx.navigate(args.url)) }; }
+    catch (e) { return { ok: false, error: `browser_navigate: ${e.message}` }; }
+  },
+};
+
+const browser_click = {
+  name: 'browser_click', category: 'browser', sensitive: true,
+  description: 'Click an element by CSS selector.',
+  parameters: { type: 'object', properties: { selector: { type: 'string' } }, required: ['selector'] },
+  async exec(args) {
+    try { const ctx = await ensureCtx(); return { ok: true, ...(await ctx.click(args.selector)) }; }
+    catch (e) { return { ok: false, error: `browser_click: ${e.message}` }; }
+  },
+};
+
+const browser_back = {
+  name: 'browser_back', category: 'browser', sensitive: true,
+  description: 'Navigate back in browser history.',
+  parameters: { type: 'object', properties: {} },
+  async exec() {
+    try { const ctx = await ensureCtx(); return { ok: true, ...(await ctx.back()) }; }
+    catch (e) { return { ok: false, error: `browser_back: ${e.message}` }; }
+  },
+};
+
+const browser_screenshot = {
+  name: 'browser_screenshot', category: 'browser', sensitive: true,
+  description: 'Capture a full-page PNG to <path>.',
+  parameters: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
+  async exec(args) {
+    try { const ctx = await ensureCtx(); return { ok: true, ...(await ctx.screenshot(args.path)) }; }
+    catch (e) { return { ok: false, error: `browser_screenshot: ${e.message}` }; }
+  },
+};
+
+export const TOOLS = [browser_navigate, browser_click, browser_back, browser_screenshot];

package/mas/tools/clarify.mjs

@@ -0,0 +1,36 @@
+// clarify — surface a question to the human user mid-turn. The actual
+// prompting mechanism is host-dependent (REPL prompt, Slack DM, gateway
+// SSE), so the runtime hooks an asker via __setAsker. Returns the user's
+// reply as a plain string. Pattern lifted from Hermes (spec §7 sub-12).
+
+let _asker = null;
+export function __setAsker(fn) { _asker = fn; }
+
+export const TOOL = {
+  name: 'clarify',
+  category: 'agents',
+  sensitive: false,
+  description: 'Ask the user a clarifying question and wait for the reply.',
+  parameters: {
+    type: 'object',
+    properties: { question: { type: 'string' }, choices: { type: 'array', items: { type: 'string' } } },
+    required: ['question'],
+  },
+  async exec(args, ctx) {
+    if (!args?.question) return { ok: false, error: 'clarify: question required' };
+    if (typeof _asker === 'function') {
+      try {
+        const answer = await _asker({ question: args.question, choices: args.choices });
+        return { ok: true, answer };
+      } catch (e) { return { ok: false, error: `clarify: ${e.message}` }; }
+    }
+    if (ctx?.isTTY) {
+      const readline = await import('node:readline/promises');
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const answer = await rl.question(`[clarify] ${args.question} > `);
+      rl.close();
+      return { ok: true, answer };
+    }
+    return { ok: false, error: 'clarify: no asker bound and not running in a TTY' };
+  },
+};

package/mas/tools/coding.mjs

@@ -0,0 +1,109 @@
+// coding — sandboxed code runners (python_exec, node_exec), data tools
+// (sql_query stub, http_request that reuses web_fetch SSRF policy),
+// and a pure helper (regex_match).
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { TOOLS as webTools } from './web.mjs';
+
+function runProc(cmd, args, opts = {}) {
+  return new Promise(resolve => {
+    let p;
+    try { p = spawn(cmd, args, { cwd: opts.cwd, env: opts.env || process.env }); }
+    catch (e) { return resolve({ ok: false, error: e.message }); }
+    let out = '', err = '';
+    const timeout = setTimeout(() => { try { p.kill('SIGKILL'); } catch {} }, opts.timeoutMs || 30_000);
+    p.on('error', e => { clearTimeout(timeout); resolve({ ok: false, error: e.message }); });
+    p.stdout?.on('data', d => out += d.toString());
+    p.stderr?.on('data', d => err += d.toString());
+    p.on('close', code => { clearTimeout(timeout); resolve({ ok: code === 0, stdout: out, stderr: err, exitCode: code }); });
+    if (opts.stdin != null) { p.stdin.write(opts.stdin); p.stdin.end(); }
+  });
+}
+
+const python_exec = {
+  name: 'python_exec', category: 'coding', sensitive: true,
+  description: 'Run a Python snippet in a sandboxed subprocess. 30s timeout.',
+  parameters: {
+    type: 'object',
+    properties: { code: { type: 'string' }, timeoutMs: { type: 'number' } },
+    required: ['code'],
+  },
+  async exec(args, ctx) {
+    const py = ctx?.python || process.env.LAZYCLAW_PYTHON || 'python3';
+    return runProc(py, ['-c', args.code], { cwd: ctx?.cwd, timeoutMs: args.timeoutMs });
+  },
+};
+
+const node_exec = {
+  name: 'node_exec', category: 'coding', sensitive: true,
+  description: 'Run a Node.js snippet in a sandboxed subprocess. 30s timeout.',
+  parameters: {
+    type: 'object',
+    properties: { code: { type: 'string' }, timeoutMs: { type: 'number' } },
+    required: ['code'],
+  },
+  async exec(args, ctx) {
+    const node = ctx?.node || process.execPath;
+    return runProc(node, ['-e', args.code], { cwd: ctx?.cwd, timeoutMs: args.timeoutMs });
+  },
+};
+
+const sql_query = {
+  name: 'sql_query', category: 'coding', sensitive: true,
+  description: 'Run a read-only SQL query against the agent\'s bound database. Returns rows.',
+  parameters: {
+    type: 'object',
+    properties: { sql: { type: 'string' }, params: { type: 'array' } },
+    required: ['sql'],
+  },
+  async exec(args, ctx) {
+    const db = ctx?.db || null;
+    if (!db) return { ok: false, error: 'sql_query: no database bound to agent context' };
+    try {
+      const stmt = db.prepare(args.sql);
+      const rows = stmt.all(...(args.params || []));
+      return { ok: true, rows };
+    } catch (e) { return { ok: false, error: `sql_query: ${e.message}` }; }
+  },
+};
+
+const http_request = {
+  name: 'http_request', category: 'coding', sensitive: true,
+  description: 'Generic HTTP client. Reuses web_fetch SSRF policy.',
+  parameters: {
+    type: 'object',
+    properties: {
+      url: { type: 'string' }, method: { type: 'string' },
+      headers: { type: 'object' }, body: { type: 'string' },
+    },
+    required: ['url'],
+  },
+  async exec(args, ctx) {
+    const wf = webTools.find(t => t.name === 'web_fetch');
+    return wf.exec(args, ctx);
+  },
+};
+
+const regex_match = {
+  name: 'regex_match', category: 'coding', sensitive: false,
+  description: 'Run a regex over a string and return the matches.',
+  parameters: {
+    type: 'object',
+    properties: { pattern: { type: 'string' }, flags: { type: 'string' }, text: { type: 'string' } },
+    required: ['pattern', 'text'],
+  },
+  async exec(args) {
+    try {
+      const re = new RegExp(args.pattern, args.flags || '');
+      const matches = args.flags?.includes('g')
+        ? [...args.text.matchAll(re)].map(m => m[0])
+        : (args.text.match(re) || []);
+      return { ok: true, matches };
+    } catch (e) { return { ok: false, error: `regex_match: ${e.message}` }; }
+  },
+};
+
+export const TOOLS = [python_exec, node_exec, sql_query, http_request, regex_match];

package/mas/tools/delegation.mjs

@@ -0,0 +1,53 @@
+// delegation — task_spawn (named agent), delegate (worker provider).
+// Both lazy-import providers/orchestrator.mjs / mas/agent_turn.mjs to
+// avoid pulling those into every process that imports the registry.
+
+let _dispatcher = null;
+export function __setDispatcher(fn) { _dispatcher = fn; }
+
+async function dispatchDelegate(job) {
+  if (_dispatcher) return _dispatcher(job);
+  const orch = await import('../../providers/orchestrator.mjs').catch(() => null);
+  if (!orch || typeof orch.dispatchWorker !== 'function') {
+    return { ok: false, error: 'delegate: orchestrator.dispatchWorker unavailable' };
+  }
+  return orch.dispatchWorker(job);
+}
+
+async function dispatchSpawn(job) {
+  const at = await import('../agent_turn.mjs').catch(() => null);
+  if (!at || typeof at.runAgentTurn !== 'function') {
+    return { ok: false, error: 'task_spawn: agent_turn.runAgentTurn unavailable' };
+  }
+  return at.runAgentTurn(job);
+}
+
+const task_spawn = {
+  name: 'task_spawn', category: 'agents', sensitive: true,
+  description: 'Spawn an agent by name with a prompt; returns the final answer.',
+  parameters: {
+    type: 'object',
+    properties: { agent: { type: 'string' }, prompt: { type: 'string' } },
+    required: ['agent', 'prompt'],
+  },
+  async exec(args) {
+    if (!args?.agent || !args?.prompt) return { ok: false, error: 'task_spawn: agent + prompt required' };
+    return dispatchSpawn({ agent: args.agent, prompt: args.prompt });
+  },
+};
+
+const delegate = {
+  name: 'delegate', category: 'agents', sensitive: true,
+  description: 'Dispatch a subtask to a worker provider (claude-cli, codex-cli, gemini-cli, anthropic, openai, gemini, ollama).',
+  parameters: {
+    type: 'object',
+    properties: { worker: { type: 'string' }, prompt: { type: 'string' }, model: { type: 'string' } },
+    required: ['worker', 'prompt'],
+  },
+  async exec(args) {
+    if (!args?.worker || !args?.prompt) return { ok: false, error: 'delegate: worker + prompt required' };
+    return dispatchDelegate({ worker: args.worker, prompt: args.prompt, model: args.model });
+  },
+};
+
+export const TOOLS = [task_spawn, delegate];

package/mas/tools/edit.mjs

@@ -0,0 +1,36 @@
+// edit — find/replace exactly one occurrence of `old` with `new` inside a file
+// rooted at the agent cwd. Refuses when `old` is missing or not unique so the
+// LLM cannot silently overwrite the wrong span (spec §7 sub-bullet 1).
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const TOOL = {
+  name: 'edit',
+  category: 'fs',
+  sensitive: true,
+  description: 'Replace exactly one occurrence of `old` with `new` inside a workspace file. Fails if `old` is missing or appears more than once.',
+  parameters: {
+    type: 'object',
+    properties: {
+      path: { type: 'string', description: 'File path relative to cwd.' },
+      old:  { type: 'string', description: 'Exact substring to replace.' },
+      new:  { type: 'string', description: 'Replacement text.' },
+    },
+    required: ['path', 'old', 'new'],
+  },
+  async exec(args, { cwd = process.cwd() } = {}) {
+    if (!args || typeof args.path !== 'string') return { ok: false, error: 'edit: path required' };
+    if (typeof args.old !== 'string' || typeof args.new !== 'string') return { ok: false, error: 'edit: old/new strings required' };
+    const abs = path.resolve(cwd, args.path);
+    if (!abs.startsWith(path.resolve(cwd))) return { ok: false, error: 'edit: path escapes workspace' };
+    let src;
+    try { src = fs.readFileSync(abs, 'utf8'); } catch (e) { return { ok: false, error: `edit: ${e.message}` }; }
+    const idx = src.indexOf(args.old);
+    if (idx === -1) return { ok: false, error: `edit: \`old\` not found in ${args.path}` };
+    if (src.indexOf(args.old, idx + 1) !== -1) return { ok: false, error: `edit: \`old\` not unique in ${args.path}` };
+    const next = src.slice(0, idx) + args.new + src.slice(idx + args.old.length);
+    fs.writeFileSync(abs, next);
+    return { ok: true, path: args.path, bytesWritten: Buffer.byteLength(next) };
+  },
+};