min-agent 0.2.0 → 0.3.0

package/dist/tools/bash.js

@@ -1,99 +1,176 @@
 import { tool, jsonSchema } from "ai";
 import { spawn } from "child_process";
+import path from "path";
 import { confirm, isDangerousCommand, isAutoApprove } from "../confirm.js";
+import { writeFullToolOutput } from "../tool-output.js";
+const MAX_STREAM_BYTES = 200 * 1024;
+const MAX_OUTPUT_BYTES = 100_000;
 /** Track active child processes so they can be killed on abort (e.g. ESC). */
-const activeProcesses = new Set();
+const activeRuns = new Set();
+let sigintRegistered = false;
+/**
+ * Registered exactly once: Ctrl+C kills all active commands instead of leaking a handler per call.
+ * When nothing is running, re-dispatch the signal so the process can exit normally
+ * (single-shot mode must not swallow Ctrl+C).
+ */
+function ensureSigintHandler() {
+    if (sigintRegistered)
+        return;
+    sigintRegistered = true;
+    const onSigint = () => {
+        if (activeRuns.size === 0) {
+            process.removeListener("SIGINT", onSigint);
+            sigintRegistered = false;
+            process.kill(process.pid, "SIGINT");
+            return;
+        }
+        for (const run of [...activeRuns]) {
+            interruptRun(run);
+        }
+    };
+    process.on("SIGINT", onSigint);
+}
+function interruptRun(run) {
+    run.killed = true;
+    run.settled = true;
+    if (run.timer)
+        clearTimeout(run.timer);
+    killProcess(run.proc.pid);
+    run.resolve(formatOutput(run) + "\n\n[Command interrupted by user.]");
+}
 /** Kill all active child processes spawned by the bash tool. */
 export function killActiveProcesses() {
-    for (const proc of activeProcesses) {
-        killProcess(proc.pid);
+    for (const run of activeRuns) {
+        run.killed = true;
+        run.settled = true;
+        if (run.timer)
+            clearTimeout(run.timer);
+        killProcess(run.proc.pid);
+        run.resolve(formatOutput(run) + "\n\n[Command interrupted by user.]");
     }
-    activeProcesses.clear();
+    activeRuns.clear();
 }
 export const bashTool = tool({
-    description: "Run a shell command. Use this for system operations, running builds, tests, git commands, etc. The command runs in the current working directory. You SHOULD set a timeout based on how long you expect the command to take. If no timeout is set, the command runs until it finishes or the user manually interrupts (Ctrl+C).",
+    description: "Run a shell command. Use this for system operations, running builds, tests, git commands, etc. The command runs in the current working directory (or `cwd` if specified). You SHOULD set a timeout based on how long you expect the command to take. If no timeout is set, the command runs until it finishes or the user manually interrupts (Ctrl+C).",
     inputSchema: jsonSchema({
         type: "object",
         properties: {
             command: { type: "string", description: "The shell command to execute" },
             timeout: { type: "number", description: "Timeout in milliseconds. Set based on expected duration (e.g. 5000 for quick commands, 60000 for builds). Omit only for commands with unpredictable duration." },
+            cwd: { type: "string", description: "Working directory for the command (relative to the current directory or absolute)" },
         },
         required: ["command"],
     }),
-    execute: async ({ command, timeout }) => {
+    execute: async ({ command, timeout, cwd }) => {
         if (!isAutoApprove() && isDangerousCommand(command)) {
             const approved = await confirm(`Execute dangerous command: ${command}`);
             if (!approved)
                 return "Command rejected by user.";
         }
-        return new Promise((resolve) => {
-            const chunks = [];
-            let killed = false;
-            let timer;
-            // On Windows, force UTF-8 codepage to avoid Chinese garbled text
-            const isWin = process.platform === "win32";
-            const actualCommand = isWin ? `chcp 65001 >nul && ${command}` : command;
-            const proc = spawn(actualCommand, [], {
-                shell: true,
-                cwd: process.cwd(),
-                stdio: ["ignore", "pipe", "pipe"],
-                detached: process.platform !== "win32",
-                env: { ...process.env, ...(isWin ? { PYTHONIOENCODING: "utf-8" } : {}) },
-            });
-            activeProcesses.add(proc);
-            proc.stdout?.on("data", (chunk) => chunks.push(chunk));
-            proc.stderr?.on("data", (chunk) => chunks.push(chunk));
-            // Timeout kill (only if timeout is specified)
-            if (timeout && timeout > 0) {
-                timer = setTimeout(() => {
-                    killed = true;
-                    killProcess(proc.pid);
-                    resolve(getOutput(chunks) +
-                        `\n\n[Command timed out after ${timeout}ms and was killed. Retry with a larger timeout if needed.]`);
-                }, timeout);
+        return executeBash(command, timeout, cwd);
+    },
+});
+/** Shared bash execution engine (no permission prompt). Used by bashTool and the read-only variant. */
+export async function executeBash(command, timeout, cwd) {
+    ensureSigintHandler();
+    return new Promise((resolve) => {
+        const run = {
+            proc: undefined,
+            resolve,
+            stdoutChunks: [],
+            stderrChunks: [],
+            killed: false,
+            settled: false,
+            stdoutTruncated: false,
+            stderrTruncated: false,
+        };
+        activeRuns.add(run);
+        // On Windows, force UTF-8 codepage to avoid Chinese garbled text
+        const isWin = process.platform === "win32";
+        const actualCommand = isWin ? `chcp 65001 >nul && ${command}` : command;
+        const proc = spawn(actualCommand, [], {
+            shell: true,
+            cwd: cwd ? path.resolve(process.cwd(), cwd) : process.cwd(),
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: process.platform !== "win32",
+            env: { ...process.env, ...(isWin ? { PYTHONIOENCODING: "utf-8" } : {}) },
+        });
+        run.proc = proc;
+        const collect = (chunks, truncated) => (chunk) => {
+            const total = chunks.reduce((sum, c) => sum + c.byteLength, 0);
+            if (total >= MAX_STREAM_BYTES) {
+                run[truncated] = true;
+                return;
             }
-            // Allow user to interrupt with Ctrl+C (SIGINT)
-            const sigintHandler = () => {
-                killed = true;
-                if (timer)
-                    clearTimeout(timer);
+            chunks.push(chunk);
+        };
+        proc.stdout?.on("data", collect(run.stdoutChunks, "stdoutTruncated"));
+        proc.stderr?.on("data", collect(run.stderrChunks, "stderrTruncated"));
+        // Timeout kill (only if timeout is specified)
+        if (timeout && timeout > 0) {
+            run.timer = setTimeout(() => {
+                run.killed = true;
+                run.settled = true;
                 killProcess(proc.pid);
-                resolve(getOutput(chunks) + "\n\n[Command interrupted by user.]");
-            };
-            process.on("SIGINT", sigintHandler);
-            proc.on("close", (code) => {
-                activeProcesses.delete(proc);
-                process.removeListener("SIGINT", sigintHandler);
-                if (timer)
-                    clearTimeout(timer);
-                if (killed)
-                    return;
-                const output = getOutput(chunks);
-                if (code === 0) {
-                    resolve(output || "(no output)");
-                }
-                else {
-                    resolve(`Exit code ${code}\n${output || "(no output)"}`);
-                }
-            });
-            proc.on("error", (err) => {
-                activeProcesses.delete(proc);
-                process.removeListener("SIGINT", sigintHandler);
-                if (timer)
-                    clearTimeout(timer);
-                if (killed)
-                    return;
-                resolve(`Error: ${err.message}`);
-            });
+                resolve(formatOutput(run) +
+                    `\n\n[Command timed out after ${timeout}ms and was killed. Retry with a larger timeout if needed.]`);
+            }, timeout);
+        }
+        proc.on("close", (code) => {
+            activeRuns.delete(run);
+            if (run.timer)
+                clearTimeout(run.timer);
+            if (run.killed || run.settled)
+                return;
+            run.settled = true;
+            const output = formatOutput(run);
+            if (code === 0) {
+                resolve(output || "(no output)");
+            }
+            else {
+                resolve(`Exit code ${code}\n${output || "(no output)"}`);
+            }
         });
-    },
-});
-function getOutput(chunks) {
-    const output = Buffer.concat(chunks).toString("utf-8").trim();
-    if (output.length > 100_000) {
-        return output.slice(0, 50_000) + `\n\n...(truncated, ${output.length} bytes total)...\n\n` + output.slice(-10_000);
+        proc.on("error", (err) => {
+            activeRuns.delete(run);
+            if (run.timer)
+                clearTimeout(run.timer);
+            if (run.killed || run.settled)
+                return;
+            run.settled = true;
+            resolve(`Error: ${err.message}`);
+        });
+    });
+}
+/** Merge stdout + stderr, saved to disk when too large for the response budget. */
+function formatOutput(run) {
+    const out = Buffer.concat(run.stdoutChunks).toString("utf-8").trim();
+    const err = Buffer.concat(run.stderrChunks).toString("utf-8").trim();
+    let text = out;
+    if (err)
+        text = text ? `${text}\n\n--- stderr ---\n${err}` : err;
+    if (run.stdoutTruncated || run.stderrTruncated) {
+        text += `\n\n[Output capped at ${MAX_STREAM_BYTES} bytes; the remainder was discarded.]`;
     }
-    return output;
+    const total = Buffer.byteLength(text, "utf-8");
+    if (total <= MAX_OUTPUT_BYTES)
+        return text;
+    const filePath = writeFullToolOutput(text);
+    return `${truncateUtf8(text, MAX_OUTPUT_BYTES)}\n\nFull output saved to: ${filePath}`;
+}
+function truncateUtf8(text, maxBytes) {
+    const buf = Buffer.from(text, "utf-8");
+    const headLen = Math.floor(maxBytes * 0.5);
+    const tailLen = Math.floor(maxBytes * 0.1);
+    let h = headLen;
+    while (h > 0 && (buf[h] & 0xc0) === 0x80)
+        h--;
+    let t = buf.length - tailLen;
+    while (t < buf.length && (buf[t] & 0xc0) === 0x80)
+        t++;
+    return (buf.subarray(0, h).toString("utf-8") +
+        `\n\n...(truncated, ${buf.length} bytes total)...\n\n` +
+        buf.subarray(Math.max(t, h)).toString("utf-8"));
 }
 function killProcess(pid) {
     if (!pid)

package/dist/tools/code_search.js

@@ -1,8 +1,6 @@
 import { tool, jsonSchema } from "ai";
 import { truncateToolOutput } from "../tool-output.js";
-const EXA_MCP_URL = process.env.EXA_API_KEY
-    ? `https://mcp.exa.ai/mcp?exaApiKey=${encodeURIComponent(process.env.EXA_API_KEY)}`
-    : "https://mcp.exa.ai/mcp";
+const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
 export const codeSearchTool = tool({
     description: `Search and get relevant context for any programming task using Exa Code API.
 Provides high-quality, fresh context for libraries, SDKs, and APIs.
@@ -59,6 +57,7 @@ async function callExaCode(query, tokensNum) {
         headers: {
             "Content-Type": "application/json",
             Accept: "application/json, text/event-stream",
+            ...(process.env.EXA_API_KEY ? { Authorization: `Bearer ${process.env.EXA_API_KEY}` } : {}),
         },
         body,
         signal: AbortSignal.timeout(30000),
@@ -66,8 +65,10 @@ async function callExaCode(query, tokensNum) {
     if (!response.ok) {
         throw new Error(`Exa API returned ${response.status}`);
     }
-    const text = await response.text();
-    // Parse SSE response: look for "data: {...}" lines
+    return await parseExaResponse(await response.text());
+}
+/** Parse either an SSE stream or a direct JSON body into the tool result text. */
+async function parseExaResponse(text) {
     for (const line of text.split("\n")) {
         if (!line.startsWith("data: "))
             continue;

package/dist/tools/edit.js

@@ -1,5 +1,6 @@
 import { tool, jsonSchema } from "ai";
-import { readFileSync, writeFileSync, existsSync } from "fs";
+import { readFile, writeFile, rename, unlink } from "fs/promises";
+import { randomBytes } from "crypto";
 import path from "path";
 import { confirm, isAutoApprove } from "../confirm.js";
 export const editTool = tool({
@@ -14,11 +15,18 @@ export const editTool = tool({
         required: ["filePath", "oldText", "newText"],
     }),
     execute: async ({ filePath, oldText, newText }) => {
+        if (!oldText)
+            return "Error: oldText must not be empty";
+        if (oldText === newText)
+            return "No change: oldText equals newText";
         const resolved = path.resolve(process.cwd(), filePath);
-        if (!existsSync(resolved)) {
-            return `Error: File not found: ${filePath}`;
+        let content;
+        try {
+            content = await readFile(resolved, "utf-8");
+        }
+        catch (err) {
+            return `Error: cannot read ${filePath}: ${err.message}`;
         }
-        const content = readFileSync(resolved, "utf-8");
         const occurrences = content.split(oldText).length - 1;
         if (occurrences === 0) {
             // Try to help: show nearby content
@@ -37,13 +45,21 @@ export const editTool = tool({
         }
         // Confirm edit
         if (!isAutoApprove()) {
-            const preview = oldText.length > 80 ? oldText.slice(0, 80) + "..." : oldText;
-            const approved = await confirm(`Edit ${filePath}: replace "${preview}"`);
+            const preview = (s) => (s.length > 80 ? s.slice(0, 80) + "..." : s);
+            const approved = await confirm(`Edit ${filePath}:\nreplace "${preview(oldText)}"\nwith "${preview(newText)}"`);
             if (!approved)
                 return "Edit rejected by user.";
         }
         const updated = content.replace(oldText, newText);
-        writeFileSync(resolved, updated, "utf-8");
+        const tmpPath = path.join(path.dirname(resolved), `.${path.basename(resolved)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
+        try {
+            await writeFile(tmpPath, updated, "utf-8");
+            await rename(tmpPath, resolved);
+        }
+        catch (err) {
+            await unlink(tmpPath).catch(() => { });
+            return `Error: cannot write ${filePath}: ${err.message}`;
+        }
         const oldLines = oldText.split("\n").length;
         const newLines = newText.split("\n").length;
         return `Edited ${filePath}: replaced ${oldLines} line(s) with ${newLines} line(s)`;

package/dist/tools/explore.js

@@ -1,6 +1,6 @@
 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";
@@ -17,7 +17,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
@@ -28,7 +28,7 @@ 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) {
+export function createExploreTool(modelId, abortSignal, onUsage) {
     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 +51,31 @@ 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);
+                if (result.usage)
+                    onUsage?.(result.usage);
+                console.error(`\x1b[90m  └─ ✓ Done\x1b[0m`);
+                return truncateToolOutput(result.text, { direction: "head" }).content;
             }
             catch (err) {
-                console.log(`\x1b[90m  └─ ✗ Failed: ${err.message}\x1b[0m`);
+                if (abortSignal?.aborted)
+                    return "Explore cancelled by user.";
+                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) {
     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,6 +84,8 @@ ${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,
@@ -87,6 +93,7 @@ Task: ${query}`;
         tools,
         stopWhen: stepCountIs(EXPLORE_MAX_STEPS),
         maxRetries: 2,
+        abortSignal: signal,
         onError() { },
     });
     let assistantText = "";
@@ -96,9 +103,70 @@ 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`);
                 break;
+            case "error":
+                controller.abort();
+                return { text: stripThinkingFromAssistantText(assistantText) || `[Explore error: ${event.error}]` };
         }
     }
-    return stripThinkingFromAssistantText(assistantText) || "(explore agent produced no output)";
+    let usage;
+    try {
+        usage = await result.usage;
+    }
+    catch { }
+    return {
+        text: 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,5 +1,5 @@
 import { tool, jsonSchema } from "ai";
-import { globSync } from "glob";
+import { glob } from "glob";
 import { truncateToolOutput } from "../tool-output.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.",
@@ -13,9 +13,9 @@ export const globTool = tool({
     }),
     execute: async ({ pattern, cwd }) => {
         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)