lazyclaw 3.99.28 → 4.2.1

package/mas/audit.mjs

@@ -0,0 +1,62 @@
+// Per-task audit log for every tool call an agent makes.
+//
+// Records appended one JSON object per line to
+// <configDir>/tasks/<id>.audit.jsonl. Stores hashes of the args and
+// result so a runaway agent can't blow the disk with verbose tool I/O,
+// while still giving operators something to grep against when they need
+// forensics. Set LAZYCLAW_AUDIT_RAW=1 to additionally inline the raw
+// args/result bodies — useful in development, off by default.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+
+export class AuditError extends Error {
+  constructor(message) { super(message); this.name = 'AuditError'; }
+}
+
+export function defaultConfigDir() {
+  return process.env.LAZYCLAW_CONFIG_DIR || path.join(os.homedir(), '.lazyclaw');
+}
+
+export function auditPath(taskId, configDir = defaultConfigDir()) {
+  if (!taskId || typeof taskId !== 'string') throw new AuditError('taskId required');
+  return path.join(configDir, 'tasks', `${taskId}.audit.jsonl`);
+}
+
+function hashJson(obj) {
+  const s = (obj === undefined) ? '' : JSON.stringify(obj);
+  return 'sha256:' + crypto.createHash('sha256').update(s).digest('hex').slice(0, 16);
+}
+
+export function append({ taskId, agent, tool, args, result, ok = true, configDir = defaultConfigDir() } = {}) {
+  if (!taskId) return;  // skip silently when called outside a task scope (Phase 12a unit tests)
+  const file = auditPath(taskId, configDir);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const entry = {
+    ts: new Date().toISOString(),
+    agent: agent || 'unknown',
+    tool,
+    args_hash: hashJson(args),
+    result_hash: hashJson(result),
+    ok: !!ok,
+  };
+  if (process.env.LAZYCLAW_AUDIT_RAW === '1') {
+    entry.args = args;
+    entry.result = result;
+  }
+  fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+}
+
+export function read(taskId, configDir = defaultConfigDir()) {
+  const file = auditPath(taskId, configDir);
+  if (!fs.existsSync(file)) return [];
+  const raw = fs.readFileSync(file, 'utf8');
+  const out = [];
+  for (const line of raw.split('\n')) {
+    if (!line) continue;
+    try { out.push(JSON.parse(line)); } catch { /* skip malformed */ }
+  }
+  return out;
+}

package/mas/mention_router.mjs

@@ -0,0 +1,360 @@
+// Mention router — drives a multi-agent task through one Slack thread.
+//
+// Flow per `runTaskTurn` call:
+//
+//   1. Append the user message (if any) to task.turns.
+//   2. Enqueue the team lead for the first turn.
+//   3. Pop an agent off the queue, build its turn context from task.turns
+//      (system = agent.role + team metadata; user = formatted thread
+//      transcript + "your turn as X"), and call runAgentTurn.
+//   4. Append the agent's reply to task.turns and (if Slack is wired)
+//      post it into the task's thread.
+//   5. If the reply contains the [[TASK_DONE]] marker, flip status to
+//      'done' and stop. Otherwise, extract @mentions of teammates and
+//      enqueue them. When the speaker isn't the lead and made no
+//      mentions, hand control back to the lead.
+//   6. Loop until queue empties or maxAgentTurns is reached.
+//
+// History across turns: every agent sees the entire thread transcript
+// rendered as one big user message — that's the simplest representation
+// that survives multi-speaker alternation rules in all three providers.
+
+import * as agentTurn from './agent_turn.mjs';
+import * as agentsMod from '../agents.mjs';
+import * as tasksMod from '../tasks.mjs';
+import * as agentMemory from './agent_memory.mjs';
+
+export class MentionRouterError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'MentionRouterError';
+    this.code = code || 'ROUTER_ERR';
+  }
+}
+
+export const DONE_MARKER = '[[TASK_DONE]]';
+const DEFAULT_MAX_AGENT_TURNS = 12;
+
+// Extract @AgentName mentions out of an agent's text. Only resolves
+// matches that are present in `teamAgents`; everything else (including
+// "@channel", "@here", or stray emails) is ignored. Preserves order,
+// dedupes, and skips the speaker so an agent that re-mentions itself
+// doesn't loop.
+export function extractMentions(text, teamAgents, speaker = null) {
+  if (typeof text !== 'string' || !text) return [];
+  const set = new Set(teamAgents.map((a) => a.toLowerCase()));
+  const out = [];
+  const seen = new Set();
+  const re = /(?:^|[^\w@])@([a-zA-Z][a-zA-Z0-9_-]*)/g;
+  let m;
+  while ((m = re.exec(text)) !== null) {
+    const name = m[1];
+    const key = name.toLowerCase();
+    if (!set.has(key)) continue;
+    if (speaker && key === String(speaker).toLowerCase()) continue;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    // Recover the canonical (original) name from teamAgents.
+    const canonical = teamAgents.find((a) => a.toLowerCase() === key) || name;
+    out.push(canonical);
+  }
+  return out;
+}
+
+// Render task.turns into a single string. Each turn becomes:
+//   "[agentName] text..."
+// The "user" pseudo-agent maps to "User"; the "system" pseudo-agent maps
+// to "System" (the kickoff turn lazyclaw seeds during task start).
+export function renderTranscript(turns) {
+  if (!Array.isArray(turns) || turns.length === 0) return '(no turns yet)';
+  return turns.map((t) => {
+    const who = t.agent === 'user' ? 'User' : t.agent === 'system' ? 'System' : t.agent;
+    return `[${who}] ${t.text}`;
+  }).join('\n\n');
+}
+
+// Build the per-turn prompt the agent sees. System prompt = agent.role
+// + memory block (Phase 18) + team metadata so the model knows who its
+// teammates are and how to terminate; user prompt = task spec +
+// transcript + a tag indicating whose turn this is.
+export function buildTurnContext({ task, team, agent, agentRecord, teammates, configDir }) {
+  const memberList = teammates.length
+    ? teammates.map((a) => `@${a}`).join(', ')
+    : '(no other agents in this team)';
+  const role = agentRecord.role || '';
+  // Phase 18: per-agent memory block, truncated to the agent's
+  // memoryMaxChars (default 12 KB). When the file is empty/missing the
+  // helper returns '' so the prompt looks exactly like it did before
+  // Phase 18.
+  const memBlock = agentMemory.buildMemoryBlock(
+    agentRecord.name,
+    configDir,
+    Number.isFinite(+agentRecord.memoryMaxChars) ? +agentRecord.memoryMaxChars : agentMemory.DEFAULT_MAX_CHARS,
+  );
+  const system = [
+    role,
+    role && '\n\n---\n',
+    memBlock || null,
+    `You are *${agentRecord.displayName || agentRecord.name}* on team "${team.displayName || team.name}".`,
+    `Teammates you can mention with @name: ${memberList}.`,
+    `When the task is complete, end your message with the marker ${DONE_MARKER}.`,
+  ].filter(Boolean).join('\n');
+  const userParts = [
+    `# Task: ${task.title}`,
+    task.description ? `\n${task.description}\n` : '',
+    '# Conversation so far:\n',
+    renderTranscript(task.turns),
+    `\n\n# Your turn (as ${agentRecord.name}):`,
+  ];
+  return { system, user: userParts.join('') };
+}
+
+// Post a single message into the task's Slack thread. Best-effort: log
+// + swallow when the bot token is missing or the API call fails so the
+// router doesn't crash mid-task on a transient Slack error.
+//
+// When agentRecord has displayName / iconEmoji, the post is sent under
+// the agent's persona via chat.postMessage's `username` / `icon_emoji`
+// fields (requires the bot's chat:write.customize scope — Slack
+// silently ignores them when the scope is missing). The message text
+// is no longer manually prefixed with the agent name because the
+// custom username already shows it in Slack's UI.
+async function postToThread({ task, agentRecord, text, logger = () => {}, sender }) {
+  if (!task.slackChannel || !task.slackThreadTs) return null;
+  let slack = sender;
+  let owned = false;
+  if (!slack) {
+    const { SlackChannel } = await import('../channels/slack.mjs');
+    slack = new SlackChannel({ requireInbound: false });
+    owned = true;
+    try {
+      await slack.start(async () => '', {});
+    } catch (err) {
+      logger(`[router] slack start failed: ${err?.message || err}\n`);
+      return null;
+    }
+  }
+  const threadId = `${task.slackChannel}:${task.slackThreadTs}`;
+  // When we have a real agent persona, push the text under that
+  // persona's username + icon. Otherwise (user message or system note)
+  // fall back to the bot's default identity with no decoration.
+  let body;
+  let sendOpts = {};
+  if (agentRecord) {
+    body = String(text);
+    if (agentRecord.displayName) sendOpts.username = agentRecord.displayName;
+    if (agentRecord.iconEmoji) sendOpts.icon_emoji = agentRecord.iconEmoji;
+  } else {
+    body = String(text);
+  }
+  try {
+    const res = await slack.send(threadId, body, sendOpts);
+    return res?.ts || null;
+  } catch (err) {
+    logger(`[router] slack send failed: ${err?.message || err}\n`);
+    return null;
+  } finally {
+    if (owned) await slack.stop().catch(() => {});
+  }
+}
+
+// "X is thinking…" placeholder posted into the thread before an agent
+// turn so a human reader knows work is happening. Returns the ts of
+// the placeholder so the caller can delete it once the real reply is
+// in. No-op when Slack isn't wired or the post fails.
+async function postTypingPlaceholder({ task, agentRecord, logger = () => {}, sender }) {
+  if (!task.slackChannel || !task.slackThreadTs) return { ts: null, sender: null };
+  let slack = sender;
+  let owned = false;
+  if (!slack) {
+    const { SlackChannel } = await import('../channels/slack.mjs');
+    slack = new SlackChannel({ requireInbound: false });
+    owned = true;
+    try {
+      await slack.start(async () => '', {});
+    } catch (err) {
+      logger(`[router] slack start failed: ${err?.message || err}\n`);
+      return { ts: null, sender: null };
+    }
+  }
+  const threadId = `${task.slackChannel}:${task.slackThreadTs}`;
+  const sendOpts = {};
+  if (agentRecord?.displayName) sendOpts.username = agentRecord.displayName;
+  if (agentRecord?.iconEmoji)   sendOpts.icon_emoji = agentRecord.iconEmoji;
+  try {
+    const res = await slack.send(threadId, `_:hourglass_flowing_sand: thinking…_`, sendOpts);
+    return { ts: res?.ts || null, sender: owned ? slack : null, channel: task.slackChannel };
+  } catch (err) {
+    logger(`[router] slack typing post failed: ${err?.message || err}\n`);
+    if (owned) await slack.stop().catch(() => {});
+    return { ts: null, sender: null };
+  }
+}
+
+// Fire one reflection LLM call per agent that actually spoke during
+// this task. Each successful reflection is prepended to the agent's
+// memory file. Failures are logged but never thrown — a sticky
+// transcript that won't reflect shouldn't poison the user's terminal.
+async function autoReflect({ task, agentsById, apiKey, baseUrl, fetchImpl, configDir, logger = () => {} }) {
+  if (!task || !Array.isArray(task.turns)) return;
+  const participants = new Set();
+  for (const t of task.turns) {
+    if (t.agent && t.agent !== 'user' && t.agent !== 'system') participants.add(t.agent);
+  }
+  for (const name of participants) {
+    const agentRecord = agentsById[name];
+    if (!agentRecord) continue;
+    if (agentRecord.memoryWrite && agentRecord.memoryWrite !== 'auto') continue;
+    try {
+      const body = await agentMemory.reflectOnce({
+        agent: agentRecord,
+        task,
+        apiKey,
+        baseUrl,
+        fetchImpl,
+      });
+      if (body && body.trim()) {
+        agentMemory.prependEntry(name, { taskId: task.id, title: task.title, body }, configDir);
+        logger(`[memory] ${name} reflected on ${task.id}\n`);
+      }
+    } catch (err) {
+      logger(`[memory] reflection failed for ${name}: ${err?.message || err}\n`);
+    }
+  }
+}
+
+async function clearTypingPlaceholder(placeholder, logger) {
+  if (!placeholder?.ts || !placeholder?.channel) return;
+  const slack = placeholder.sender;
+  if (!slack) return;  // sender wasn't owned by us; skip
+  try { await slack.deleteMessage(placeholder.channel, placeholder.ts); }
+  catch (err) { logger(`[router] slack typing delete failed: ${err?.message || err}\n`); }
+  finally { await slack.stop().catch(() => {}); }
+}
+
+// Run agents in this team until the queue empties or budget runs out.
+//
+// Returns { task, iterations, stoppedBy: 'idle' | 'done' | 'budget' }.
+//   - 'idle'  — natural end (queue empty, no one to speak)
+//   - 'done'  — an agent emitted DONE_MARKER (task.status flipped)
+//   - 'budget' — maxAgentTurns hit before queue drained
+export async function runTaskTurn({
+  task,
+  team,
+  agentsById,
+  userMessage,
+  configDir,
+  cwd,
+  apiKey,
+  fetchImpl,
+  baseUrl,
+  logger = () => {},
+  maxAgentTurns = DEFAULT_MAX_AGENT_TURNS,
+  signal,
+} = {}) {
+  if (!task || !team || !agentsById) {
+    throw new MentionRouterError('task, team, agentsById are required', 'ROUTER_BAD_INPUT');
+  }
+  if (!team.lead || !team.agents.includes(team.lead)) {
+    throw new MentionRouterError(`team "${team.name}" has no valid lead`, 'ROUTER_NO_LEAD');
+  }
+  // Closed tasks reject further ticks so a stray `task tick` after a
+  // [[TASK_DONE]] or an explicit abandon doesn't reopen the loop.
+  if (task.status === 'done' || task.status === 'abandoned') {
+    throw new MentionRouterError(`task "${task.id}" is ${task.status} — cannot run further turns`, 'ROUTER_CLOSED');
+  }
+
+  let current = task;
+
+  // A pending task (no Slack thread was opened at task start) gets
+  // promoted to running on its first tick so the dashboard reflects
+  // that work has actually started.
+  if (current.status === 'pending') {
+    current = tasksMod.patchTask(current.id, { status: 'running' }, configDir);
+  }
+
+  // Seed: append the user message if provided, and (also) push it to
+  // Slack so anyone reading the thread sees the prompt.
+  if (userMessage && String(userMessage).trim()) {
+    current = tasksMod.appendTurn(current.id, { agent: 'user', text: String(userMessage), ts: new Date().toISOString() }, configDir);
+    await postToThread({ task: current, agentRecord: null, text: `*User*: ${userMessage}`, logger });
+  }
+
+  const queue = [team.lead];
+  let iterations = 0;
+  let stoppedBy = 'idle';
+
+  while (queue.length > 0 && iterations < maxAgentTurns) {
+    if (signal?.aborted) { stoppedBy = 'abort'; break; }
+    const speaker = queue.shift();
+    const agentRecord = agentsById[speaker];
+    if (!agentRecord) {
+      logger(`[router] no agent record for "${speaker}" — skipping\n`);
+      continue;
+    }
+    iterations++;
+    const teammates = team.agents.filter((a) => a !== speaker);
+    const ctx = buildTurnContext({ task: current, team, agent: speaker, agentRecord, teammates, configDir });
+
+    // Post a "thinking…" placeholder so the user sees the bot picked
+    // up the turn before the LLM finishes. Cleared right after the
+    // real reply lands so we never leave a stale placeholder in the
+    // thread.
+    const typing = await postTypingPlaceholder({ task: current, agentRecord, logger });
+
+    let result;
+    try {
+      result = await agentTurn.runAgentTurn({
+        agent: { ...agentRecord, role: ctx.system },
+        userMessage: ctx.user,
+        history: [],
+        taskId: current.id,
+        configDir, cwd, apiKey, fetchImpl, baseUrl, signal,
+      });
+    } catch (err) {
+      await clearTypingPlaceholder(typing, logger);
+      logger(`[router] agent "${speaker}" threw: ${err?.message || err}\n`);
+      current = tasksMod.appendTurn(current.id, { agent: speaker, text: `(error: ${err?.message || err})`, ts: new Date().toISOString(), error: true }, configDir);
+      continue;
+    }
+    await clearTypingPlaceholder(typing, logger);
+
+    const replyText = (result.text || '').trim();
+    const ts = new Date().toISOString();
+    current = tasksMod.appendTurn(current.id, { agent: speaker, text: replyText, ts, toolCalls: result.toolCalls?.length ? result.toolCalls : undefined }, configDir);
+
+    // Slack mirror — only the user-visible text, with the agent name
+    // prefixed so a human reader can follow who said what.
+    if (replyText) await postToThread({ task: current, agentRecord, text: replyText, logger });
+
+    if (replyText.includes(DONE_MARKER)) {
+      current = tasksMod.patchTask(current.id, { status: 'done' }, configDir);
+      await postToThread({ task: current, agentRecord: null, text: `:white_check_mark: ${DONE_MARKER} — task closed by *${agentRecord.displayName || speaker}*.`, logger });
+      stoppedBy = 'done';
+      // Phase 18: fire one reflection LLM call per participating agent
+      // whose memoryWrite is 'auto'. We pick "participating" off the
+      // task.turns rather than team.agents so an agent who never spoke
+      // doesn't reflect on a task they weren't really in.
+      await autoReflect({
+        task: current,
+        agentsById,
+        apiKey, baseUrl, fetchImpl,
+        configDir, logger,
+      });
+      break;
+    }
+
+    const mentions = extractMentions(replyText, team.agents, speaker);
+    for (const m of mentions) queue.push(m);
+
+    // When a non-lead speaker doesn't hand off, return control to the
+    // lead so the conversation doesn't strand mid-team. The lead can
+    // choose to terminate next turn.
+    if (mentions.length === 0 && speaker !== team.lead) {
+      queue.push(team.lead);
+    }
+  }
+
+  if (iterations >= maxAgentTurns) stoppedBy = 'budget';
+  return { task: current, iterations, stoppedBy };
+}

package/mas/tool_runner.mjs

@@ -0,0 +1,87 @@
+// Tool runner — given an agent record and a tool invocation, validates
+// 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 audit from './audit.mjs';
+
+export class ToolError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'ToolError';
+    this.code = code || 'TOOL_ERR';
+  }
+}
+
+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);
+  for (const name of wanted) {
+    const t = TOOLS[name];
+    if (!t) continue;
+    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.
+//
+// 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 } = {}) {
+  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');
+  }
+  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;
+  }
+  let result;
+  try {
+    result = await impl.exec(args || {}, { cwd: cwd || process.cwd() });
+  } catch (err) {
+    result = { ok: false, error: `${tool} threw: ${err?.message || err}` };
+  }
+  audit.append({ taskId, agent: agent.name, tool, args, result, ok: !!result?.ok, configDir });
+  return result;
+}

package/mas/tools/bash.mjs

@@ -0,0 +1,78 @@
+// Bash tool — runs a shell command, captures stdout/stderr/exit.
+//
+// Workspace is constrained to the lazyclaw process cwd (spec §5.2). We
+// don't sandbox further (per §10 #6 — destructive-pattern confirmation
+// is OFF by default); the audit log captures every invocation so post-hoc
+// forensics work.
+//
+// Timeout defaults to 30s so a runaway command can't stall the whole
+// agent turn. Override via args.timeoutMs (capped at 5 minutes).
+
+import { spawn } from 'node:child_process';
+
+export const NAME = 'bash';
+export const DESCRIPTION = 'Run a shell command in the agent\'s workspace. Returns {stdout, stderr, exitCode}. Timeout 30s by default.';
+export const PARAMETERS = {
+  type: 'object',
+  properties: {
+    command: { type: 'string', description: 'The shell command to execute.' },
+    timeoutMs: { type: 'number', description: 'Optional override (max 300000).' },
+  },
+  required: ['command'],
+};
+
+const MAX_TIMEOUT_MS = 5 * 60_000;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_OUTPUT_BYTES = 200_000;  // 200 KB per stream — bigger gets truncated
+
+export async function exec(args, { cwd = process.cwd() } = {}) {
+  if (!args || typeof args.command !== 'string' || args.command.trim() === '') {
+    return { ok: false, error: 'bash: command is required (non-empty string)' };
+  }
+  const timeoutMs = Math.min(
+    Math.max(Number.isFinite(+args.timeoutMs) ? +args.timeoutMs : DEFAULT_TIMEOUT_MS, 100),
+    MAX_TIMEOUT_MS
+  );
+  return new Promise((resolve) => {
+    const child = spawn('sh', ['-c', args.command], { cwd, env: process.env });
+    let stdout = '', stderr = '';
+    let outBytes = 0, errBytes = 0;
+    let truncated = false;
+    let timedOut = false;
+    const tm = setTimeout(() => {
+      timedOut = true;
+      try { child.kill('SIGTERM'); } catch { /* gone */ }
+      setTimeout(() => { try { child.kill('SIGKILL'); } catch { /* gone */ } }, 1000);
+    }, timeoutMs);
+    child.stdout.on('data', (chunk) => {
+      const s = chunk.toString();
+      outBytes += s.length;
+      if (outBytes > MAX_OUTPUT_BYTES) {
+        if (!truncated) stdout += s.slice(0, Math.max(0, MAX_OUTPUT_BYTES - (outBytes - s.length))) + '\n…[truncated]\n';
+        truncated = true;
+      } else {
+        stdout += s;
+      }
+    });
+    child.stderr.on('data', (chunk) => {
+      const s = chunk.toString();
+      errBytes += s.length;
+      if (errBytes > MAX_OUTPUT_BYTES) {
+        if (!truncated) stderr += s.slice(0, Math.max(0, MAX_OUTPUT_BYTES - (errBytes - s.length))) + '\n…[truncated]\n';
+        truncated = true;
+      } else {
+        stderr += s;
+      }
+    });
+    child.on('close', (code) => {
+      clearTimeout(tm);
+      resolve({
+        ok: true,
+        stdout, stderr,
+        exitCode: code,
+        timedOut,
+        truncated,
+      });
+    });
+  });
+}

package/mas/tools/grep.mjs

@@ -0,0 +1,91 @@
+// Grep tool — recursive substring / regex search over the workspace.
+//
+// Pure JS scanner — no shell dependency on rg/grep. Walks the directory
+// tree honoring a small built-in ignore list (node_modules, .git,
+// dist/, build/, etc.) so a default search doesn't trawl megabytes of
+// dependency code.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const NAME = 'grep';
+export const DESCRIPTION = 'Search files for a substring or /regex/. Returns matching lines with path + line number.';
+export const PARAMETERS = {
+  type: 'object',
+  properties: {
+    pattern: { type: 'string', description: 'Plain substring or "/pattern/flags" regex form.' },
+    path: { type: 'string', description: 'Root to search; defaults to workspace cwd.' },
+    maxMatches: { type: 'number', description: 'Cap on results; default 200.' },
+  },
+  required: ['pattern'],
+};
+
+const DEFAULT_MAX_MATCHES = 200;
+const IGNORE_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage', '.playwright', 'playwright-report', 'test-results', '.lazyclaw']);
+const MAX_FILE_BYTES = 1_000_000;  // skip files bigger than 1 MB
+const TEXT_EXT = new Set([
+  '.js', '.mjs', '.cjs', '.ts', '.tsx', '.jsx', '.json', '.md', '.txt',
+  '.html', '.css', '.scss', '.sass', '.yml', '.yaml', '.toml', '.ini',
+  '.py', '.rb', '.go', '.rs', '.c', '.cc', '.cpp', '.h', '.hpp', '.java',
+  '.kt', '.swift', '.sh', '.bash', '.zsh', '.fish', '.sql', '.xml',
+  '.svg', '.vue', '.svelte', '.lua', '.php', '.gitignore', '',
+]);
+
+function compilePattern(raw) {
+  const m = /^\/(.+)\/([gimsuy]*)$/.exec(raw);
+  if (m) return new RegExp(m[1], m[2].includes('g') ? m[2] : m[2] + 'g');
+  // Escape for substring literal use and force `g` so we can scan
+  // multiple lines per file without restarting state.
+  return new RegExp(raw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g');
+}
+
+function* walk(root) {
+  let 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 (IGNORE_DIRS.has(ent.name)) continue;
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) stack.push(full);
+      else if (ent.isFile()) yield full;
+    }
+  }
+}
+
+export async function exec(args, { cwd = process.cwd() } = {}) {
+  if (!args || typeof args.pattern !== 'string' || !args.pattern) {
+    return { ok: false, error: 'grep: pattern is required' };
+  }
+  const root = args.path
+    ? (path.isAbsolute(args.path) ? args.path : path.resolve(cwd, args.path))
+    : cwd;
+  const max = Math.max(1, Math.min(Number.isFinite(+args.maxMatches) ? +args.maxMatches : DEFAULT_MAX_MATCHES, 1000));
+  let re;
+  try { re = compilePattern(args.pattern); }
+  catch (err) { return { ok: false, error: `grep: bad pattern: ${err?.message || err}` }; }
+
+  const matches = [];
+  let truncated = false;
+  for (const file of walk(root)) {
+    const ext = path.extname(file).toLowerCase();
+    if (TEXT_EXT.size && !TEXT_EXT.has(ext)) continue;
+    let stat;
+    try { stat = fs.statSync(file); } catch { continue; }
+    if (stat.size > MAX_FILE_BYTES) continue;
+    let content;
+    try { content = fs.readFileSync(file, 'utf8'); } catch { continue; }
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      re.lastIndex = 0;
+      if (re.test(lines[i])) {
+        matches.push({ path: file, line: i + 1, text: lines[i].slice(0, 500) });
+        if (matches.length >= max) { truncated = true; break; }
+      }
+    }
+    if (truncated) break;
+  }
+  return { ok: true, count: matches.length, truncated, matches };
+}