min-agent 0.3.0 → 0.4.0

package/dist/doom-loop.js

@@ -1,43 +1,278 @@
 /**
- * Doom loop detection.
+ * Loop / stall detection for the agent run.
  *
- * Detects when the agent calls the same tool with the same arguments
- * repeatedly (indicating it's stuck in a loop). After THRESHOLD consecutive
- * identical calls, the loop is broken and the agent is informed.
+ * 1. Exact identity: the same tool with the same (normalized) arguments,
+ *    THRESHOLD times in a row → halt. Non-consecutive repeats of the same call
+ *    are counted too (a parallel batch used to flush the old sliding window),
+ *    with a higher threshold.
+ * 2. Web research productivity: a research call is judged by what came back.
+ *    Rounds that bring new URLs / domains are free — gathering data about many
+ *    entities legitimately needs many searches. Rounds that bring nothing new
+ *    build an "unproductive" streak that first steers the model to write, then
+ *    removes the research tools for the rest of the turn. A hard per-turn cap
+ *    still applies.
  *
- * Based on opencode's processor.ts doom loop detection.
+ * The detector is owned by the outer run loop so auto-continue cannot reset it.
  */
-const THRESHOLD = 3;
+/** Same tool + same args, back to back. */
+export const EXACT_LOOP_THRESHOLD = 3;
+/** Same tool + same args anywhere in the turn (survives parallel batches). */
+export const REPEAT_TOTAL_THRESHOLD = 5;
+/** Research rounds without new sources before steering the model to deliver. */
+export const RESEARCH_STEER_AFTER = 3;
+/** Research rounds without new sources before the research tools are dropped. */
+export const RESEARCH_STOP_AFTER = 5;
+/** Hard ceiling on research calls in a single turn. */
+export const RESEARCH_TOTAL_CAP = 24;
+export const WEB_RESEARCH_TOOLS = new Set(["search_web", "web_fetch"]);
+const ARTIFACT_TOOLS = new Set(["write", "edit", "apply_patch"]);
+export const STEER_PROMPT = "Your last few searches and page fetches returned nothing new. Stop calling search_web and web_fetch. Using only what you already have, produce the user's requested deliverable now (files, code, or a complete answer). If some fields are uncertain, mark them and proceed — do not search again.";
+export const DELIVER_PROMPT = "The research tools have been removed for the rest of this turn. Do not try to search again. Using the information already in this conversation, produce the user's requested deliverable now (write files with the write/edit tools). If a fact is missing, note the gap and still write the output.";
+export const RESEARCH_STUB_RESULT = "Web search and page fetch are disabled for the rest of this turn. Produce the user's requested deliverable from information already in this conversation. If a fact is missing, note the gap and still write the output.";
+export const LOOP_HALT_MESSAGE = "同一操作连续重复了多次，已停止以免空转。发送消息可继续。";
+function positiveInt(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 1)
+        return fallback;
+    return Math.floor(value);
+}
 /** Deterministic serialization so equivalent objects compare equal regardless of key order. */
 function serializeInput(input) {
-    if (input === null || typeof input !== "object")
-        return JSON.stringify(input);
-    if (Array.isArray(input))
-        return JSON.stringify(input.map(serializeInput));
-    const sorted = {};
-    for (const key of Object.keys(input).sort()) {
-        sorted[key] = serializeInput(input[key]);
+    try {
+        if (input === null || typeof input !== "object")
+            return JSON.stringify(input);
+        if (Array.isArray(input))
+            return JSON.stringify(input.map(serializeInput));
+        const sorted = {};
+        for (const key of Object.keys(input).sort()) {
+            sorted[key] = serializeInput(input[key]);
+        }
+        return JSON.stringify(sorted);
+    }
+    catch {
+        return String(input);
+    }
+}
+function asRecord(input) {
+    if (input && typeof input === "object" && !Array.isArray(input))
+        return input;
+    return null;
+}
+function normalizeQuery(raw) {
+    if (typeof raw !== "string")
+        return "";
+    return raw.toLowerCase().replace(/\s+/g, " ").trim();
+}
+function hostOf(raw) {
+    try {
+        return new URL(raw.trim()).hostname.toLowerCase().replace(/^www\./, "");
+    }
+    catch {
+        return "";
+    }
+}
+function normalizeUrl(raw) {
+    if (typeof raw !== "string")
+        return "";
+    try {
+        const u = new URL(raw.trim());
+        const host = u.hostname.toLowerCase().replace(/^www\./, "");
+        const path = u.pathname.replace(/\/+$/, "");
+        return `${u.protocol}//${host}${path}${u.search}`;
+    }
+    catch {
+        return raw.trim().toLowerCase();
+    }
+}
+/** Identity used for exact-repeat detection (search queries / URLs are normalized). */
+export function identityPayload(toolName, input) {
+    const rec = asRecord(input);
+    if (toolName === "search_web" && rec)
+        return serializeInput({ query: normalizeQuery(rec.query) });
+    if (toolName === "web_fetch" && rec)
+        return serializeInput({ url: normalizeUrl(rec.url) });
+    return serializeInput(input);
+}
+const URL_IN_TEXT = /https?:\/\/[^\s"'<>)\]}]+/g;
+const RESULT_ERROR = /^(error|search error|fetch error)\b/i;
+/** New URLs / domains found in a research result, ignoring ones already seen. */
+export function extractSources(text) {
+    const urls = new Set();
+    const hosts = new Set();
+    for (const raw of text.match(URL_IN_TEXT) ?? []) {
+        const url = normalizeUrl(raw);
+        if (url)
+            urls.add(url);
+        const host = hostOf(raw);
+        if (host)
+            hosts.add(host);
     }
-    return JSON.stringify(sorted);
+    return { urls: [...urls], hosts: [...hosts] };
 }
 export class DoomLoopDetector {
-    recentCalls = [];
-    /** Record a tool call. Returns true if a doom loop is detected. */
+    lastCall = { key: "", count: 0 };
+    callCounts = new Map();
+    webTotal = 0;
+    /** Research calls issued but whose results have not been seen yet. */
+    inFlight = 0;
+    /** Did the current batch of research calls bring anything new? */
+    batchProductive = false;
+    unproductiveRounds = 0;
+    steered = false;
+    capped = false;
+    delivered = false;
+    seenUrls = new Set();
+    seenHosts = new Set();
+    steerAfter;
+    stopAfter;
+    totalCap;
+    constructor(opts) {
+        this.steerAfter = positiveInt(opts?.steerAfter, RESEARCH_STEER_AFTER);
+        this.stopAfter = Math.max(positiveInt(opts?.stopAfter, RESEARCH_STOP_AFTER), this.steerAfter + 1);
+        this.totalCap = positiveInt(opts?.totalCap, RESEARCH_TOTAL_CAP);
+    }
+    get webResearchCount() {
+        return this.webTotal;
+    }
+    get researchCapped() {
+        return this.capped;
+    }
+    get producedArtifact() {
+        return this.delivered;
+    }
+    /** Research rounds in a row that returned no new sources. */
+    get unproductiveStreak() {
+        return this.unproductiveRounds;
+    }
+    /** Record a tool call. Returns true if the run should halt (exact identity loop). */
     record(toolName, input) {
-        const call = { toolName, input: serializeInput(input) };
-        this.recentCalls.push(call);
-        const window = this.recentCalls.slice(-THRESHOLD);
-        const allSame = window.length === THRESHOLD &&
-            window.every((c) => c.toolName === call.toolName && c.input === call.input);
-        // Keep only the most recent THRESHOLD-1 calls to bound memory
-        this.recentCalls = window.slice(-(THRESHOLD - 1));
-        if (allSame) {
-            this.recentCalls = [];
-            return true;
-        }
-        return false;
+        return this.observe(toolName, input) === "halt";
+    }
+    /** A tool call is starting. */
+    observe(toolName, input) {
+        const key = `${toolName}\u0000${identityPayload(toolName, input)}`;
+        if (this.lastCall.key === key)
+            this.lastCall.count++;
+        else
+            this.lastCall = { key, count: 1 };
+        const total = (this.callCounts.get(key) ?? 0) + 1;
+        this.callCounts.set(key, total);
+        if (this.lastCall.count >= EXACT_LOOP_THRESHOLD || total >= REPEAT_TOTAL_THRESHOLD) {
+            this.lastCall = { key: "", count: 0 };
+            this.callCounts.delete(key);
+            return "halt";
+        }
+        if (WEB_RESEARCH_TOOLS.has(toolName)) {
+            this.webTotal++;
+            if (this.inFlight === 0)
+                this.batchProductive = false;
+            this.inFlight++;
+            if (!this.capped && this.webTotal >= this.totalCap) {
+                this.markCapped();
+                return "cap";
+            }
+            return "ok";
+        }
+        if (ARTIFACT_TOOLS.has(toolName)) {
+            // Real progress: forgive the research history so far.
+            this.delivered = true;
+            this.unproductiveRounds = 0;
+        }
+        // Other tools neither help nor hurt the research budget.
+        return "ok";
+    }
+    /**
+     * A tool result came back. Research productivity is judged here, once the
+     * whole parallel batch has landed, so four fresh searches in one step are not
+     * mistaken for a loop.
+     */
+    observeResult(toolName, output) {
+        if (!WEB_RESEARCH_TOOLS.has(toolName))
+            return "ok";
+        const text = typeof output === "string" ? output : safeString(output);
+        if (!RESULT_ERROR.test(text.trim())) {
+            const { urls, hosts } = extractSources(text);
+            let fresh = 0;
+            for (const url of urls) {
+                if (!this.seenUrls.has(url)) {
+                    this.seenUrls.add(url);
+                    fresh++;
+                }
+            }
+            for (const host of hosts) {
+                if (!this.seenHosts.has(host)) {
+                    this.seenHosts.add(host);
+                    fresh++;
+                }
+            }
+            if (fresh > 0)
+                this.batchProductive = true;
+        }
+        if (this.inFlight > 0)
+            this.inFlight--;
+        if (this.inFlight > 0)
+            return "ok";
+        if (this.batchProductive) {
+            this.unproductiveRounds = 0;
+            return "ok";
+        }
+        this.unproductiveRounds++;
+        if (this.capped)
+            return "ok";
+        if (this.unproductiveRounds >= this.stopAfter) {
+            this.markCapped();
+            return "cap";
+        }
+        if (!this.steered && this.unproductiveRounds >= this.steerAfter) {
+            this.steered = true;
+            return "steer";
+        }
+        return "ok";
+    }
+    markCapped() {
+        this.capped = true;
+        this.steered = true;
+    }
+    promptHint() {
+        if (this.capped) {
+            return [
+                "## Research budget",
+                "search_web and web_fetch have been removed for the rest of this turn.",
+                "Produce the requested deliverable from information already in the conversation.",
+            ].join("\n");
+        }
+        if (this.webTotal < 4)
+            return "";
+        const lines = [
+            "## Research budget",
+            `Research calls this turn: ${this.webTotal}/${this.totalCap}; rounds without new sources: ${this.unproductiveRounds}/${this.stopAfter}.`,
+        ];
+        if (this.steered || this.unproductiveRounds >= this.steerAfter) {
+            lines.push("Recent searches added nothing new. Stop searching and produce the requested deliverable; mark uncertain fields instead of looking for more.");
+        }
+        else {
+            lines.push("Keep queries targeted: fetch the best sources, then write the output.");
+        }
+        return lines.join("\n");
     }
     reset() {
-        this.recentCalls = [];
+        this.lastCall = { key: "", count: 0 };
+        this.callCounts.clear();
+        this.webTotal = 0;
+        this.inFlight = 0;
+        this.batchProductive = false;
+        this.unproductiveRounds = 0;
+        this.steered = false;
+        this.capped = false;
+        this.delivered = false;
+        this.seenUrls.clear();
+        this.seenHosts.clear();
+    }
+}
+function safeString(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
     }
 }

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/instructions.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "async_hooks";
 import { readFileSync, existsSync } from "fs";
 import path from "path";
 import os from "os";
@@ -40,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.
@@ -68,6 +72,23 @@ export class InstructionTracker {
         return results;
     }
 }
+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 = [];
     const root = path.parse(process.cwd()).root;

package/dist/logger.js

@@ -34,13 +34,42 @@ 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}] ${scrubSecrets(msg)}\n`, { flag: "a" });
+        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(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,
 ];
@@ -55,7 +84,7 @@ export function log(level, msg) {
     writeLog(level, msg);
 }
 function summarize(v, max = 200) {
-    const s = typeof v === "string" ? v : JSON.stringify(v) ?? String(v);
+    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) {