min-agent 0.2.1 → 0.4.0

package/dist/tools/backend.js

@@ -0,0 +1,61 @@
+/**
+ * Shared plumbing for the HTTP-backed tools (`search_web`, `web_fetch`):
+ * base-URL resolution, consistent "how to configure this" copy, and fetch
+ * error description. Kept separate so both tools report problems the same way.
+ */
+/** Human-readable pointer to both configuration channels. */
+export function configHint(spec) {
+    return `Configure a working instance via "${spec.configKey}" in ~/.min-agent/config.json or the ${spec.envName} env var.`;
+}
+/**
+ * Normalize a user-supplied base URL: trim whitespace and trailing slashes so
+ * callers can always append "/path" without producing a double slash.
+ * Returns an error string for anything that is not an absolute http(s) URL.
+ */
+export function normalizeBaseURL(raw, source) {
+    const trimmed = raw.trim();
+    if (trimmed === "")
+        return { ok: false, error: `${source} is empty` };
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return { ok: false, error: `${source} is not a valid absolute URL: ${trimmed}` };
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return { ok: false, error: `${source} must use http or https, got "${parsed.protocol}"` };
+    }
+    // Keep any path prefix (instances behind a reverse proxy subpath) but drop
+    // query/hash and trailing slashes.
+    parsed.search = "";
+    parsed.hash = "";
+    return { ok: true, base: parsed.toString().replace(/\/+$/, "") };
+}
+/**
+ * Resolve a backend base URL. The environment variable wins over the config
+ * file so a single run can be redirected from the shell without editing
+ * config.json; the built-in default is the last resort.
+ */
+export function resolveBackendBase(spec, configValue) {
+    const env = process.env[spec.envName];
+    if (env?.trim())
+        return normalizeBaseURL(env, spec.envName);
+    if (configValue?.trim())
+        return normalizeBaseURL(configValue, `"${spec.configKey}" in config.json`);
+    return normalizeBaseURL(spec.fallback, "the built-in default backend URL");
+}
+/** Turn a thrown fetch error into a short, actionable sentence. */
+export function describeFetchError(err) {
+    if (err instanceof Error) {
+        // AbortSignal.timeout rejects with a TimeoutError DOMException.
+        if (err.name === "TimeoutError" || err.name === "AbortError")
+            return "the request timed out";
+        const cause = err.cause;
+        const causeCode = typeof cause === "object" && cause !== null ? cause.code : undefined;
+        if (typeof causeCode === "string")
+            return `${err.message} (${causeCode})`;
+        return err.message;
+    }
+    return String(err);
+}

package/dist/tools/bash.js

@@ -1,99 +1,214 @@
 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";
+import { planSandboxedSpawn } from "../sandbox.js";
+import { getEffectiveConfig } from "../config.js";
+const MAX_STREAM_BYTES = 200 * 1024;
+const MAX_OUTPUT_BYTES = 100_000;
+/** Default wall-clock limit so one hung command cannot stall the whole turn. */
+export const DEFAULT_BASH_TIMEOUT_MS = 10 * 60 * 1000;
+/** Resolve the timeout for a command: explicit > config > default. 0 disables. */
+export function resolveBashTimeout(explicit) {
+    if (typeof explicit === "number" && Number.isFinite(explicit) && explicit >= 0)
+        return Math.floor(explicit);
+    const configured = getEffectiveConfig().tools?.bashTimeoutMs;
+    if (typeof configured === "number" && Number.isFinite(configured) && configured >= 0)
+        return Math.floor(configured);
+    return DEFAULT_BASH_TIMEOUT_MS;
+}
 /** 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;
+/** Sandbox caveats are shown once per process to avoid spamming every command. */
+let sandboxWarningShown = false;
+/** Test hook: allow the sandbox caveat to be shown again. */
+export function resetSandboxWarningShown() {
+    sandboxWarningShown = 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). Commands are killed after 10 minutes by default; set `timeout` for anything expected to run longer (or shorter).",
     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." },
+            timeout: {
+                type: "number",
+                description: "Timeout in milliseconds. Defaults to 600000 (10 minutes). Set a smaller value for quick commands or a larger one for long builds.",
+            },
+            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 isWin = process.platform === "win32";
+        const resolvedCwd = cwd ? path.resolve(process.cwd(), cwd) : process.cwd();
+        const plan = planSandboxedSpawn(command, resolvedCwd, {
+            ...process.env,
+            ...(isWin ? { PYTHONIOENCODING: "utf-8" } : {}),
+        });
+        if ("error" in plan) {
+            resolve(plan.error);
+            return;
+        }
+        let notice = "";
+        if (plan.warning && !sandboxWarningShown) {
+            sandboxWarningShown = true;
+            notice = `${plan.warning}\n\n`;
+        }
+        const run = {
+            proc: undefined,
+            resolve: (value) => resolve(notice + value),
+            stdoutChunks: [],
+            stderrChunks: [],
+            killed: false,
+            settled: false,
+            stdoutTruncated: false,
+            stderrTruncated: false,
+        };
+        activeRuns.add(run);
+        const proc = spawn(plan.file, plan.args, {
+            shell: plan.shell,
+            cwd: plan.cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: process.platform !== "win32",
+            env: plan.env,
+        });
+        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 (explicit value, config default, or the 10 minute fallback)
+        const effectiveTimeout = resolveBashTimeout(timeout);
+        if (effectiveTimeout > 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}`);
-            });
+                run.resolve(formatOutput(run) +
+                    `\n\n[Command timed out after ${effectiveTimeout}ms and was killed. Retry with a larger timeout if needed.]`);
+            }, effectiveTimeout);
+        }
+        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) {
+                run.resolve(output || "(no output)");
+            }
+            else {
+                run.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;
+            run.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,7 @@
 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";
+import { getEffectiveSandboxPolicy, networkDeniedMessage } from "../sandbox.js";
+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.
@@ -27,6 +26,11 @@ Usage:
         required: ["query"],
     }),
     execute: async ({ query, tokensNum }) => {
+        if (getEffectiveSandboxPolicy().network === "deny")
+            return `Code search error: ${networkDeniedMessage()}`;
+        if (!process.env.EXA_API_KEY?.trim()) {
+            return "Code search error: EXA_API_KEY is not set. Configure it in your environment to enable code search.";
+        }
         const tokens = Math.max(1000, Math.min(50000, tokensNum ?? 5000));
         try {
             const result = await callExaCode(query, tokens);
@@ -36,7 +40,7 @@ Usage:
             return truncateToolOutput(result, { direction: "head" }).content;
         }
         catch (err) {
-            return `Code search error: ${err.message}`;
+            return `Code search error: ${err instanceof Error ? err.message : String(err)}`;
         }
     },
 });
@@ -59,6 +63,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 +71,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,7 +1,9 @@
 import { tool, jsonSchema } from "ai";
-import { readFileSync, writeFileSync, existsSync } from "fs";
+import { readFile } from "fs/promises";
 import path from "path";
-import { confirm, isAutoApprove } from "../confirm.js";
+import { confirm, isEditAutoApprove } from "../confirm.js";
+import { pathAccessError } from "../sandbox.js";
+import { atomicWriteFile } from "./atomic-file.js";
 export const editTool = tool({
     description: "Edit a file by replacing a specific text block with new content. The oldText must match exactly (including whitespace and indentation). Use this for precise edits instead of rewriting entire files.",
     inputSchema: jsonSchema({
@@ -14,11 +16,21 @@ 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 denied = pathAccessError(filePath, "write");
+        if (denied)
+            return `Error: ${denied}`;
         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 instanceof Error ? err.message : String(err)}`;
         }
-        const content = readFileSync(resolved, "utf-8");
         const occurrences = content.split(oldText).length - 1;
         if (occurrences === 0) {
             // Try to help: show nearby content
@@ -36,14 +48,19 @@ export const editTool = tool({
             return `Error: oldText found ${occurrences} times in ${filePath}. Please provide more context to make the match unique.`;
         }
         // Confirm edit
-        if (!isAutoApprove()) {
-            const preview = oldText.length > 80 ? oldText.slice(0, 80) + "..." : oldText;
-            const approved = await confirm(`Edit ${filePath}: replace "${preview}"`);
+        if (!isEditAutoApprove()) {
+            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");
+        try {
+            await atomicWriteFile(resolved, updated);
+        }
+        catch (err) {
+            return `Error: cannot write ${filePath}: ${err instanceof Error ? err.message : String(err)}`;
+        }
         const oldLines = oldText.split("\n").length;
         const newLines = newText.split("\n").length;
         return `Edited ${filePath}: replaced ${oldLines} line(s) with ${newLines} line(s)`;