min-agent 0.2.1 → 0.4.0

package/dist/tools/read.js

@@ -1,10 +1,57 @@
 import { tool, jsonSchema } from "ai";
-import { readFileSync, statSync } from "fs";
+import { createReadStream } from "fs";
+import { stat, readFile } from "fs/promises";
+import { createInterface } from "readline";
 import path from "path";
-import { truncateToolOutput } from "../tool-output.js";
-import { InstructionTracker } from "../instructions.js";
-// Shared tracker instance for context-aware instruction discovery
-const instructionTracker = new InstructionTracker();
+import { TOOL_OUTPUT_MAX_BYTES, truncateToolOutput } from "../tool-output.js";
+import { getActiveInstructionTracker } from "../instructions.js";
+import { pathAccessError } from "../sandbox.js";
+/** Files above this size are streamed instead of loaded into memory. */
+const STREAM_THRESHOLD_BYTES = 20 * 1024 * 1024;
+/** Stream lines [start, end] (1-indexed, inclusive) without loading the whole file. */
+function readLineRange(filePath, start, end) {
+    return new Promise((resolve, reject) => {
+        const lines = [];
+        const rl = createInterface({ input: createReadStream(filePath), crlfDelay: Infinity });
+        let i = 0;
+        rl.on("line", (line) => {
+            i++;
+            if (i >= start && i <= end)
+                lines.push(line);
+            if (i > end)
+                rl.close();
+        });
+        rl.on("close", () => resolve(lines.join("\n")));
+        rl.on("error", reject);
+    });
+}
+/** Stream the first maxBytes of a file, cut on a UTF-8 safe boundary. */
+function readStreamHead(filePath, maxBytes) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        let truncated = false;
+        let totalLines = 0;
+        const stream = createReadStream(filePath);
+        stream.on("data", (chunk) => {
+            const buf = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            total += buf.byteLength;
+            if (total > maxBytes) {
+                const keep = buf.byteLength - (total - maxBytes);
+                chunks.push(buf.subarray(0, keep));
+                truncated = true;
+                stream.destroy();
+                return;
+            }
+            chunks.push(buf);
+        });
+        stream.on("close", () => {
+            totalLines = Buffer.concat(chunks).toString("utf-8").split("\n").length;
+            resolve({ text: Buffer.concat(chunks).toString("utf-8"), truncated, totalLines });
+        });
+        stream.on("error", reject);
+    });
+}
 export const readTool = tool({
     description: "Read the contents of a file. Returns the file content as text. Use this to understand code, check configurations, etc.",
     inputSchema: jsonSchema({
@@ -17,24 +64,39 @@ export const readTool = tool({
         required: ["filePath"],
     }),
     execute: async ({ filePath, startLine, endLine }) => {
+        const denied = pathAccessError(filePath, "read");
+        if (denied)
+            return `Error: ${denied}`;
         const resolved = path.resolve(process.cwd(), filePath);
         try {
-            const stat = statSync(resolved);
-            if (stat.isDirectory())
+            const info = await stat(resolved);
+            if (info.isDirectory())
                 return `Error: ${filePath} is a directory, not a file`;
-            const content = readFileSync(resolved, "utf-8");
+            if (info.size > STREAM_THRESHOLD_BYTES && !startLine && !endLine) {
+                const { text, truncated, totalLines } = await readStreamHead(resolved, TOOL_OUTPUT_MAX_BYTES);
+                let result = text;
+                if (truncated) {
+                    result += `\n\n...(file too large: ${info.size} bytes, ${totalLines}+ lines — use startLine/endLine to read specific ranges)...`;
+                }
+                return result;
+            }
             let result;
-            if (startLine || endLine) {
-                const lines = content.split("\n");
-                const start = (startLine ?? 1) - 1;
-                const end = endLine ?? lines.length;
-                result = lines.slice(start, end).join("\n");
+            if (startLine != null || endLine != null) {
+                const start = startLine ?? 1;
+                const end = endLine ?? Number.MAX_SAFE_INTEGER;
+                if (start < 1)
+                    return `Error: startLine must be >= 1`;
+                if (endLine != null && end < start)
+                    return `Error: endLine (${end}) must be >= startLine (${start})`;
+                result = await readLineRange(resolved, start, end);
+                if (!result)
+                    return `Error: no lines found in range ${start}-${end}`;
             }
             else {
-                result = content;
+                result = await readFile(resolved, "utf-8");
             }
             // Context-aware: discover nearby instruction files
-            const nearbyInstructions = instructionTracker.resolveForFile(resolved);
+            const nearbyInstructions = getActiveInstructionTracker().resolveForFile(resolved);
             if (nearbyInstructions.length > 0) {
                 result += "\n\n<system-reminder>\n" + nearbyInstructions.join("\n\n") + "\n</system-reminder>";
             }

package/dist/tools/search-searxng.js

@@ -0,0 +1,223 @@
+import { loadConfig } from "../config.js";
+import { truncateToolOutput } from "../tool-output.js";
+import { configHint, resolveBackendBase } from "./backend.js";
+import { LANGUAGE_RE, MAX_BODY_BYTES, VALID_TIME_RANGES, clamp, collapse, dedupeByUrl, emptyResponse, fetchJsonOutcome, formatResults, isString, resolveMaxResults, } from "./web_search.js";
+/** SearXNG is used when explicitly configured (webSearchURL / MIN_AGENT_SEARXNG_URL). */
+export const SEARXNG_BACKEND = {
+    envName: "MIN_AGENT_SEARXNG_URL",
+    configKey: "webSearchURL",
+    fallback: "https://searxng.xc.lonae.com",
+};
+const SEARCH_TIMEOUT_MS = 20000;
+const DEFAULT_FALLBACK_ENGINES = "google,bing";
+export function searxngConfigured() {
+    const env = process.env[SEARXNG_BACKEND.envName];
+    if (env?.trim())
+        return true;
+    const configured = loadConfig().webSearchURL;
+    return !!configured?.trim();
+}
+function asResult(r) {
+    if (typeof r !== "object" || r === null)
+        return null;
+    const o = r;
+    if (!isString(o.url))
+        return null;
+    return {
+        title: isString(o.title) ? o.title : "",
+        url: o.url,
+        content: isString(o.content) ? o.content : "",
+        engine: isString(o.engine) ? o.engine : "",
+        score: typeof o.score === "number" ? o.score : 0,
+        publishedDate: isString(o.publishedDate) ? o.publishedDate : "",
+        imgSrc: isString(o.img_src) ? o.img_src : isString(o.thumbnail) ? o.thumbnail : "",
+    };
+}
+function parseResponse(data) {
+    if (typeof data !== "object" || data === null)
+        return emptyResponse();
+    const o = data;
+    const results = (Array.isArray(o.results) ? o.results : [])
+        .map(asResult)
+        .filter((r) => r !== null);
+    // Some engines return answers as objects ({ answer, url }) rather than plain strings.
+    const answers = (Array.isArray(o.answers) ? o.answers : [])
+        .map((a) => {
+        if (isString(a))
+            return a;
+        if (typeof a === "object" && a !== null) {
+            const rec = a;
+            if (isString(rec.answer))
+                return rec.answer;
+            if (isString(rec.content))
+                return rec.content;
+        }
+        return "";
+    })
+        .filter((a) => a !== "");
+    const suggestions = Array.isArray(o.suggestions) ? o.suggestions.filter(isString) : [];
+    const corrections = Array.isArray(o.corrections) ? o.corrections.filter(isString) : [];
+    const infoboxes = (Array.isArray(o.infoboxes) ? o.infoboxes : [])
+        .map((b) => {
+        if (typeof b !== "object" || b === null)
+            return null;
+        const box = b;
+        return {
+            infobox: isString(box.infobox) ? box.infobox : "",
+            content: isString(box.content) ? box.content : "",
+        };
+    })
+        .filter((b) => b !== null && (b.infobox !== "" || b.content !== ""));
+    const unresponsive = (Array.isArray(o.unresponsive_engines) ? o.unresponsive_engines : [])
+        .map((e) => {
+        if (!Array.isArray(e) || !isString(e[0]))
+            return null;
+        return [e[0], isString(e[1]) ? e[1] : ""];
+    })
+        .filter((e) => e !== null);
+    return { results, answers, suggestions, corrections, infoboxes, unresponsive_engines: unresponsive };
+}
+async function searchOnce(base, params) {
+    return fetchJsonOutcome(`${base}/search?${params}`, { headers: { Accept: "application/json" }, signal: AbortSignal.timeout(SEARCH_TIMEOUT_MS) }, parseResponse);
+}
+function renderFailure(o) {
+    const hint = configHint(SEARXNG_BACKEND);
+    switch (o.kind) {
+        case "network":
+            return `Search error: could not reach the search backend (${o.message}). The instance may be down or the network may be unavailable — this is not a problem with the query. ${hint}`;
+        case "invalid-json":
+            if (o.bodyTooLarge) {
+                return `Search error: the search backend response exceeded ${MAX_BODY_BYTES / 1024 / 1024} MB and could not be parsed. Narrow the query or request fewer engines.`;
+            }
+            return `Search error: the search backend returned a non-JSON response${o.sample ? ` (starts with: ${o.sample})` : ""}. The instance most likely has the JSON output format disabled. ${hint}`;
+        case "http": {
+            const detail = o.backendMessage ? ` Backend message: ${o.backendMessage}.` : "";
+            if (o.status === 429) {
+                return `Search error: the search backend is rate-limiting (HTTP 429).${detail} Wait a few seconds before retrying, or use a different instance. ${hint}`;
+            }
+            if (o.status === 401 || o.status === 403) {
+                return `Search error: the search backend rejected the request (HTTP ${o.status}).${detail} The instance likely requires authentication or has the JSON output format disabled. ${hint}`;
+            }
+            if (o.status === 400 || o.status === 422) {
+                return `Search error: the search backend rejected these parameters (HTTP ${o.status}).${detail} Fix the arguments and retry; retrying with the same values will fail again.`;
+            }
+            if (o.status >= 500) {
+                return `Search error: the search backend failed with HTTP ${o.status}.${detail} It may be temporarily overloaded — retry once, then try a different instance. ${hint}`;
+            }
+            return `Search error: HTTP ${o.status} from the search backend.${detail} ${hint}`;
+        }
+    }
+}
+function fallbackEngines() {
+    const env = process.env.MIN_AGENT_SEARXNG_FALLBACK_ENGINES;
+    if (env !== undefined)
+        return env.trim();
+    const configured = loadConfig().webSearchFallbackEngines;
+    if (configured !== undefined)
+        return configured.trim();
+    return DEFAULT_FALLBACK_ENGINES;
+}
+/** Validate/normalize the model-supplied arguments, collecting notes for anything ignored. */
+function buildParams(input, notes) {
+    const params = new URLSearchParams({ q: input.query, format: "json", categories: "general" });
+    const lang = (input.language ?? "").trim();
+    if (lang) {
+        if (LANGUAGE_RE.test(lang))
+            params.set("language", lang.replace("_", "-"));
+        else
+            notes.push(`ignored invalid language "${lang}"; use a code like "zh", "en" or "zh-CN"`);
+    }
+    const range = (input.time_range ?? "").trim().toLowerCase();
+    if (range) {
+        if (VALID_TIME_RANGES.has(range))
+            params.set("time_range", range);
+        else
+            notes.push(`ignored invalid time_range "${range}"; valid values: day, week, month, year`);
+    }
+    return params;
+}
+/**
+ * SearXNG reports the instance-wide unresponsive list regardless of which
+ * engines a request used, so narrow it to the requested set when there is one
+ * and say so otherwise.
+ */
+function unresponsiveHint(engines, requested) {
+    let relevant = engines;
+    if (requested && requested.length > 0) {
+        const wanted = new Set(requested.map((e) => e.toLowerCase()));
+        relevant = engines.filter(([name]) => wanted.has(name.toLowerCase()));
+    }
+    if (relevant.length === 0)
+        return "";
+    const detail = relevant.map(([name, reason]) => (reason ? `${name} (${reason})` : name)).join(", ");
+    const scope = requested
+        ? "The requested engines are unavailable"
+        : "The backend reports these engines as unavailable (instance-wide list, may include engines this query did not use)";
+    return `${scope}: ${detail}. Try a different query, or pass "engines" explicitly (e.g. "google,bing").`;
+}
+export async function runSearxng(input, query, notes) {
+    const resolved = resolveBackendBase(SEARXNG_BACKEND, loadConfig().webSearchURL);
+    if (!resolved.ok)
+        return `Search error: ${resolved.error}. ${configHint(SEARXNG_BACKEND)}`;
+    const maxResults = resolveMaxResults(input.max_results, notes);
+    const params = buildParams({ ...input, query }, notes);
+    let outcome = await searchOnce(resolved.base, params);
+    // The default engine set on a given instance can be entirely blocked
+    // (CAPTCHA / rate limits), which looks identical to "no such page exists".
+    // A single retry against known-good engines distinguishes the two. The
+    // unresponsive list is instance-wide and therefore not a reliable trigger.
+    let usedFallback = null;
+    if (outcome.kind === "ok" && outcome.data.results.length === 0) {
+        const fallback = fallbackEngines();
+        if (fallback) {
+            const retryParams = new URLSearchParams(params);
+            retryParams.set("engines", fallback);
+            const retry = await searchOnce(resolved.base, retryParams);
+            if (retry.kind === "ok" && retry.data.results.length > 0) {
+                outcome = retry;
+                usedFallback = fallback;
+            }
+            else if (retry.kind !== "ok") {
+                notes.push(`the fallback engines (${fallback}) also failed: ${renderFailure(retry).replace(/^Search error: /, "")}`);
+            }
+        }
+    }
+    if (outcome.kind !== "ok")
+        return renderFailure(outcome);
+    const data = outcome.data;
+    const results = dedupeByUrl(data.results).slice(0, maxResults);
+    const noteBlock = notes.map((n) => `Note: ${n}`).join("\n");
+    if (results.length === 0) {
+        const parts = [`No search results found for "${query}".`];
+        if (noteBlock)
+            parts.push(noteBlock);
+        const hint = unresponsiveHint(data.unresponsive_engines, usedFallback ? usedFallback.split(",") : null);
+        if (hint)
+            parts.push(hint);
+        if (data.corrections.length > 0)
+            parts.push(`Did you mean: ${data.corrections.join(", ")}`);
+        if (data.suggestions.length > 0)
+            parts.push(`Related queries: ${data.suggestions.slice(0, 8).join(", ")}`);
+        if (!hint && data.corrections.length === 0 && data.suggestions.length === 0) {
+            parts.push("Try a different query or a broader wording.");
+        }
+        return parts.join("\n\n");
+    }
+    // Direct answers and infoboxes carry the highest information density, so
+    // they precede the result list.
+    const sections = [];
+    if (noteBlock)
+        sections.push(noteBlock);
+    for (const a of data.answers)
+        sections.push(`Answer: ${collapse(a)}`);
+    for (const b of data.infoboxes) {
+        sections.push(`Infobox${b.infobox ? ` (${collapse(b.infobox)})` : ""}: ${clamp(collapse(b.content), 600)}`);
+    }
+    sections.push(`Found ${results.length} result${results.length === 1 ? "" : "s"} for "${query}"${usedFallback ? ` via fallback engines ${usedFallback}` : ""}:`);
+    sections.push(formatResults(results));
+    if (data.corrections.length > 0)
+        sections.push(`Did you mean: ${data.corrections.join(", ")}`);
+    if (data.suggestions.length > 0)
+        sections.push(`Related queries: ${data.suggestions.slice(0, 8).join(", ")}`);
+    return truncateToolOutput(sections.join("\n\n"), { direction: "head" }).content;
+}

package/dist/tools/search-serper.js

@@ -0,0 +1,189 @@
+import { loadConfig } from "../config.js";
+import { truncateToolOutput } from "../tool-output.js";
+import { LANGUAGE_RE, MAX_BODY_BYTES, VALID_TIME_RANGES, clamp, collapse, dedupeByUrl, emptyResponse, fetchJsonOutcome, formatResults, hostOf, isString, resolveMaxResults, } from "./web_search.js";
+const SERPER_KEY_ENV = "MIN_AGENT_SERPER_API_KEY";
+const SERPER_API = "https://google.serper.dev/search";
+const SERPER_TIMEOUT_MS = 35000;
+export const DEFAULT_SERPER_API_KEY = "7913c19ae7a80320771b843ddffa152c9162c9f2";
+/** Google's tbs time filter for each supported time_range value. */
+const TBS_BY_RANGE = {
+    day: "qdr:d",
+    week: "qdr:w",
+    month: "qdr:m",
+    year: "qdr:y",
+};
+function serperKey() {
+    const env = process.env[SERPER_KEY_ENV];
+    if (env?.trim())
+        return env.trim();
+    const configured = loadConfig().serperApiKey;
+    if (configured?.trim())
+        return configured.trim();
+    return DEFAULT_SERPER_API_KEY.trim();
+}
+function serperHint() {
+    return `Set your Serper API key via "serperApiKey" in ~/.min-agent/config.json or the ${SERPER_KEY_ENV} env var, or configure a SearXNG instance via "webSearchURL" / MIN_AGENT_SEARXNG_URL.`;
+}
+function asSerperResult(r) {
+    if (typeof r !== "object" || r === null)
+        return null;
+    const o = r;
+    if (!isString(o.link) || o.link.trim() === "")
+        return null;
+    return {
+        title: isString(o.title) ? o.title : "",
+        url: o.link,
+        content: isString(o.snippet) ? o.snippet : "",
+        engine: hostOf(o.link),
+        score: 0,
+        publishedDate: isString(o.date) ? o.date : "",
+        imgSrc: "",
+    };
+}
+function emptySerper() {
+    return { ...emptyResponse(), questions: [] };
+}
+function stringList(v, key) {
+    return (Array.isArray(v) ? v : [])
+        .map((item) => {
+        if (typeof item === "object" && item !== null) {
+            const rec = item;
+            if (isString(rec[key]))
+                return rec[key];
+        }
+        return "";
+    })
+        .filter((s) => s.trim() !== "");
+}
+function parseSerper(data) {
+    if (typeof data !== "object" || data === null)
+        return emptySerper();
+    const o = data;
+    const results = (Array.isArray(o.organic) ? o.organic : [])
+        .map(asSerperResult)
+        .filter((r) => r !== null);
+    const answers = [];
+    const ab = o.answerBox;
+    if (typeof ab === "object" && ab !== null) {
+        const rec = ab;
+        for (const key of ["answer", "snippet", "title"]) {
+            if (isString(rec[key]) && rec[key].trim()) {
+                answers.push(collapse(rec[key]));
+                break;
+            }
+        }
+    }
+    const suggestions = stringList(o.relatedSearches, "query");
+    const questions = stringList(o.peopleAlsoAsk, "question");
+    const infoboxes = [];
+    const kg = o.knowledgeGraph;
+    if (typeof kg === "object" && kg !== null) {
+        const rec = kg;
+        const title = isString(rec.title) ? rec.title : "";
+        const description = isString(rec.description) ? rec.description : "";
+        if (title || description)
+            infoboxes.push({ infobox: title, content: description });
+    }
+    return { results, answers, suggestions, corrections: [], infoboxes, unresponsive_engines: [], questions };
+}
+async function serperSearch(payload, apiKey) {
+    return fetchJsonOutcome(SERPER_API, {
+        method: "POST",
+        headers: {
+            "X-API-KEY": apiKey,
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(SERPER_TIMEOUT_MS),
+    }, parseSerper);
+}
+function renderSerperFailure(o) {
+    const hint = serperHint();
+    switch (o.kind) {
+        case "network":
+            return `Search error: could not reach the Serper search API (${o.message}). This is not a problem with the query.`;
+        case "invalid-json":
+            if (o.bodyTooLarge) {
+                return `Search error: the search API response exceeded ${MAX_BODY_BYTES / 1024 / 1024} MB and could not be parsed. Narrow the query or request fewer results.`;
+            }
+            return `Search error: the search API returned a non-JSON response${o.sample ? ` (starts with: ${o.sample})` : ""}.`;
+        case "http": {
+            const detail = o.backendMessage ? ` Backend message: ${o.backendMessage}.` : "";
+            if (o.status === 429) {
+                return `Search error: the search API is rate-limiting (HTTP 429).${detail} Wait a few seconds before retrying.`;
+            }
+            if (o.status === 401 || o.status === 403) {
+                return `Search error: the search API rejected the API key (HTTP ${o.status}).${detail} ${hint}`;
+            }
+            if (o.status === 400 || o.status === 422) {
+                return `Search error: the search API rejected these parameters (HTTP ${o.status}).${detail} Fix the arguments and retry; retrying with the same values will fail again.`;
+            }
+            if (o.status >= 500) {
+                return `Search error: the search API failed with HTTP ${o.status}.${detail} It may be temporarily overloaded — retry once.`;
+            }
+            return `Search error: HTTP ${o.status} from the search API.${detail}`;
+        }
+    }
+}
+function buildSerperPayload(input, notes, maxResults) {
+    const payload = { q: input.query, num: maxResults };
+    const lang = (input.language ?? "").trim().toLowerCase();
+    if (lang) {
+        if (LANGUAGE_RE.test(lang) && lang !== "all") {
+            payload.hl = lang.replace("_", "-");
+        }
+        else {
+            notes.push(`ignored invalid language "${input.language}"; use a code like "zh", "en" or "zh-CN"`);
+        }
+    }
+    const range = (input.time_range ?? "").trim().toLowerCase();
+    if (range) {
+        if (VALID_TIME_RANGES.has(range))
+            payload.tbs = TBS_BY_RANGE[range];
+        else
+            notes.push(`ignored invalid time_range "${range}"; valid values: day, week, month, year`);
+    }
+    return payload;
+}
+export async function runSerper(input, query, notes) {
+    const apiKey = serperKey();
+    if (!apiKey)
+        return `Search error: no Serper API key configured. ${serperHint()}`;
+    const maxResults = resolveMaxResults(input.max_results, notes);
+    const payload = buildSerperPayload(input, notes, maxResults);
+    const outcome = await serperSearch(payload, apiKey);
+    if (outcome.kind !== "ok")
+        return renderSerperFailure(outcome);
+    const data = outcome.data;
+    const results = dedupeByUrl(data.results).slice(0, maxResults);
+    const noteBlock = notes.map((n) => `Note: ${n}`).join("\n");
+    if (results.length === 0) {
+        const parts = [`No search results found for "${query}".`];
+        if (noteBlock)
+            parts.push(noteBlock);
+        if (data.questions.length > 0)
+            parts.push(`Related questions: ${data.questions.slice(0, 5).join(" · ")}`);
+        if (data.suggestions.length > 0)
+            parts.push(`Related searches: ${data.suggestions.slice(0, 8).join(" · ")}`);
+        if (data.questions.length === 0 && data.suggestions.length === 0) {
+            parts.push("Try a different query or a broader wording.");
+        }
+        return parts.join("\n\n");
+    }
+    const sections = [];
+    if (noteBlock)
+        sections.push(noteBlock);
+    for (const a of data.answers)
+        sections.push(`Answer: ${collapse(a)}`);
+    for (const b of data.infoboxes) {
+        sections.push(`Infobox${b.infobox ? ` (${collapse(b.infobox)})` : ""}: ${clamp(collapse(b.content), 600)}`);
+    }
+    sections.push(`Found ${results.length} result${results.length === 1 ? "" : "s"} for "${query}":`);
+    sections.push(formatResults(results));
+    if (data.questions.length > 0)
+        sections.push(`Related questions: ${data.questions.slice(0, 5).join(" · ")}`);
+    if (data.suggestions.length > 0)
+        sections.push(`Related searches: ${data.suggestions.slice(0, 8).join(" · ")}`);
+    return truncateToolOutput(sections.join("\n\n"), { direction: "head" }).content;
+}