min-agent 0.2.1 → 0.4.0

package/dist/tools/explore.js

@@ -1,12 +1,16 @@
 import { tool, jsonSchema, streamText, stepCountIs } from "ai";
 import { resolveModel } from "../provider.js";
-import { bashTool } from "./bash.js";
+import { executeBash } from "./bash.js";
 import { readTool } from "./read.js";
 import { globTool } from "./glob.js";
 import { grepTool } from "./grep.js";
 import { stripThinkingFromAssistantText } from "../assistant-stream.js";
+import { unwrapXmlSearchTags } from "../xml-search.js";
 import { truncateToolOutput } from "../tool-output.js";
-const EXPLORE_SYSTEM = `You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+import { log } from "../logger.js";
+import { getEffectiveConfig } from "../config.js";
+function exploreSystem() {
+    return `You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
 
 Your strengths:
 - Rapidly finding files using glob patterns
@@ -17,7 +21,7 @@ Guidelines:
 - Use glob for broad file pattern matching
 - Use grep for searching file contents with regex
 - Use read when you know the specific file path
-- Use bash ONLY for read-only operations (ls, find, cat, wc, head, tail)
+- Use bash ONLY for read-only inspection (ls, find, cat, wc, head, tail, grep, git status/log/diff)
 - Adapt your search approach based on the thoroughness level specified
 - Return file paths as absolute paths in your final response
 - Do NOT create, modify, or delete any files
@@ -27,8 +31,14 @@ Complete the search request efficiently and report findings clearly.
 
 Working directory: ${process.cwd()}
 Platform: ${process.platform}`;
+}
 const EXPLORE_MAX_STEPS = 20;
-export function createExploreTool(modelId) {
+function resolveExploreSteps(explicit) {
+    const configured = getEffectiveConfig().agent?.exploreMaxSteps;
+    const value = explicit ?? configured ?? EXPLORE_MAX_STEPS;
+    return Number.isFinite(value) && value >= 1 ? Math.floor(value) : EXPLORE_MAX_STEPS;
+}
+export function createExploreTool(modelId, abortSignal, onUsage, context = {}) {
     return tool({
         description: `Deep codebase exploration agent. Use this to understand project structure, find files by patterns, search code for keywords, trace module relationships, or answer questions about the codebase.
 
@@ -51,27 +61,32 @@ Examples:
         }),
         execute: async ({ query, thoroughness }) => {
             const level = thoroughness ?? "medium";
-            console.log(`\x1b[90m  ┌─ Explore (${level}): ${query.slice(0, 60)}\x1b[0m`);
+            console.error(`\x1b[90m  ┌─ Explore (${level}): ${query.slice(0, 60)}\x1b[0m`);
             try {
-                const result = await runExploreAgent(query, level, modelId);
-                console.log(`\x1b[90m  └─ ✓ Done\x1b[0m`);
-                return truncateToolOutput(result, { direction: "head" }).content;
+                const result = await runExploreAgent(query, level, modelId, abortSignal, context);
+                if (result.usage)
+                    onUsage?.(result.usage);
+                console.error(`\x1b[90m  └─ ✓ Done\x1b[0m`);
+                return truncateToolOutput(result.text, { direction: "tail" }).content;
             }
             catch (err) {
-                console.log(`\x1b[90m  └─ ✗ Failed: ${err.message}\x1b[0m`);
+                if (abortSignal?.aborted)
+                    return "Explore cancelled by user.";
+                log("error", `explore agent failed: ${err?.message ?? String(err)}`);
+                console.error(`\x1b[90m  └─ ✗ Failed: ${err.message}\x1b[0m`);
                 return `Explore error: ${err.message}`;
             }
         },
     });
 }
-async function runExploreAgent(query, thoroughness, modelId) {
+async function runExploreAgent(query, thoroughness, modelId, abortSignal, context = {}) {
     const model = resolveModel(modelId);
     // Read-only tools only
     const tools = {
         glob: globTool,
         grep: grepTool,
         read: readTool,
-        bash: bashTool, // bash is available but prompt restricts to read-only
+        bash: readOnlyBashTool,
     };
     const prompt = `Thoroughness level: ${thoroughness}
 ${thoroughness === "quick" ? "Do a quick search (1-3 tool calls max)." : ""}
@@ -80,14 +95,19 @@ ${thoroughness === "thorough" ? "Do a comprehensive analysis. Check multiple loc
 
 Task: ${query}`;
     const messages = [{ role: "user", content: prompt }];
+    const controller = new AbortController();
+    const signal = abortSignal ? AbortSignal.any([abortSignal, controller.signal]) : controller.signal;
     const result = streamText({
         model,
-        system: EXPLORE_SYSTEM,
+        system: exploreSystem(),
         messages,
         tools,
-        stopWhen: stepCountIs(EXPLORE_MAX_STEPS),
+        stopWhen: stepCountIs(resolveExploreSteps(context.maxSteps)),
         maxRetries: 2,
-        onError() { },
+        abortSignal: signal,
+        onError({ error }) {
+            log("warn", `explore step failed (will retry): ${String(error)}`);
+        },
     });
     let assistantText = "";
     for await (const event of result.fullStream) {
@@ -96,9 +116,117 @@ Task: ${query}`;
                 assistantText += event.text;
                 break;
             case "tool-call":
-                console.log(`\x1b[90m  │ ⚡ ${event.toolName}\x1b[0m`);
+                console.error(`\x1b[90m  │ ⚡ ${event.toolName}\x1b[0m`);
+                if (context.shouldStop?.()) {
+                    log("warn", "explore agent stopped: parent budget reached");
+                    controller.abort();
+                    return {
+                        text: unwrapXmlSearchTags(stripThinkingFromAssistantText(assistantText)) +
+                            "\n\n[Explore stopped: run budget reached]",
+                    };
+                }
                 break;
+            case "error":
+                log("error", `explore stream error: ${String(event.error)}`);
+                controller.abort();
+                return {
+                    text: unwrapXmlSearchTags(stripThinkingFromAssistantText(assistantText)) || `[Explore error: ${event.error}]`,
+                };
         }
     }
-    return stripThinkingFromAssistantText(assistantText) || "(explore agent produced no output)";
+    let usage;
+    try {
+        usage = await result.usage;
+    }
+    catch { }
+    return {
+        text: unwrapXmlSearchTags(stripThinkingFromAssistantText(assistantText)) || "(explore agent produced no output)",
+        usage,
+    };
 }
+/* ── Read-only bash: white-listed commands only, no redirection / chaining ── */
+const READ_ONLY_BINS = new Set([
+    "ls",
+    "find",
+    "cat",
+    "wc",
+    "head",
+    "tail",
+    "grep",
+    "rg",
+    "tree",
+    "pwd",
+    "stat",
+    "du",
+    "file",
+    "which",
+    "echo",
+    "printf",
+    "sort",
+    "uniq",
+    "cut",
+    "tr",
+    "awk",
+    "sed",
+    "basename",
+    "dirname",
+    "realpath",
+    "env",
+    "printenv",
+    "git",
+]);
+const READ_ONLY_GIT_CMDS = new Set([
+    "status",
+    "log",
+    "diff",
+    "show",
+    "rev-parse",
+    "branch",
+    "remote",
+    "tag",
+    "ls-files",
+    "help",
+    "--version",
+    "version",
+]);
+/** True if the command only inspects state (no writes, redirection, pipes, or chaining). */
+export function isReadOnlyCommand(command) {
+    const trimmed = command.trim();
+    if (!trimmed)
+        return false;
+    if (/[<>|]|&&|;|`|\$\(/.test(trimmed))
+        return false;
+    const tokens = trimmed.split(/\s+/);
+    const bin = tokens[0].toLowerCase();
+    if (!READ_ONLY_BINS.has(bin))
+        return false;
+    if (bin === "git") {
+        const sub = tokens[1]?.toLowerCase();
+        if (!sub || !READ_ONLY_GIT_CMDS.has(sub))
+            return false;
+    }
+    if (bin === "find" && /\s-(delete|exec|ok|execdir)\b/.test(trimmed))
+        return false;
+    if ((bin === "sed" || bin === "awk" || bin === "perl") && /\s-i(\.[a-zA-Z0-9_-]+)?\b/.test(trimmed))
+        return false;
+    return true;
+}
+export const readOnlyBashTool = tool({
+    description: "Run a READ-ONLY shell command (ls, find, cat, wc, head, tail, grep, git status/log/diff, etc.). " +
+        "File modification, redirection, and command chaining are blocked.",
+    inputSchema: jsonSchema({
+        type: "object",
+        properties: {
+            command: { type: "string", description: "The read-only shell command to execute" },
+            timeout: { type: "number", description: "Timeout in milliseconds" },
+            cwd: { type: "string", description: "Working directory (relative or absolute)" },
+        },
+        required: ["command"],
+    }),
+    execute: async ({ command, timeout, cwd }) => {
+        if (!isReadOnlyCommand(command)) {
+            return `Error: "${command.slice(0, 80)}" is not a read-only command. Allowed: ${[...READ_ONLY_BINS].join(", ")} (read-only git subcommands only).`;
+        }
+        return executeBash(command, timeout, cwd);
+    },
+});

package/dist/tools/glob.js

@@ -1,6 +1,7 @@
 import { tool, jsonSchema } from "ai";
-import { globSync } from "glob";
+import { glob } from "glob";
 import { truncateToolOutput } from "../tool-output.js";
+import { pathAccessError } from "../sandbox.js";
 export const globTool = tool({
     description: "Find files matching a glob pattern. Returns a list of file paths. Use this to discover project structure and find files.",
     inputSchema: jsonSchema({
@@ -12,10 +13,13 @@ export const globTool = tool({
         required: ["pattern"],
     }),
     execute: async ({ pattern, cwd }) => {
+        const denied = pathAccessError(cwd ?? ".", "read");
+        if (denied)
+            return `Error: ${denied}`;
         try {
-            const matches = globSync(pattern, {
+            const matches = await glob(pattern, {
                 cwd: cwd ?? process.cwd(),
-                ignore: ["**/node_modules/**", "**/.git/**"],
+                ignore: ["**/node_modules/**", "**/.git/**", "**/dist/**", "**/build/**"],
                 nodir: true,
             });
             if (matches.length === 0)

package/dist/tools/grep.js

@@ -1,8 +1,127 @@
 import { tool, jsonSchema } from "ai";
-import { execSync } from "child_process";
+import { readdir, readFile, stat } from "fs/promises";
+import { spawn } from "child_process";
+import path from "path";
 import { truncateToolOutput } from "../tool-output.js";
+import { pathAccessError } from "../sandbox.js";
+const IGNORED_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", ".out", "coverage", ".min-agent"]);
+const MAX_RESULTS = 500;
+const MAX_FILE_BYTES = 5 * 1024 * 1024;
+const MAX_RG_OUTPUT_BYTES = 8 * 1024 * 1024;
+const WALK_CONCURRENCY = 8;
+/** Convert a simple glob like "*.ts" into an anchored regex for file names. */
+function globToRegex(glob) {
+    const escaped = glob
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, ".*")
+        .replace(/\?/g, ".");
+    return new RegExp(`^${escaped}$`);
+}
+/** Fast path: shell out to ripgrep when available. Resolves null if rg is missing or fails. */
+function rgSearch(pattern, root, includeRegex, ignore) {
+    const args = [
+        "--no-heading",
+        "--line-number",
+        "-i",
+        "-e",
+        pattern,
+        "--max-count",
+        "1",
+        "-g",
+        "!*.lock",
+        "--max-filesize",
+        String(MAX_FILE_BYTES),
+    ];
+    for (const dir of ignore)
+        args.push("-g", `!${dir}/**`);
+    if (includeRegex) {
+        const glob = includeRegex.source.replace(/^\^/, "").replace(/\$$/, "").replace(/\\\./g, ".").replace(/\.\*/g, "*");
+        args.push("-g", glob);
+    }
+    args.push(root);
+    return new Promise((resolve) => {
+        const child = spawn("rg", args, { stdio: ["ignore", "pipe", "pipe"] });
+        const chunks = [];
+        let total = 0;
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        const timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            finish(null);
+        }, 15000);
+        child.stdout.on("data", (chunk) => {
+            total += chunk.byteLength;
+            if (total > MAX_RG_OUTPUT_BYTES) {
+                child.kill("SIGKILL");
+                finish(null);
+                return;
+            }
+            chunks.push(chunk);
+        });
+        child.on("error", () => finish(null));
+        child.on("close", (code) => {
+            if (code === 1)
+                finish([]);
+            else if (code === 0)
+                finish(Buffer.concat(chunks).toString("utf-8").split("\n").filter(Boolean).slice(0, MAX_RESULTS));
+            else
+                finish(null);
+        });
+    });
+}
+async function walk(dir, regex, includeRegex, results) {
+    const dirQueue = [dir];
+    const worker = async () => {
+        while (dirQueue.length > 0 && results.length < MAX_RESULTS) {
+            const current = dirQueue.pop();
+            let entries;
+            try {
+                entries = await readdir(current, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            await Promise.all(entries.map(async (entry) => {
+                const full = path.join(current, entry.name);
+                if (entry.isDirectory()) {
+                    if (!IGNORED_DIRS.has(entry.name) && results.length < MAX_RESULTS)
+                        dirQueue.push(full);
+                    return;
+                }
+                if (!entry.isFile())
+                    return;
+                if (includeRegex && !includeRegex.test(entry.name))
+                    return;
+                try {
+                    const info = await stat(full);
+                    if (info.size > MAX_FILE_BYTES)
+                        return;
+                    const content = await readFile(full, "utf-8");
+                    if (content.includes("\0"))
+                        return;
+                    const lines = content.split("\n");
+                    for (let i = 0; i < lines.length && results.length < MAX_RESULTS; i++) {
+                        if (regex.test(lines[i])) {
+                            results.push(`${path.relative(process.cwd(), full)}:${i + 1}:${lines[i]}`);
+                        }
+                    }
+                }
+                catch {
+                    // unreadable file — skip
+                }
+            }));
+        }
+    };
+    await Promise.all(Array.from({ length: WALK_CONCURRENCY }, worker));
+}
 export const grepTool = tool({
-    description: "Search for a pattern in files using grep. Returns matching lines with file paths and line numbers. Use this to find code references, usages, and definitions.",
+    description: "Search for a pattern in files using regex. Returns matching lines with file paths and line numbers. Use this to find code references, usages, and definitions.",
     inputSchema: jsonSchema({
         type: "object",
         properties: {
@@ -13,22 +132,42 @@ export const grepTool = tool({
         required: ["pattern"],
     }),
     execute: async ({ pattern, path: searchPath, include }) => {
-        const target = searchPath ?? ".";
-        const includeFlag = include ? `--include='${include}'` : "";
-        const cmd = `grep -rn ${includeFlag} --color=never -E '${pattern.replace(/'/g, "'\\''")}' '${target}' 2>/dev/null | head -50`;
         try {
-            const output = execSync(cmd, {
-                encoding: "utf-8",
-                cwd: process.cwd(),
-                timeout: 10000,
-                maxBuffer: 512 * 1024,
-            });
-            const text = output.trim() || "No matches found";
+            const regex = new RegExp(pattern);
+            const includeRegex = include ? globToRegex(include) : null;
+            const root = path.resolve(process.cwd(), searchPath ?? ".");
+            const denied = pathAccessError(root, "read");
+            if (denied)
+                return `Error: ${denied}`;
+            const results = [];
+            const info = await stat(root).catch(() => null);
+            if (!info)
+                return `Error: path not found: ${searchPath ?? "."}`;
+            if (info.isFile()) {
+                try {
+                    const content = await readFile(root, "utf-8");
+                    if (!content.includes("\0")) {
+                        content.split("\n").forEach((line, i) => {
+                            if (regex.test(line))
+                                results.push(`${root}:${i + 1}:${line}`);
+                        });
+                    }
+                }
+                catch { }
+            }
+            else {
+                const rgResults = await rgSearch(pattern, root, includeRegex, [...IGNORED_DIRS]);
+                if (rgResults !== null) {
+                    results.push(...rgResults);
+                }
+                else {
+                    await walk(root, regex, includeRegex, results);
+                }
+            }
+            const text = results.length > 0 ? results.join("\n") : "No matches found";
             return truncateToolOutput(text, { direction: "head" }).content;
         }
         catch (err) {
-            if (err.status === 1)
-                return "No matches found";
             return `Error: ${err.message}`;
         }
     },

package/dist/tools/index.js

@@ -2,40 +2,29 @@ import { bashTool } from "./bash.js";
 import { readTool } from "./read.js";
 import { writeTool } from "./write.js";
 import { editTool } from "./edit.js";
+import { applyPatchTool } from "./apply_patch.js";
 import { globTool } from "./glob.js";
 import { grepTool } from "./grep.js";
 import { webSearchTool } from "./web_search.js";
 import { webFetchTool } from "./web_fetch.js";
-import { todoTool } from "./todo.js";
 import { questionTool } from "./question.js";
 import { codeSearchTool } from "./code_search.js";
-/** Chat mode: general assistant tools (fewer tools = less token overhead) */
-export function createChatTools() {
-    const tools = {
-        bash: bashTool,
-        read: readTool,
-        write: writeTool,
-        edit: editTool,
-        glob: globTool,
-        grep: grepTool,
-        web_search: webSearchTool,
-        web_fetch: webFetchTool,
-        question: questionTool,
-    };
-    return tools;
-}
-/** Code mode: full tool set including task tracking and code search */
-export function createCodeTools() {
+/**
+ * Builtin tools shared by main runs and sub-agents. `todo` is deliberately
+ * absent: it must be bound to a per-run TaskState, so callers register their
+ * own instance via createTodoTool.
+ */
+export function createTools() {
     const tools = {
         bash: bashTool,
         read: readTool,
         write: writeTool,
         edit: editTool,
+        apply_patch: applyPatchTool,
         glob: globTool,
         grep: grepTool,
-        web_search: webSearchTool,
+        search_web: webSearchTool,
         web_fetch: webFetchTool,
-        todo: todoTool,
         question: questionTool,
     };
     if (process.env.EXA_API_KEY) {
@@ -43,7 +32,3 @@ export function createCodeTools() {
     }
     return tools;
 }
-/** @deprecated Use createChatTools or createCodeTools */
-export function createTools() {
-    return createChatTools();
-}

package/dist/tools/question.js

@@ -1,5 +1,6 @@
 import { tool, jsonSchema } from "ai";
-import readline from "readline";
+import { askQuestion } from "../confirm.js";
+import { normalizeQuestionOptions, normalizeQuestionPrompt } from "../question-format.js";
 export const questionTool = tool({
     description: `Ask the user a question to get clarification before proceeding. Use this when:
 - The task is ambiguous and you need more information
@@ -7,47 +8,47 @@ export const questionTool = tool({
 - You need confirmation before a potentially destructive action
 - You're unsure about a requirement or preference
 
-Provide clear, specific questions. Optionally include numbered options for the user to choose from.`,
+Provide a clear, specific question. Optional choices should be an array of strings. Object items with label/description are also accepted.`,
     inputSchema: jsonSchema({
         type: "object",
         properties: {
             question: { type: "string", description: "The question to ask the user" },
             options: {
                 type: "array",
-                items: { type: "string" },
-                description: "Optional list of choices for the user to pick from",
+                items: {
+                    anyOf: [
+                        { type: "string" },
+                        {
+                            type: "object",
+                            properties: {
+                                label: { type: "string" },
+                                description: { type: "string" },
+                                key: { type: "string" },
+                            },
+                        },
+                    ],
+                },
+                description: "Optional list of choices. Prefer plain strings; {label, description} objects are also accepted.",
             },
         },
         required: ["question"],
     }),
     execute: async ({ question, options }) => {
-        console.log();
-        console.log(`\x1b[33m❓ ${question}\x1b[0m`);
-        if (options && options.length > 0) {
-            for (let i = 0; i < options.length; i++) {
-                console.log(`\x1b[90m   ${i + 1}. ${options[i]}\x1b[0m`);
-            }
-        }
-        const answer = await askUser();
-        // If user picked a number and options exist, resolve it
-        if (options && options.length > 0) {
-            const idx = parseInt(answer) - 1;
-            if (idx >= 0 && idx < options.length) {
-                return `User chose: ${options[idx]}`;
-            }
+        const prompt = normalizeQuestionPrompt(question);
+        if (!prompt.trim())
+            return "Error: question is required.";
+        const choices = normalizeQuestionOptions(options);
+        const answer = await askQuestion(prompt, choices.length > 0 ? choices : undefined);
+        if (answer === null)
+            return "User cancelled the question";
+        if (choices.length > 0) {
+            const exact = choices.find((c) => c === answer);
+            if (exact)
+                return `User chose: ${exact}`;
+            const idx = parseInt(answer, 10) - 1;
+            if (Number.isInteger(idx) && idx >= 0 && idx < choices.length)
+                return `User chose: ${choices[idx]}`;
         }
         return `User answered: ${answer}`;
     },
 });
-function askUser() {
-    return new Promise((resolve) => {
-        const rl = readline.createInterface({
-            input: process.stdin,
-            output: process.stdout,
-        });
-        rl.question("\x1b[36m   → \x1b[0m", (answer) => {
-            rl.close();
-            resolve(answer.trim() || "(no answer)");
-        });
-    });
-}