min-agent 0.2.1 → 0.4.0

package/dist/fetch-timeout.js

@@ -0,0 +1,152 @@
+import { log } from "./logger.js";
+/**
+ * fetch wrapper for model requests.
+ *
+ * Providers can stall in two ways that a plain fetch never surfaces:
+ *   1. the response never starts (no headers / first byte),
+ *   2. the SSE stream opens and then goes quiet forever.
+ * Both would hang the agent loop indefinitely, so each has its own timer. On
+ * timeout the request is aborted with a marked error the loop recognises as a
+ * transient provider failure (see isProviderStallError).
+ *
+ * The wrapper also carries optional request/response tracing (MIN_AGENT_TRACE),
+ * which is the only way to see what a misbehaving gateway actually returned.
+ */
+/** Marker embedded in stall errors so the agent loop can classify them. */
+export const PROVIDER_STALL_MARKER = "min-agent: provider stalled";
+export const DEFAULT_FIRST_BYTE_TIMEOUT_MS = 180_000;
+export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 90_000;
+function stallError(kind, ms) {
+    const err = new Error(`${PROVIDER_STALL_MARKER}: no ${kind} for ${ms}ms`);
+    err.name = "ProviderStallError";
+    return err;
+}
+/** Walk the error chain so a stall marker survives provider SDK wrapping. */
+export function describeError(err, depth = 4) {
+    const parts = [];
+    let current = err;
+    for (let i = 0; i < depth && current != null; i++) {
+        if (current instanceof Error) {
+            parts.push(current.message);
+            current = current.cause;
+            continue;
+        }
+        parts.push(String(current));
+        break;
+    }
+    return parts.join(" | ");
+}
+/** True when the failure is a provider stall we injected (safe to retry). */
+export function isProviderStallError(err) {
+    return describeError(err).includes(PROVIDER_STALL_MARKER);
+}
+function traceRequestLine(url, init) {
+    const body = typeof init?.body === "string" ? init.body : "";
+    let summary = `bytes=${body.length}`;
+    try {
+        const parsed = JSON.parse(body || "{}");
+        const tools = parsed.tools?.map((t) => t.function?.name ?? "?") ?? [];
+        summary += ` model=${parsed.model ?? "?"} messages=${parsed.messages?.length ?? 0} tools=${tools.length} stream=${parsed.stream ?? false}`;
+    }
+    catch {
+        /* not JSON — bytes only */
+    }
+    return `trace request ${url} ${summary}`;
+}
+/**
+ * Wrap a response body so the idle timer resets on every chunk and fires when
+ * the provider goes quiet mid-stream.
+ */
+function guardBody(response, idleTimeoutMs, abort) {
+    if (!response.body || idleTimeoutMs <= 0)
+        return response;
+    const source = response.body;
+    const reader = source.getReader();
+    let timer;
+    const clear = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = undefined;
+    };
+    const guarded = new ReadableStream({
+        async pull(controller) {
+            const arm = () => {
+                clear();
+                timer = setTimeout(() => abort(stallError("stream", idleTimeoutMs)), idleTimeoutMs);
+            };
+            arm();
+            try {
+                const { done, value } = await reader.read();
+                clear();
+                if (done) {
+                    controller.close();
+                    return;
+                }
+                controller.enqueue(value);
+            }
+            catch (err) {
+                clear();
+                controller.error(err);
+            }
+        },
+        cancel(reason) {
+            clear();
+            return reader.cancel(reason);
+        },
+    });
+    return new Response(guarded, {
+        status: response.status,
+        statusText: response.statusText,
+        headers: response.headers,
+    });
+}
+export function createTimeoutFetch(options = {}) {
+    const firstByteTimeoutMs = options.firstByteTimeoutMs ?? DEFAULT_FIRST_BYTE_TIMEOUT_MS;
+    const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_STREAM_IDLE_TIMEOUT_MS;
+    const doFetch = options.fetchImpl ?? fetch;
+    const now = options.now ?? Date.now;
+    const trace = options.trace ?? false;
+    return async (input, init) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+        const controller = new AbortController();
+        let stall;
+        const abortWith = (err) => {
+            stall = err;
+            log("warn", `${err.message} (${url})`);
+            controller.abort(err);
+        };
+        const external = init?.signal;
+        const forward = () => controller.abort(external?.reason);
+        if (external) {
+            if (external.aborted)
+                forward();
+            else
+                external.addEventListener("abort", forward, { once: true });
+        }
+        let firstByteTimer;
+        if (firstByteTimeoutMs > 0) {
+            firstByteTimer = setTimeout(() => abortWith(stallError("first byte", firstByteTimeoutMs)), firstByteTimeoutMs);
+        }
+        if (trace)
+            log("info", traceRequestLine(url, init));
+        const started = now();
+        try {
+            const response = await doFetch(input, { ...init, signal: controller.signal });
+            if (firstByteTimer)
+                clearTimeout(firstByteTimer);
+            if (trace)
+                log("info", `trace response ${url} status=${response.status} ttfb=${now() - started}ms`);
+            return guardBody(response, idleTimeoutMs, abortWith);
+        }
+        catch (err) {
+            if (firstByteTimer)
+                clearTimeout(firstByteTimer);
+            if (stall)
+                throw stall;
+            throw err;
+        }
+        finally {
+            external?.removeEventListener("abort", forward);
+        }
+    };
+}

package/dist/http-approvals.js

@@ -0,0 +1,60 @@
+export const APPROVAL_TIMEOUT_MS = 300_000;
+export function createApprovalGate(timeoutMs = APPROVAL_TIMEOUT_MS) {
+    const pending = new Map();
+    const clear = (id) => {
+        const item = pending.get(id);
+        if (!item)
+            return undefined;
+        clearTimeout(item.timer);
+        pending.delete(id);
+        return item;
+    };
+    return {
+        waitConfirm(id) {
+            return new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    pending.delete(id);
+                    resolve(false);
+                }, timeoutMs);
+                pending.set(id, { kind: "confirm", resolve, timer });
+            });
+        },
+        waitQuestion(id) {
+            return new Promise((resolve) => {
+                const timer = setTimeout(() => {
+                    pending.delete(id);
+                    resolve(null);
+                }, timeoutMs);
+                pending.set(id, { kind: "question", resolve, timer });
+            });
+        },
+        resolveConfirm(id, accepted) {
+            const item = pending.get(id);
+            if (!item || item.kind !== "confirm")
+                return false;
+            clear(id);
+            item.resolve(accepted);
+            return true;
+        },
+        resolveQuestion(id, answer) {
+            const item = pending.get(id);
+            if (!item || item.kind !== "question")
+                return false;
+            clear(id);
+            item.resolve(answer);
+            return true;
+        },
+        cancel(id) {
+            const item = clear(id);
+            if (!item)
+                return;
+            if (item.kind === "confirm")
+                item.resolve(false);
+            else
+                item.resolve(null);
+        },
+        has(id) {
+            return pending.has(id);
+        },
+    };
+}

package/dist/http.js

@@ -0,0 +1,119 @@
+import { lookup } from "dns/promises";
+import { isIP } from "net";
+function isPrivateIpv4(parts) {
+    if (parts.length !== 4 || parts.some((p) => Number.isNaN(p)))
+        return true;
+    const [a, b] = parts;
+    if (a === 0 || a === 10 || a === 127)
+        return true;
+    if (a === 169 && b === 254)
+        return true;
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    if (a === 192 && b === 168)
+        return true;
+    if (a === 100 && b >= 64 && b <= 127)
+        return true;
+    if (a === 198 && (b === 18 || b === 19))
+        return true;
+    return false;
+}
+/**
+ * Decode the tail of an IPv4-mapped IPv6 address (`::ffff:7f00:1` or
+ * `::ffff:127.0.0.1`) into IPv4 octets, or return null.
+ */
+function mappedIpv4Bytes(ip) {
+    const tail = ip.slice(7);
+    if (tail.includes(".")) {
+        return tail.split(".").map(Number);
+    }
+    const groups = tail.split(":");
+    if (groups.length !== 2)
+        return null;
+    const hi = parseInt(groups[0], 16);
+    const lo = parseInt(groups[1], 16);
+    if (Number.isNaN(hi) || Number.isNaN(lo))
+        return null;
+    return [hi >> 8, hi & 0xff, lo >> 8, lo & 0xff];
+}
+/** Check whether an IP address belongs to a private / reserved / loopback range. */
+export function isPrivateAddress(ip) {
+    if (ip.startsWith("::ffff:")) {
+        const bytes = mappedIpv4Bytes(ip);
+        if (bytes)
+            return isPrivateIpv4(bytes);
+        return true;
+    }
+    if (isIP(ip) === 6) {
+        const lower = ip.toLowerCase();
+        if (lower === "::1" || lower.startsWith("::"))
+            return true;
+        if (lower.startsWith("fc") || lower.startsWith("fd"))
+            return true;
+        if (lower.startsWith("fe8") || lower.startsWith("fe9") || lower.startsWith("fea") || lower.startsWith("feb"))
+            return true;
+        if (lower.startsWith("2001:db8"))
+            return true;
+        return false;
+    }
+    return isPrivateIpv4(ip.split(".").map(Number));
+}
+/** Returns an error message if the URL is unsafe to fetch (SSRF protection), or null if safe. */
+export async function assertSafeUrl(raw) {
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        return "Invalid URL";
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return "Only http/https URLs are allowed";
+    }
+    const host = parsed.hostname;
+    if (host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal")) {
+        return `Blocked: local hostname "${host}"`;
+    }
+    if (isIP(host)) {
+        return isPrivateAddress(host) ? `Blocked: private/internal IP "${host}"` : null;
+    }
+    try {
+        const addresses = await lookup(host, { all: true });
+        for (const addr of addresses) {
+            if (isPrivateAddress(addr.address)) {
+                return `Blocked: "${host}" resolves to private address "${addr.address}"`;
+            }
+        }
+    }
+    catch {
+        // DNS failure — let fetch surface the real error
+    }
+    return null;
+}
+/**
+ * Read a response body up to maxBytes. Bytes beyond the limit are dropped and
+ * the read is cancelled early so huge responses never fill memory.
+ */
+export async function readBodyLimited(response, maxBytes) {
+    if (!response.body) {
+        return { text: "", truncated: false };
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    let truncated = false;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > maxBytes) {
+            chunks.push(Buffer.from(value.subarray(0, value.byteLength - (total - maxBytes))));
+            truncated = true;
+            await reader.cancel();
+            break;
+        }
+        chunks.push(Buffer.from(value));
+    }
+    return { text: Buffer.concat(chunks).toString("utf-8"), truncated };
+}

package/dist/instructions.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "async_hooks";
 import { readFileSync, existsSync } from "fs";
 import path from "path";
 import os from "os";
@@ -16,6 +17,21 @@ import { getRulesFile, loadConfig } from "./config.js";
  *   When the agent reads a file, nearby AGENTS.md/RULES.md are auto-loaded.
  */
 const PROJECT_FILES = ["AGENTS.md", "RULES.md", "CLAUDE.md"];
+function isWithinDir(root, p) {
+    const rel = path.relative(root, p);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+function walkUpDirs(startDir, minDir) {
+    const dirs = [];
+    let current = path.resolve(startDir);
+    while (current !== path.dirname(minDir) && isWithinDir(minDir, current)) {
+        dirs.push(current);
+        if (current === minDir)
+            break;
+        current = path.dirname(current);
+    }
+    return dirs;
+}
 /** Tracks which instruction files have already been loaded to avoid duplicates */
 export class InstructionTracker {
     loaded = new Set();
@@ -25,6 +41,9 @@ export class InstructionTracker {
     markLoaded(filepath) {
         this.loaded.add(path.resolve(filepath));
     }
+    reset() {
+        this.loaded.clear();
+    }
     /**
      * Context-aware: when a file is read, walk up from its directory
      * looking for AGENTS.md/RULES.md that haven't been loaded yet.
@@ -33,10 +52,9 @@ export class InstructionTracker {
     resolveForFile(filepath) {
         const results = [];
         const root = process.cwd();
-        let current = path.dirname(path.resolve(filepath));
-        while (current.startsWith(root) && current !== path.dirname(root)) {
+        for (const dir of walkUpDirs(path.dirname(path.resolve(filepath)), root)) {
             for (const file of PROJECT_FILES) {
-                const candidate = path.join(current, file);
+                const candidate = path.join(dir, file);
                 if (existsSync(candidate) && !this.isLoaded(candidate)) {
                     try {
                         const content = readFileSync(candidate, "utf-8").trim();
@@ -50,32 +68,41 @@ export class InstructionTracker {
             }
             if (results.length > 0)
                 break;
-            current = path.dirname(current);
         }
         return results;
     }
 }
-function findProjectInstructions() {
+const instructionStore = new AsyncLocalStorage();
+const fallbackInstructionTracker = new InstructionTracker();
+/** Per-run tracker so concurrent HTTP chats do not share loaded-file state. */
+export async function runWithInstructionTracker(fn) {
+    return instructionStore.run(new InstructionTracker(), fn);
+}
+export function getActiveInstructionTracker() {
+    return instructionStore.getStore() ?? fallbackInstructionTracker;
+}
+/** After compaction, nearby AGENTS.md must be allowed to re-inject. */
+export function resetActiveInstructionTracker() {
+    const current = instructionStore.getStore();
+    if (current)
+        current.reset();
+    else
+        fallbackInstructionTracker.reset();
+}
+export function findProjectInstructions() {
     const results = [];
-    let current = process.cwd();
-    const root = path.parse(current).root;
-    while (current !== root) {
-        // Check .min-agent/AGENTS.md in project
-        const dotDir = path.join(current, ".min-agent", "AGENTS.md");
+    const root = path.parse(process.cwd()).root;
+    for (const dir of walkUpDirs(process.cwd(), root)) {
+        const dotDir = path.join(dir, ".min-agent", "AGENTS.md");
         if (existsSync(dotDir)) {
             results.push(dotDir);
             break;
         }
-        for (const file of PROJECT_FILES) {
-            const filepath = path.join(current, file);
-            if (existsSync(filepath)) {
-                results.push(filepath);
-                break;
-            }
-        }
-        if (results.length > 0)
+        const found = PROJECT_FILES.find((file) => existsSync(path.join(dir, file)));
+        if (found) {
+            results.push(path.join(dir, found));
             break;
-        current = path.dirname(current);
+        }
     }
     return results;
 }
@@ -103,23 +130,35 @@ function resolveConfigInstructions() {
     }
     return results;
 }
-async function fetchRemoteInstructions() {
-    const config = loadConfig();
-    const instructions = config.instructions ?? [];
-    const results = [];
-    const urls = instructions.filter((i) => i.startsWith("http://") || i.startsWith("https://"));
-    for (const url of urls) {
-        try {
-            const response = await fetch(url, { signal: AbortSignal.timeout(5000) });
-            if (response.ok) {
-                const text = await response.text();
-                if (text.trim())
-                    results.push(`Instructions from: ${url}\n${text}`);
+const REMOTE_CACHE_TTL_MS = 60_000;
+const remoteCache = new Map();
+async function fetchRemoteInstruction(url) {
+    const cached = remoteCache.get(url);
+    if (cached && Date.now() - cached.fetchedAt < REMOTE_CACHE_TTL_MS)
+        return cached.text;
+    try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(5000) });
+        if (response.ok) {
+            const text = await response.text();
+            if (text.trim()) {
+                remoteCache.set(url, { fetchedAt: Date.now(), text });
+                return text;
             }
         }
-        catch { }
     }
-    return results;
+    catch { }
+    return null;
+}
+export async function fetchRemoteInstructions(urls) {
+    const config = loadConfig();
+    const instructions = urls ?? config.instructions ?? [];
+    const results = await Promise.all(instructions
+        .filter((i) => i.startsWith("http://") || i.startsWith("https://"))
+        .map(async (url) => {
+        const text = await fetchRemoteInstruction(url);
+        return text ? `Instructions from: ${url}\n${text}` : "";
+    }));
+    return results.filter(Boolean);
 }
 export async function loadInstructions() {
     const parts = [];

package/dist/logger.js

@@ -0,0 +1,95 @@
+import { mkdirSync, readdirSync, unlinkSync, writeFileSync } from "fs";
+import path from "path";
+import { getConfigDir } from "./config.js";
+const KEEP_DAYS = 7;
+function logsDir() {
+    return path.join(getConfigDir(), "logs");
+}
+function logFilePath(date) {
+    const y = date.getFullYear();
+    const m = String(date.getMonth() + 1).padStart(2, "0");
+    const d = String(date.getDate()).padStart(2, "0");
+    return path.join(logsDir(), `min-agent.${y}-${m}-${d}.log`);
+}
+export function initLogger() {
+    try {
+        mkdirSync(logsDir(), { recursive: true });
+        const cutoff = Date.now() - KEEP_DAYS * 24 * 60 * 60 * 1000;
+        for (const f of readdirSync(logsDir())) {
+            const m = f.match(/^min-agent\.(\d{4})-(\d{2})-(\d{2})\.log$/);
+            if (!m)
+                continue;
+            const ts = new Date(`${m[1]}-${m[2]}-${m[3]}T00:00:00`).getTime();
+            if (ts < cutoff) {
+                try {
+                    unlinkSync(path.join(logsDir(), f));
+                }
+                catch { }
+            }
+        }
+    }
+    catch { }
+}
+function writeLog(level, msg) {
+    try {
+        const now = new Date();
+        const time = `${String(now.getHours()).padStart(2, "0")}:${String(now.getMinutes()).padStart(2, "0")}:${String(now.getSeconds()).padStart(2, "0")}`;
+        writeFileSync(logFilePath(now), `[${time}] [${level}]${runTag()} ${scrubSecrets(msg)}\n`, { flag: "a" });
+    }
+    catch { }
+}
+/**
+ * Run context stamped onto every log line, so interleaved turns (and the passes
+ * inside one turn) can be told apart when reading the file afterwards.
+ */
+let runContext = null;
+function runTag() {
+    if (!runContext)
+        return "";
+    return ` [run=${runContext.runId} pass=${runContext.pass}]`;
+}
+/** Start a new run scope and return its id. */
+export function startRunLog() {
+    const runId = Math.random().toString(36).slice(2, 8);
+    runContext = { runId, pass: 0 };
+    return runId;
+}
+/** Mark the beginning of a model pass inside the current run. */
+export function nextRunPass() {
+    if (!runContext)
+        startRunLog();
+    runContext.pass++;
+    return runContext.pass;
+}
+export function endRunLog() {
+    runContext = null;
+}
+export function currentRunId() {
+    return runContext?.runId ?? null;
+}
+const SECRET_PATTERNS = [
+    /\b(Bearer\s+)[A-Za-z0-9._~+/-]{8,}/g,
+    /\b(api[_-]?key|apikey|token|secret|password|passwd)\s*[:=]\s*["']?[A-Za-z0-9._~+/-]{6,}["']?/gi,
+    /\b(sk-[A-Za-z0-9_-]{6,})/g,
+    /\b(gh[pousr]_[A-Za-z0-9]{20,})/g,
+];
+/** Mask obvious secrets before anything hits the log file. */
+function scrubSecrets(msg) {
+    let out = msg;
+    for (const re of SECRET_PATTERNS)
+        out = out.replace(re, "$1***");
+    return out;
+}
+export function log(level, msg) {
+    writeLog(level, msg);
+}
+function summarize(v, max = 200) {
+    const s = typeof v === "string" ? v : (JSON.stringify(v) ?? String(v));
+    return s.length > max ? s.slice(0, max) + "…" : s;
+}
+export function logToolCall(name, input) {
+    writeLog("info", `tool_call ${name} ${summarize(input)}`);
+}
+export function logToolResult(name, output) {
+    writeLog("info", `tool_result ${name} ${summarize(output)}`);
+}