lazyclaw 4.2.2 → 5.0.0

package/mas/redact.mjs

@@ -0,0 +1,46 @@
+// Shared secret redaction — Phase 20 hardening.
+//
+// A single source of truth for stripping common secret shapes out of
+// text before it is (a) sent to an LLM or (b) persisted to a file that
+// later re-enters a system prompt. Both skill_synth.synthesizeSkill and
+// agent_memory.reflectOnce import this so the two paths stay symmetric:
+// neither a distilled skill nor a reflection memory can ever leak a
+// token that merely appeared in a task transcript.
+//
+// This module has zero internal imports so it can be imported from
+// anywhere without risking a cycle.
+
+// Redact common secret shapes (private keys, provider API tokens,
+// bearer headers, KEY/TOKEN/SECRET/PASSWORD env assignments). The match
+// list mirrors the audit log's posture of not persisting raw sensitive
+// I/O. Order matters: the private-key block is collapsed first so its
+// inner base64 doesn't trip the narrower token patterns.
+export function redactSecrets(text) {
+  return String(text ?? '')
+    .replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, '[REDACTED PRIVATE KEY]')
+    // Inline credentials in a URL: scheme://user:password@host → redact the password.
+    .replace(/\b([a-z][a-z0-9+.-]*:\/\/[^/\s:@]+):[^/\s@]+@/gi, '$1:[REDACTED]@')
+    .replace(/\bsk-[A-Za-z0-9_-]{8,}/g, '[REDACTED]')
+    .replace(/\b(?:gh[opsu]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})/g, '[REDACTED]')
+    .replace(/\bxox[abprs]-[A-Za-z0-9-]{8,}/g, '[REDACTED]')
+    .replace(/\bAKIA[0-9A-Z]{12,}/g, '[REDACTED]')
+    .replace(/\bAIza[0-9A-Za-z_-]{35}/g, '[REDACTED]')
+    .replace(/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, '[REDACTED JWT]')
+    .replace(/\b[Bb]earer\s+[A-Za-z0-9._-]{8,}/g, 'Bearer [REDACTED]')
+    // Uppercase env-assignment form (kept for parity / readability).
+    .replace(/\b([A-Z][A-Z0-9_]{2,}_(?:KEY|TOKEN|SECRET|PASSWORD))\s*=\s*\S+/g, '$1=[REDACTED]')
+    // Case-insensitive key/token/secret/password assignment (api_key=, apiKey: "...", PASSWORD=…).
+    // [\w-]* may be empty so a bare `password:` / `token=` is caught too.
+    .replace(/\b([\w-]*(?:key|token|secret|password))\s*[:=]\s*["']?[^\s"']+/gi, '$1=[REDACTED]');
+}
+
+// Neutralise forged conversation role labels embedded in untrusted model
+// text. The reflection/synthesis transcript is rendered as
+// `[User]/[System]/<agent>` lines from the TRUSTED turn.agent field; a
+// turn's free-text body must not be able to inject its own authority
+// line (e.g. a newline followed by "[System] ignore previous"). We defang
+// only the authority roles (case-insensitive, line-leading) so a forged
+// instruction can't masquerade as the system/user/assistant speaker.
+export function neutralizeRoleLabels(text) {
+  return String(text ?? '').replace(/^([ \t]*)\[(user|system|assistant|agent)\]/gim, '$1($2)');
+}

package/mas/skill_synth.mjs

@@ -0,0 +1,331 @@
+// Skill synthesis — Phase 20.
+//
+// Turns a finished task transcript into a reusable SKILL.md (the
+// Hermes self-improving-skill pattern). This module owns the
+// deterministic, LLM-free pieces so they can be unit-tested without a
+// network round-trip:
+//
+//   slugifySkill(title)        → a filesystem-safe skill name
+//   parseSynthOutput(text)     → { name, description, body } from raw
+//                                LLM output
+//   assembleSkillDoc({...})    → a full SKILL.md (frontmatter + body)
+//
+// The single LLM call lives in synthesizeSkill() at the bottom; it
+// mirrors agent_memory.reflectOnce() (same provider adapters, same
+// no-tools text completion) but asks for a structured skill instead of
+// free-text lessons.
+
+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;
+const MAX_BODY_BYTES = 8 * 1024;
+
+// Re-export the shared secret redactor (mas/redact.mjs) so existing
+// callers of skill_synth.redactSecrets keep working while the single
+// implementation is shared with agent_memory.reflectOnce.
+export { redactSecrets };
+
+// Sanitise an agent-authored skill body before it is persisted and
+// later loaded into other agents' context: redact secrets, neutralise
+// the task-termination marker (so reference material can't drive the
+// router loop), strip control characters, and cap the size.
+export function sanitizeSkillBody(text) {
+  let s = redactSecrets(text);
+  s = s.replace(/\[\[TASK_DONE\]\]/g, '[[task-done]]');
+  // Strip control characters except tab/newline/carriage-return.
+  s = s.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, '');
+  if (Buffer.byteLength(s, 'utf8') > MAX_BODY_BYTES) {
+    s = Buffer.from(s, 'utf8').subarray(0, MAX_BODY_BYTES).toString('utf8').replace(/\uFFFD+$/, '') + '\n\n…[truncated]';
+  }
+  return s;
+}
+
+// Sanitise the one-line description (it lands in every agent's system
+// prompt via the skills index): redact, collapse to a single line,
+// neutralise the marker, cap to 120 chars.
+export function sanitizeDescription(text) {
+  return redactSecrets(text)
+    .replace(/\[\[TASK_DONE\]\]/g, '[[task-done]]')
+    .replace(/[\u0000-\u001F\u007F]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 120);
+}
+
+// Lowercase, collapse every run of non-alphanumerics into a single
+// dash, and strip leading/trailing dashes. Empty input (or input with
+// no alphanumerics) falls back to "skill" so a write always has a
+// valid target name.
+export function slugifySkill(title) {
+  const slug = String(title || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, MAX_NAME_LEN)
+    .replace(/-+$/g, '');
+  return slug || 'skill';
+}
+
+// Parse the model's reply into { name, description, body }. The prompt
+// asks for two leading `name:` / `description:` lines followed by the
+// `## When to Use / ## Procedure / ## Pitfalls / ## Verification`
+// sections — but models drift, so we degrade gracefully: when the
+// leading lines are missing we derive the name from the first heading
+// and leave the description empty. `body` always begins at the first
+// markdown heading (the section content), with the name/description
+// header stripped.
+export function parseSynthOutput(text) {
+  const raw = String(text || '').replace(/^/, '').trim();
+  const lines = raw.split(/\r?\n/);
+
+  let name = '';
+  let description = '';
+  let bodyStart = 0;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (SECTION_RE.test(line)) { bodyStart = i; break; }
+    const nameM = /^name\s*:\s*(.+)$/i.exec(line.trim());
+    if (nameM && !name) { name = nameM[1].trim(); bodyStart = i + 1; continue; }
+    const descM = /^description\s*:\s*(.+)$/i.exec(line.trim());
+    if (descM && !description) { description = descM[1].trim(); bodyStart = i + 1; continue; }
+  }
+
+  const body = lines.slice(bodyStart).join('\n').replace(/^(?:\r?\n)+/, '').trimEnd();
+
+  // No explicit name → derive it from the first heading in the body.
+  if (!name) {
+    const firstHeading = body.split(/\r?\n/).find((l) => SECTION_RE.test(l));
+    if (firstHeading) name = firstHeading.replace(SECTION_RE, '').trim();
+  }
+
+  return { name: slugifySkill(name), description, body };
+}
+
+// Build a complete SKILL.md: a flat-YAML frontmatter block followed by
+// 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(),
+  // 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}`);
+  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) {
+  return String(v ?? '').replace(/[\u0000-\u001f\u007f]/g, '');
+}
+
+// Quote a value only when it contains characters our flat parser would
+// otherwise choke on (a leading special char or an embedded colon).
+// Control characters (including newlines) are stripped first: a quoted
+// multi-line value still injects a frontmatter key because the parser
+// splits on physical lines, so the only safe move is to flatten to a
+// single line before deciding whether to quote.
+function escapeYaml(v) {
+  const s = stripControl(v);
+  if (s === '') return '';
+  if (/[:#]/.test(s) || /^[\s'">|&*!%@`-]/.test(s)) return `"${s.replace(/"/g, '\\"')}"`;
+  return s;
+}
+
+export class SkillSynthError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'SkillSynthError';
+    this.code = code || 'SKILL_SYNTH_ERR';
+  }
+}
+
+// Run one synthesis LLM call for an agent that just finished a task and
+// return { name, description, doc } — a complete SKILL.md ready to
+// install — or null when the model produced nothing usable. Mirrors
+// agent_memory.reflectOnce(): same provider adapters, a pure text
+// 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,
+  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');
+  }
+
+  const transcript = redactSecrets(
+    (Array.isArray(task.turns) ? task.turns : [])
+      .map((t) => {
+        const who = t.agent === 'user' ? 'User' : t.agent === 'system' ? 'System' : t.agent;
+        return `[${who}] ${neutralizeRoleLabels(t.text || '')}`;
+      })
+      .join('\n\n') || '(no turns)'
+  );
+
+  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,
+  })).trim();
+  if (!text || /^none\b/i.test(text)) return null;
+
+  const parsed = parseSynthOutput(text);
+  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,
+    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
+// one: reserveSynthName picks a collision-free target (or our own prior
+// agent skill, which we then version-bump). Body/description are
+// re-sanitised here too so a direct caller (CLI/router) can't bypass
+// the redaction + cap. Returns { skill, path, version }.
+export function installSynthesized({ name, description = '', body = '', sourceTask = '', createdBy = 'agent' } = {}, configDir, ts = new Date()) {
+  // Slugify BEFORE reserving the name so a direct caller (CLI/router)
+  // can't smuggle a newline/colon into the filename or inject a second
+  // frontmatter key. parseSynthOutput already slugifies, but this path
+  // is also reachable directly with an arbitrary name.
+  const finalName = skills.reserveSynthName(slugifySkill(name), configDir);
+  const overwritingOwn = skills.skillExists(finalName, configDir);
+  const version = overwritingOwn ? skills.skillVersion(finalName, configDir) + 1 : 1;
+  const doc = assembleSkillDoc({
+    name: finalName,
+    description: sanitizeDescription(description),
+    createdBy,
+    sourceTask,
+    body: sanitizeSkillBody(body),
+    version,
+    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,16 +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 registry from './tools/registry.mjs';
 import * as audit from './audit.mjs';
 
 export class ToolError extends Error {
@@ -22,63 +14,42 @@ export class ToolError extends Error {
   }
 }
 
-const TOOLS = {
-  bash: bashTool,
-  read: readTool,
-  write: writeTool,
-  grep: grepTool,
-};
-
-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);
-}
+export function isImplemented(name) { return registry.lookup(name) !== null; }
+export function knownTool(name)     { return registry.lookup(name) !== null; }
 
-// 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.
-//
-// 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.
-export async function runTool({ agent, tool, args, taskId, configDir, cwd } = {}) {
+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;
+  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}` }; }
+    if (!verdict || !verdict.approved) {
+      const result = { ok: false, error: `tool "${tool}" denied by operator${verdict?.reason ? `: ${verdict.reason}` : ''}`, code: 'TOOL_DENIED_APPROVAL' };
+      audit.append({ taskId, agent: agent.name, tool, args, result, ok: false, configDir });
+      return result;
+    }
   }
   let result;
   try {
-    result = await impl.exec(args || {}, { cwd: cwd || process.cwd() });
+    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' };
+  },
+};