crewswarm 0.8.1-beta

package/lib/crew-lead/agent-manager.mjs

@@ -0,0 +1,125 @@
+/**
+ * Dynamic agent creation and management — extracted from crew-lead.mjs
+ * Manages agents in ~/.crewswarm/crewswarm.json.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { writeAgentTools, writeAgentPrompt } from "../agents/permissions.mjs";
+import { getSharedChatPromptOverlay } from "../chat/shared-chat-prompt-overlay.mjs";
+
+function tryRead(p) {
+  try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
+}
+
+function withSharedChatGuidance(id, body) {
+  return `${body}\n\n${getSharedChatPromptOverlay(id)}`;
+}
+
+export const AGENT_ROLE_PRESETS = {
+  coder: {
+    tools: ["read_file", "write_file", "mkdir", "run_cmd", "skill"],
+    useOpenCode: false,
+    promptTemplate: (id, desc) => withSharedChatGuidance(id, `You are ${id}, a specialist coding agent.\n\nFocus: ${desc || "full-stack development"}\n\nUse @@READ_FILE before modifying files. Always @@WRITE_FILE your output with absolute paths. Report what you did and the full file paths in your reply.`),
+  },
+  researcher: {
+    tools: ["read_file", "web_search", "web_fetch", "skill"],
+    useOpenCode: false,
+    promptTemplate: (id, desc) => withSharedChatGuidance(id, `You are ${id}, a research specialist.\n\nFocus: ${desc || "deep research and analysis"}\n\nUse @@WEB_SEARCH and @@WEB_FETCH to gather information. Synthesize findings into clear, actionable summaries. Always cite sources.`),
+  },
+  writer: {
+    tools: ["read_file", "write_file", "web_search", "web_fetch", "skill"],
+    useOpenCode: false,
+    promptTemplate: (id, desc) => withSharedChatGuidance(id, `You are ${id}, a writing specialist.\n\nFocus: ${desc || "technical writing and documentation"}\n\nUse @@WEB_SEARCH for research when needed. Always @@WRITE_FILE your output with absolute paths. Write clear, concise, scannable content.`),
+  },
+  auditor: {
+    tools: ["read_file", "run_cmd", "skill"],
+    useOpenCode: false,
+    promptTemplate: (id, desc) => withSharedChatGuidance(id, `You are ${id}, an audit and review specialist.\n\nFocus: ${desc || "code review, testing, and quality assurance"}\n\nUse @@READ_FILE to inspect files and @@RUN_CMD for tests. Report issues with specific file paths and line numbers. Never modify files directly.`),
+  },
+  ops: {
+    tools: ["read_file", "write_file", "mkdir", "run_cmd", "git", "skill"],
+    useOpenCode: false,
+    promptTemplate: (id, desc) => withSharedChatGuidance(id, `You are ${id}, a DevOps and infrastructure specialist.\n\nFocus: ${desc || "deployment, CI/CD, infrastructure, and operations"}\n\nUse @@RUN_CMD for system tasks. Use @@WRITE_FILE for configs and scripts. Report status and any issues.`),
+  },
+  generalist: {
+    tools: ["read_file", "write_file", "mkdir", "run_cmd", "dispatch", "skill"],
+    useOpenCode: false,
+    promptTemplate: (id, desc) => withSharedChatGuidance(id, `You are ${id}, a generalist agent.\n\nFocus: ${desc || "versatile task execution"}\n\nAdapt to whatever is needed. Use @@READ_FILE, @@WRITE_FILE, @@RUN_CMD as appropriate. You can @@DISPATCH to other agents if a task needs a specialist.`),
+  },
+};
+
+const MAX_DYNAMIC_AGENTS = Number(process.env.CREWSWARM_MAX_DYNAMIC_AGENTS || "5");
+
+export function createAgent({ id, role, displayName, prompt, description, model }) {
+  if (!id) throw new Error("Agent id is required");
+  if (!id.startsWith("crew-")) id = `crew-${id}`;
+
+  const swarmPath = path.join(os.homedir(), ".crewswarm", "crewswarm.json");
+  const swarm = tryRead(swarmPath) || {};
+  if (!Array.isArray(swarm.agents)) swarm.agents = [];
+
+  // Check if agent already exists
+  if (swarm.agents.some(a => a.id === id)) {
+    throw new Error(`Agent ${id} already exists`);
+  }
+
+  // Count dynamic agents (those with _dynamic flag)
+  const dynamicCount = swarm.agents.filter(a => a._dynamic).length;
+  if (dynamicCount >= MAX_DYNAMIC_AGENTS) {
+    throw new Error(`Max dynamic agents (${MAX_DYNAMIC_AGENTS}) reached. Remove an existing dynamic agent first.`);
+  }
+
+  const preset = AGENT_ROLE_PRESETS[role] || AGENT_ROLE_PRESETS.generalist;
+  const agentModel = model || swarm.agents.find(a => a.id === "crew-main")?.model || "groq/llama-3.3-70b-versatile";
+
+  // OpenCode is opt-in only. Dynamic agents inherit no execution engine unless explicitly assigned.
+  const openCodeEnabled = preset.useOpenCode || false;
+  const defaultOcModel = (() => {
+    const existingCoder = swarm.agents.find(a => a.opencodeModel && a.useOpenCode);
+    if (existingCoder) return existingCoder.opencodeModel;
+    return process.env.CREWSWARM_OPENCODE_MODEL || "openai/gpt-5.3-codex";
+  })();
+
+  const agentEntry = {
+    id,
+    model: agentModel,
+    _dynamic: true,
+    _createdAt: new Date().toISOString(),
+    _role: role || "generalist",
+    useOpenCode: openCodeEnabled,
+  };
+  if (openCodeEnabled) agentEntry.opencodeModel = defaultOcModel;
+  if (displayName) agentEntry.identity = { name: displayName };
+
+  swarm.agents.push(agentEntry);
+  fs.writeFileSync(swarmPath, JSON.stringify(swarm, null, 2), "utf8");
+
+  // Set tools
+  writeAgentTools(id, preset.tools);
+
+  // Set prompt
+  const agentPrompt = prompt || preset.promptTemplate(id, description);
+  const bareId = id.replace(/^crew-/, "");
+  writeAgentPrompt(bareId, agentPrompt);
+
+  return { id, role: role || "generalist", tools: preset.tools, model: agentModel, displayName, useOpenCode: openCodeEnabled };
+}
+
+export function listDynamicAgents() {
+  const swarm = tryRead(path.join(os.homedir(), ".crewswarm", "crewswarm.json")) || {};
+  return (swarm.agents || []).filter(a => a._dynamic);
+}
+
+export function removeDynamicAgent(id) {
+  if (!id.startsWith("crew-")) id = `crew-${id}`;
+  const swarmPath = path.join(os.homedir(), ".crewswarm", "crewswarm.json");
+  const swarm = tryRead(swarmPath) || {};
+  if (!Array.isArray(swarm.agents)) return false;
+  const idx = swarm.agents.findIndex(a => a.id === id && a._dynamic);
+  if (idx < 0) throw new Error(`${id} is not a dynamic agent (or doesn't exist)`);
+  swarm.agents.splice(idx, 1);
+  fs.writeFileSync(swarmPath, JSON.stringify(swarm, null, 2), "utf8");
+  return true;
+}

package/lib/crew-lead/background.mjs

@@ -0,0 +1,270 @@
+/**
+ * Background loop and rate-limit fallback — extracted from crew-lead.mjs
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+let _broadcastSSE = () => {};
+let _appendHistory = () => {};
+let _appendToBrain = () => {};
+let _dispatchTask = () => null;
+let _findNextRoadmapPhase = () => null;
+let _parseDispatches = () => [];
+let _pendingPipelines = new Map();
+let _readProjectsRegistry = () => [];
+let _autoAdvanceRoadmap = async () => {};
+let _tryRead = (p) => { try { return JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; } };
+
+let _bgConsciousnessEnabled = false;
+let _getBgConsciousnessEnabled = null;
+let _bgConsciousnessIntervalMs = 15 * 60 * 1000;
+let _bgConsciousnessModel = "groq/llama-3.1-8b-instant";
+let _brainPath = "";
+
+export const _agentTimeoutCounts = new Map();
+const _timeoutLog = [];
+let _lastBgConsciousnessAt = 0;
+let _bgLoopInterval = null;
+
+export function initBackground({
+  broadcastSSE,
+  appendHistory,
+  appendToBrain,
+  dispatchTask,
+  findNextRoadmapPhase,
+  parseDispatches,
+  pendingPipelines,
+  readProjectsRegistry,
+  autoAdvanceRoadmap,
+  tryRead,
+  bgConsciousnessEnabled,
+  getBgConsciousnessEnabled,
+  bgConsciousnessIntervalMs,
+  bgConsciousnessModel,
+  brainPath,
+}) {
+  if (broadcastSSE) _broadcastSSE = broadcastSSE;
+  if (appendHistory) _appendHistory = appendHistory;
+  if (appendToBrain) _appendToBrain = appendToBrain;
+  if (dispatchTask) _dispatchTask = dispatchTask;
+  if (findNextRoadmapPhase) _findNextRoadmapPhase = findNextRoadmapPhase;
+  if (parseDispatches) _parseDispatches = parseDispatches;
+  if (pendingPipelines) _pendingPipelines = pendingPipelines;
+  if (readProjectsRegistry) _readProjectsRegistry = readProjectsRegistry;
+  if (autoAdvanceRoadmap) _autoAdvanceRoadmap = autoAdvanceRoadmap;
+  if (tryRead) _tryRead = tryRead;
+  if (bgConsciousnessEnabled !== undefined) _bgConsciousnessEnabled = bgConsciousnessEnabled;
+  if (getBgConsciousnessEnabled) _getBgConsciousnessEnabled = getBgConsciousnessEnabled;
+  if (bgConsciousnessIntervalMs !== undefined) _bgConsciousnessIntervalMs = bgConsciousnessIntervalMs;
+  if (bgConsciousnessModel !== undefined) _bgConsciousnessModel = bgConsciousnessModel;
+  if (brainPath !== undefined) _brainPath = brainPath;
+}
+
+export function recordAgentTimeout(agent) {
+  _timeoutLog.push({ agent, ts: Date.now() });
+  const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+  while (_timeoutLog.length && _timeoutLog[0].ts < cutoff) _timeoutLog.shift();
+  const counts = {};
+  for (const e of _timeoutLog) counts[e.agent] = (counts[e.agent] || 0) + 1;
+  for (const [id, n] of Object.entries(counts)) _agentTimeoutCounts.set(id, n);
+}
+
+function getBgConsciousnessLLM() {
+  const cfg = _tryRead(path.join(os.homedir(), ".crewswarm", "crewswarm.json")) || {};
+  const providers = cfg.providers || {};
+  const [providerKey, ...modelParts] = String(_bgConsciousnessModel).split("/");
+  let modelId = modelParts.join("/") || "llama-3.1-8b-instant";
+  const p = providers[providerKey];
+  if (!p?.apiKey) return null;
+  const baseUrl = p.baseUrl || (providerKey === "groq" ? "https://api.groq.com/openai/v1" : "");
+  if (!baseUrl) return null;
+  // OpenRouter requires full ID (e.g. openrouter/hunter-alpha), not bare "hunter-alpha"
+  if ((providerKey === "openrouter" || (baseUrl || "").includes("openrouter.ai")) && modelId && !modelId.startsWith("openrouter/")) {
+    modelId = "openrouter/" + modelId;
+  }
+  return { baseUrl, apiKey: p.apiKey, modelId, providerKey };
+}
+
+const BG_CONSCIOUSNESS_LLM_TIMEOUT_MS = 60_000;
+
+async function runBackgroundConsciousnessDirect() {
+  const llm = getBgConsciousnessLLM();
+  if (!llm) return false;
+  let brainContent = "";
+  try {
+    const raw = fs.readFileSync(_brainPath, "utf8");
+    const stripped = raw.replace(/^#[^\n]*\n/gm, "").replace(/^Agents: append.*\n?/gm, "").replace(/^This is the persistent.*\n?/gm, "").replace(/^Read it to.*\n?/gm, "").replace(/^Write to it.*\n?/gm, "").trim();
+    if (stripped.length < 80) {
+      console.log("[bg-loop] Brain empty — skipping consciousness cycle");
+      return true;
+    }
+    brainContent = raw.slice(-6000);
+  } catch {
+    console.log("[bg-loop] brain.md not found — skipping consciousness cycle");
+    return true;
+  }
+  const system = "You are crew-main managing the process for the user. Reply in under 100 words. Output: 1) One sentence on system/crew state or suggested next step. 2) If something needs follow-up, emit exactly one line: @@BRAIN crew-main: <fact> OR @@DISPATCH {\"agent\":\"...\",\"task\":\"...\"}. Otherwise reply NO_ACTION.";
+  const user = `Shared memory (recent):\n${brainContent}\n\nWhat should the user know? Any follow-up? Reply briefly.`;
+  const messages = [{ role: "system", content: system }, { role: "user", content: user }];
+  let content;
+  try {
+    // Reasoning models (o1/o3/gpt-5 series) don't support max_tokens parameter
+    const isReasoningModel = /^(o1|o3|gpt-5)/i.test(llm.modelId);
+    const payload = { model: llm.modelId, messages, temperature: 0.5, stream: false };
+    if (!isReasoningModel) {
+      payload.max_tokens = 256;
+    }
+    const res = await fetch(`${llm.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "authorization": `Bearer ${llm.apiKey}` },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(BG_CONSCIOUSNESS_LLM_TIMEOUT_MS),
+    });
+    if (!res.ok) throw new Error(`${res.status}: ${await res.text().catch(() => "")}`);
+    const data = await res.json();
+    content = data?.choices?.[0]?.message?.content || "NO_ACTION";
+  } catch (e) {
+    console.error("[bg-loop] Background consciousness LLM failed:", e.message);
+    return true;
+  }
+  content = content.trim();
+  const brainMatch = content.match(/@@BRAIN\s+([^\n]+)/);
+  if (brainMatch) {
+    const entry = brainMatch[1].trim();
+    // Quality gate: reject chat fragments, status spam, and personality leaks
+    const BRAIN_JUNK = /^(crew-lead \(auto\)|Services:|System Status|All (systems|agents)|✅|Hello|Hey|Hi[,!.\s]|Yo[,!\s]|I'm |You |What |Now |Look|Always|Hell |Cute|First|RT bus)/i;
+    const looksLikeChat = entry.length < 20 || BRAIN_JUNK.test(entry) || !/[a-z]/.test(entry);
+    if (looksLikeChat) {
+      console.log("[bg-loop] @@BRAIN rejected (chat fragment):", entry.slice(0, 60));
+    } else {
+      try {
+        _appendToBrain("crew-main", entry);
+        console.log("[crew-lead] @@BRAIN (bg):", entry.slice(0, 60));
+      } catch (e) {
+        console.error("[bg-loop] Brain append failed:", e.message);
+      }
+    }
+  }
+  const dispatches = _parseDispatches(content);
+  for (const d of dispatches) {
+    try {
+      _dispatchTask(d.agent, d.task, "bg-consciousness", null);
+      console.log("[crew-lead] @@DISPATCH (bg):", d.agent, d.task?.slice(0, 50));
+    } catch (e) {
+      console.error("[bg-loop] Dispatch failed:", e.message);
+    }
+  }
+  const short = content.replace(/\n+/g, " ").slice(0, 800).trim();
+  const isNoAction = /^NO_ACTION/i.test(short) || short.length < 10;
+  if (!isNoAction) {
+    _appendHistory("default", "owner", "system", `[crew-main — background]: ${short}`);
+    _broadcastSSE({ type: "agent_reply", from: "crew-main", content: short, sessionId: "owner", _bg: true, ts: Date.now() });
+  }
+  try {
+    const statusPath = path.join(os.homedir(), ".crewswarm", "process-status.md");
+    const stamp = new Date().toISOString().slice(0, 19).replace("T", " ");
+    fs.writeFileSync(statusPath, `# Process status (crew-main)\nLast updated: ${stamp}\n\n${content.slice(0, 2000).replace(/@@/g, "")}\n`, "utf8");
+  } catch (_) {}
+  return true;
+}
+
+function backgroundLoop() {
+  try {
+    for (const [pid, pipeline] of _pendingPipelines) {
+      if (!pipeline._lastActivity) pipeline._lastActivity = Date.now();
+      const staleMs = Date.now() - pipeline._lastActivity;
+      if (staleMs > 15 * 60 * 1000 && pipeline.pendingTaskIds.size > 0) {
+        console.log(`[bg-loop] Pipeline ${pid} appears stalled (${Math.round(staleMs / 60000)}m no activity) — ${pipeline.pendingTaskIds.size} tasks pending`);
+        _broadcastSSE({ type: "pipeline_stalled", pipelineId: pid, staleMinutes: Math.round(staleMs / 60000), ts: Date.now() });
+      }
+    }
+
+    for (const [agent, count] of _agentTimeoutCounts) {
+      if (count >= 3) {
+        console.log(`[bg-loop] ⚠️  ${agent} has timed out ${count}x in last 24h — consider checking its model or restarting its bridge`);
+        _broadcastSSE({ type: "agent_timeout_pattern", agent, count, ts: Date.now() });
+      }
+    }
+
+    if (_pendingPipelines.size === 0) {
+      const projects = _readProjectsRegistry();
+      for (const project of projects) {
+        if (!project.outputDir || project.autoAdvance !== true) continue;
+        const nextPhase = _findNextRoadmapPhase(project.outputDir);
+        if (nextPhase) {
+          console.log(`[bg-loop] Auto-advancing "${project.name}" → "${nextPhase.title}"`);
+          _autoAdvanceRoadmap(project.outputDir, "owner");
+        }
+      }
+
+      const bgEnabled = _getBgConsciousnessEnabled ? _getBgConsciousnessEnabled() : _bgConsciousnessEnabled;
+      if (bgEnabled && Date.now() - _lastBgConsciousnessAt >= _bgConsciousnessIntervalMs) {
+        _lastBgConsciousnessAt = Date.now();
+        const useDirect = getBgConsciousnessLLM();
+        if (useDirect) {
+          console.log("[bg-loop] Running background consciousness via", useDirect.providerKey + "/" + useDirect.modelId);
+          runBackgroundConsciousnessDirect().catch((e) => {
+            console.error("[bg-loop] Background consciousness error:", e.message);
+          });
+        } else {
+          const consciousnessTask = `BACKGROUND CYCLE — you are managing the process for the user. Your reply is shown in their chat and written to ~/.crewswarm/process-status.md.
+@@READ_FILE ${_brainPath}
+Consider: what should the user know? (stalled work, next steps, blockers, health.) Reply in under 100 words.
+Reply with: 1) One sentence on system/crew state or suggested next step. 2) If something needs follow-up, emit exactly one @@BRAIN: or @@DISPATCH line (e.g. dispatch to fix a stuck pipeline). Otherwise reply NO_ACTION.`;
+          try {
+            _dispatchTask("crew-main", consciousnessTask, "bg-consciousness", null);
+            console.log("[bg-loop] Dispatched background consciousness cycle to crew-main (no cheap model configured)");
+          } catch (e) {
+            console.error("[bg-loop] Background consciousness dispatch failed:", e.message);
+          }
+        }
+      }
+    }
+  } catch (e) {
+    console.error("[bg-loop] Error:", e.message);
+  }
+}
+
+export function startBackgroundLoop() {
+  if (_bgLoopInterval) clearInterval(_bgLoopInterval);
+  _bgLoopInterval = setInterval(backgroundLoop, 5 * 60 * 1000);
+  console.log("[crew-lead] Background loop started (5m interval)");
+  const bgEnabled = _getBgConsciousnessEnabled ? _getBgConsciousnessEnabled() : _bgConsciousnessEnabled;
+  if (bgEnabled) {
+    console.log("[crew-lead] Background consciousness ON — reflect every " + (_bgConsciousnessIntervalMs / 60000) + "m when idle");
+  } else {
+    console.log("[crew-lead] Background consciousness OFF — toggle in Dashboard → Settings");
+  }
+}
+
+const _RATE_LIMIT_FALLBACK_STATIC = {
+  "crew-coder-back": "crew-coder",
+  "crew-coder-front": "crew-coder",
+  "crew-coder": "crew-main",
+  "crew-frontend": "crew-coder",
+  "crew-pm": "crew-main",
+  "crew-qa": "crew-main",
+  "crew-copywriter": "crew-main",
+  "crew-security": "crew-main",
+};
+const _ROLE_FALLBACK = {
+  coder: "crew-coder",
+  writer: "crew-copywriter",
+  researcher: "crew-main",
+  auditor: "crew-qa",
+  ops: "crew-main",
+  generalist: "crew-main",
+};
+
+export function getRateLimitFallback(agentId) {
+  if (_RATE_LIMIT_FALLBACK_STATIC[agentId]) return _RATE_LIMIT_FALLBACK_STATIC[agentId];
+  const swarm = _tryRead(path.join(os.homedir(), ".crewswarm", "crewswarm.json"));
+  const agent = (swarm?.agents || []).find(a => a.id === agentId);
+  if (agent?.fallbackModel) return agentId;
+  if (agent?._role && _ROLE_FALLBACK[agent._role]) return _ROLE_FALLBACK[agent._role];
+  return "crew-main";
+}
+
+export const RATE_LIMIT_PATTERN = /429|rate\s*limit|throttl|quota\s*exceeded|too\s*many\s*requests|resource_exhausted|overloaded/i;

package/lib/crew-lead/brain.mjs

@@ -0,0 +1,110 @@
+/**
+ * Brain, global rules, and search helpers — extracted from crew-lead.mjs
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { execSync, spawnSync } from "node:child_process";
+import { getSearchToolsConfig } from "../agents/permissions.mjs";
+
+let _brainPath = "";
+let _globalRulesPath = "";
+
+export function initBrain({ brainPath, globalRulesPath }) {
+  if (brainPath !== undefined) _brainPath = brainPath;
+  if (globalRulesPath !== undefined) _globalRulesPath = globalRulesPath;
+}
+
+export function appendToBrain(agentId, entry, projectDir = null) {
+  const date = new Date().toISOString().slice(0, 10);
+  const block = `\n## [${date}] ${agentId}: ${entry}\n`;
+  if (projectDir) {
+    const projectBrainDir = path.join(projectDir, ".crewswarm");
+    const projectBrainPath = path.join(projectBrainDir, "brain.md");
+    fs.mkdirSync(projectBrainDir, { recursive: true });
+    if (!fs.existsSync(projectBrainPath)) {
+      fs.writeFileSync(projectBrainPath, "# Project Brain\n\nAccumulated knowledge for this project. Agents append discoveries here.\n", "utf8");
+    }
+    fs.appendFileSync(projectBrainPath, block, "utf8");
+  } else {
+    if (!fs.existsSync(_brainPath)) fs.mkdirSync(path.dirname(_brainPath), { recursive: true });
+    fs.appendFileSync(_brainPath, block, "utf8");
+  }
+  return block.trim();
+}
+
+export function readGlobalRules() {
+  try { return fs.readFileSync(_globalRulesPath, "utf8").trim(); } catch { return ""; }
+}
+
+export function writeGlobalRules(content) {
+  fs.writeFileSync(_globalRulesPath, content, "utf8");
+  return content;
+}
+
+export function appendGlobalRule(rule) {
+  const existing = readGlobalRules();
+  const updated = existing ? `${existing}\n- ${rule}` : `# Global Agent Rules\n\n- ${rule}`;
+  writeGlobalRules(updated);
+  return updated;
+}
+
+export async function searchWithBrave(query) {
+  const key = getSearchToolsConfig()?.brave?.apiKey || process.env.BRAVE_API_KEY;
+  if (!key) return null;
+  try {
+    const res = await fetch(
+      `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=5&text_decorations=false`,
+      { headers: { "Accept": "application/json", "X-Subscription-Token": key }, signal: AbortSignal.timeout(8000) }
+    );
+    if (!res.ok) return null;
+    const data = await res.json();
+    const results = (data.web?.results || []).slice(0, 5);
+    if (!results.length) return null;
+    const text = results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.description || ""}\n   ${r.url}`).join("\n\n");
+    console.log(`[crew-lead] Brave search query="${query.slice(0, 80)}" → ${results.length} results`);
+    return text;
+  } catch { return null; }
+}
+
+export function getWorkspaceRoot() {
+  return process.env.CREW_LEAD_WORKSPACE || process.cwd();
+}
+
+/** Run a text search in the workspace; returns excerpt string or null. Uses rg then grep. */
+export function searchCodebase(query) {
+  const workspace = getWorkspaceRoot();
+  if (!query || query.length < 2) return null;
+  const maxOutput = 6000;
+  const args = [
+    "-F", "-i", "-n",
+    "-C", "1",
+    "--max-files", "20",
+    "--max-count", "3",
+    "--glob", "!node_modules",
+    "--glob", "!.git",
+    "--glob", "!*.min.js",
+    query,
+    workspace,
+  ];
+  try {
+    const out = spawnSync("rg", args, {
+      encoding: "utf8",
+      timeout: 5000,
+      maxBuffer: maxOutput,
+      windowsHide: true,
+    });
+    if (out.status !== 0 || !out.stdout?.trim()) return null;
+    const lines = out.stdout.trim().split("\n").slice(0, 25);
+    return lines.join("\n");
+  } catch {
+    try {
+      const out = execSync(
+        `grep -r -F -i -n --include="*.js" --include="*.mjs" --include="*.ts" --include="*.json" --include="*.md" -e ${JSON.stringify(query)} ${JSON.stringify(workspace)} 2>/dev/null | head -25`,
+        { encoding: "utf8", timeout: 5000, maxBuffer: maxOutput }
+      );
+      return out?.trim() || null;
+    } catch { return null; }
+  }
+}