aiden-runtime 4.1.4 → 4.5.0

package/dist/core/v4/verifier.js

@@ -0,0 +1,448 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/verifier.ts — v4.2 Phase 1: Per-tool result verifier.
+ *
+ * After each tool dispatch, the verifier inspects the result and
+ * classifies the outcome:
+ *
+ *   ok            — tool produced a usable, non-failed output
+ *   failed        — tool errored, returned `success: false`, or matched
+ *                   a known failure shape
+ *   no_progress   — tool succeeded but produced no useful signal (empty
+ *                   payload, identical hash to a recent call — Phase 3
+ *                   wires the hash repeat detector)
+ *   low_signal    — tool succeeded but with a short / vague response
+ *                   that's informative but probably won't help the
+ *                   model make progress
+ *   unknown       — verifier couldn't classify with confidence
+ *
+ * Scope (Phase 1):
+ * - Pure inspection of `(toolName, args, result)` — NO goal awareness
+ *   (deferred to Phase 5 / task graph).
+ * - Synchronous; runs in the agent's tool-dispatch loop between
+ *   `onToolCall('after', result)` and `turnState.recordToolCall(...)`.
+ * - Default fallback handles ~99% of Aiden tools that return the
+ *   `{ success: boolean, error?: string, ...payload }` envelope.
+ * - Built-in per-tool verifiers for 5 high-signal tools where the
+ *   default envelope inspection isn't sufficient: `shell_exec`,
+ *   `web_search`, `file_write`, `file_read`, `web_fetch`.
+ * - Behind the same gate as TurnState (default ON; opt-out via
+ *   `AIDEN_TCE=0`). When disabled, the agent skips verifier
+ *   classification — the registry is still constructed (cheap) but
+ *   `resolve()` is never called inside the gated branch.
+ *
+ * Out of scope (deferred phases):
+ * - Phase 2 — typed failure reason taxonomy (timeout / auth /
+ *   hallucination / network — separate from per-tool verifier).
+ * - Phase 3 — RecoveryReport (uses verifier output + Phase 2 classifier).
+ * - Phase 4 — checkpoint/restore (uses Phase 3 state shape).
+ * - Phase 5 — task-graph sub-step verification (extends VerifierFn
+ *   signature with optional `subGoal` argument; backward-compatible).
+ *
+ * The design intentionally mirrors a layered-decision pattern from the
+ * reference system's tool-guardrail module: a pure classifier function
+ * driving a controller's threshold counters, with per-tool overrides
+ * for the small set of tools where heuristic inspection is too coarse.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.browserInteractiveVerifier = exports.webFetchVerifier = exports.fileReadVerifier = exports.fileWriteVerifier = exports.webSearchVerifier = exports.shellExecVerifier = exports.defaultVerifier = exports.VerifierRegistry = void 0;
+exports.buildDefaultRegistry = buildDefaultRegistry;
+/**
+ * Per-tool override registry with a default-fallback resolver. Cheap
+ * to construct; safe to keep instantiated even when TCE is disabled
+ * because nothing runs unless `resolve(...)` is called by the agent
+ * loop (which itself is gated).
+ */
+class VerifierRegistry {
+    constructor(fallback = exports.defaultVerifier) {
+        this.overrides = new Map();
+        this.fallback = fallback;
+    }
+    register(toolName, fn) {
+        this.overrides.set(toolName, fn);
+    }
+    resolve(toolName) {
+        return this.overrides.get(toolName) ?? this.fallback;
+    }
+    /** Direct lookup for tests — returns true when a per-tool override is registered. */
+    hasOverride(toolName) {
+        return this.overrides.has(toolName);
+    }
+}
+exports.VerifierRegistry = VerifierRegistry;
+// ── Default fallback verifier ──────────────────────────────────────────────
+const SHORT_RESPONSE_THRESHOLD = 50; // chars — below this, raw strings are flagged low_signal
+const RAW_STRING_SCAN_WINDOW = 500; // chars — generic error keyword scan only looks at the head
+/**
+ * Heuristic default. Handles five result shapes in priority order:
+ *
+ *   1. Outer envelope error  → ToolCallResult.error set → failed (conf 1.0)
+ *   2. Inner `success: false` → typed failure (conf 1.0)
+ *   3. Inner `success: true`  → typed ok (conf 1.0)
+ *   4. Raw string < 50 chars  → low_signal (conf 0.4, ok: true)
+ *   5. Raw string with error keywords in first 500 chars → failed (conf 0.6)
+ *
+ * Anything else (typed object without `success`, non-empty string
+ * without error keywords) is `ok` at conf 0.7 — the verifier doesn't
+ * have enough signal to be more precise without a per-tool override.
+ */
+const defaultVerifier = (_toolName, _args, result) => {
+    // 1. Outer envelope error — executor threw or wrapped a known failure.
+    if (typeof result.error === 'string' && result.error.length > 0) {
+        return {
+            ok: false,
+            confidence: 1.0,
+            code: 'failed',
+            reason: result.error,
+        };
+    }
+    const inner = result.result;
+    // 2 + 3. Typed `{ success: boolean }` envelope — the common Aiden shape.
+    if (inner !== null && typeof inner === 'object' && !Array.isArray(inner)) {
+        const obj = inner;
+        if (obj.success === false) {
+            const reason = typeof obj.error === 'string' && obj.error.length > 0
+                ? obj.error
+                : 'tool returned success:false';
+            return {
+                ok: false,
+                confidence: 1.0,
+                code: 'failed',
+                reason,
+            };
+        }
+        if (obj.success === true) {
+            return { ok: true, confidence: 1.0, code: 'ok' };
+        }
+        // No `success` field — fall through to confidence-0.7 default.
+        return { ok: true, confidence: 0.7, code: 'ok' };
+    }
+    // 4 + 5. Raw string payload (the webSearch / deepResearch / openUrl shape).
+    if (typeof inner === 'string') {
+        const trimmed = inner.trim();
+        if (trimmed.length === 0) {
+            return {
+                ok: true,
+                confidence: 0.4,
+                code: 'low_signal',
+                reason: 'empty string result',
+            };
+        }
+        if (trimmed.length < SHORT_RESPONSE_THRESHOLD) {
+            return {
+                ok: true,
+                confidence: 0.4,
+                code: 'low_signal',
+                reason: `short result (${trimmed.length} chars)`,
+            };
+        }
+        const head = trimmed.slice(0, RAW_STRING_SCAN_WINDOW).toLowerCase();
+        if (head.startsWith('error') ||
+            head.includes('"error"') ||
+            head.includes('"failed"')) {
+            return {
+                ok: false,
+                confidence: 0.6,
+                code: 'failed',
+                reason: 'error keywords detected in raw string head',
+            };
+        }
+        return { ok: true, confidence: 0.7, code: 'ok' };
+    }
+    // null / undefined / array / number — no clear signal.
+    if (inner === null || inner === undefined) {
+        return {
+            ok: true,
+            confidence: 0.5,
+            code: 'unknown',
+            reason: 'null result',
+        };
+    }
+    return { ok: true, confidence: 0.5, code: 'unknown' };
+};
+exports.defaultVerifier = defaultVerifier;
+// ── Built-in per-tool verifiers ────────────────────────────────────────────
+/**
+ * `shell_exec` — inspect `exitCode` directly. A successful exit with
+ * empty stdout is suspicious (probe with no output) — surface as
+ * `low_signal` rather than ok-with-high-confidence so the loop
+ * controller can weight it.
+ */
+const shellExecVerifier = (_n, _a, result) => {
+    if (typeof result.error === 'string' && result.error.length > 0) {
+        return { ok: false, confidence: 1.0, code: 'failed', reason: result.error };
+    }
+    const inner = result.result;
+    if (inner === null || typeof inner !== 'object') {
+        return { ok: false, confidence: 0.5, code: 'unknown', reason: 'non-object shell_exec result' };
+    }
+    // Typed-failure envelope short-circuit — a wrapper returning
+    // `{success: false}` without exitCode is still definitively failed.
+    if (inner.success === false) {
+        return {
+            ok: false,
+            confidence: 1.0,
+            code: 'failed',
+            reason: typeof inner.error === 'string' ? inner.error : 'success:false',
+        };
+    }
+    const exitCode = typeof inner.exitCode === 'number' ? inner.exitCode : undefined;
+    if (exitCode === undefined) {
+        // Some wrappers omit exitCode on a successful run when the
+        // underlying command was trivial (e.g. a noop). Trust the typed
+        // success flag if present; otherwise we genuinely don't know.
+        if (inner.success === true) {
+            return { ok: true, confidence: 0.7, code: 'ok' };
+        }
+        return { ok: false, confidence: 0.5, code: 'unknown', reason: 'missing exitCode' };
+    }
+    if (exitCode !== 0) {
+        return {
+            ok: false,
+            confidence: 1.0,
+            code: 'failed',
+            reason: `non-zero exit (${exitCode})`,
+            suggestion: 'Inspect stderr and adjust the command — repeating the same invocation will not help.',
+        };
+    }
+    const stdout = typeof inner.stdout === 'string' ? inner.stdout.trim() : '';
+    if (stdout.length === 0) {
+        return {
+            ok: true,
+            confidence: 0.4,
+            code: 'low_signal',
+            reason: 'exit 0 with empty stdout',
+        };
+    }
+    return { ok: true, confidence: 1.0, code: 'ok' };
+};
+exports.shellExecVerifier = shellExecVerifier;
+/**
+ * `web_search` — returns a raw string (synthesised answer). Short
+ * responses are low-signal, not failures (often "no results found"
+ * IS the answer). Generic error-keyword scan applies.
+ */
+const webSearchVerifier = (_n, _a, result) => {
+    if (typeof result.error === 'string' && result.error.length > 0) {
+        return { ok: false, confidence: 1.0, code: 'failed', reason: result.error };
+    }
+    const inner = result.result;
+    if (typeof inner !== 'string') {
+        // Some adapters might wrap the string in `{ success, result }`.
+        return (0, exports.defaultVerifier)(_n, _a, result);
+    }
+    const trimmed = inner.trim();
+    if (trimmed.length === 0) {
+        return {
+            ok: true,
+            confidence: 0.4,
+            code: 'low_signal',
+            reason: 'empty web_search result',
+            suggestion: 'Try a different query or use web_fetch with a known URL.',
+        };
+    }
+    if (trimmed.length < SHORT_RESPONSE_THRESHOLD) {
+        return {
+            ok: true,
+            confidence: 0.4,
+            code: 'low_signal',
+            reason: `short web_search result (${trimmed.length} chars)`,
+        };
+    }
+    return { ok: true, confidence: 0.9, code: 'ok' };
+};
+exports.webSearchVerifier = webSearchVerifier;
+/**
+ * `file_write` — verify the write actually happened. We trust the
+ * tool's `success` flag but additionally require `bytesWritten > 0`
+ * when present (catches the "wrote 0 bytes" pathology).
+ */
+const fileWriteVerifier = (_n, _a, result) => {
+    if (typeof result.error === 'string' && result.error.length > 0) {
+        return { ok: false, confidence: 1.0, code: 'failed', reason: result.error };
+    }
+    const inner = result.result;
+    if (inner === null || typeof inner !== 'object') {
+        return { ok: false, confidence: 0.5, code: 'unknown', reason: 'non-object file_write result' };
+    }
+    if (inner.success === false) {
+        return {
+            ok: false,
+            confidence: 1.0,
+            code: 'failed',
+            reason: typeof inner.error === 'string' ? inner.error : 'success:false',
+        };
+    }
+    if (typeof inner.bytesWritten === 'number' && inner.bytesWritten === 0) {
+        return {
+            ok: true,
+            confidence: 0.4,
+            code: 'low_signal',
+            reason: 'wrote 0 bytes',
+        };
+    }
+    return { ok: true, confidence: 1.0, code: 'ok' };
+};
+exports.fileWriteVerifier = fileWriteVerifier;
+/**
+ * `file_read` — verify content non-empty (a deliberately-empty file
+ * is rare; usually means a path mismatch or stale read). Trusts the
+ * tool's `success` flag.
+ */
+const fileReadVerifier = (_n, _a, result) => {
+    if (typeof result.error === 'string' && result.error.length > 0) {
+        return { ok: false, confidence: 1.0, code: 'failed', reason: result.error };
+    }
+    const inner = result.result;
+    if (inner === null || typeof inner !== 'object') {
+        return { ok: false, confidence: 0.5, code: 'unknown', reason: 'non-object file_read result' };
+    }
+    if (inner.success === false) {
+        return {
+            ok: false,
+            confidence: 1.0,
+            code: 'failed',
+            reason: typeof inner.error === 'string' ? inner.error : 'success:false',
+        };
+    }
+    const content = typeof inner.content === 'string' ? inner.content : '';
+    if (content.length === 0) {
+        return {
+            ok: true,
+            confidence: 0.4,
+            code: 'low_signal',
+            reason: 'empty file content',
+        };
+    }
+    return { ok: true, confidence: 1.0, code: 'ok' };
+};
+exports.fileReadVerifier = fileReadVerifier;
+/**
+ * `web_fetch` (and aliases) — verify the body is substantive. A
+ * < 100 char fetch body is almost certainly a redirect / blank
+ * page / soft-block; surface as low_signal.
+ */
+const WEB_FETCH_MIN_BODY = 100;
+const webFetchVerifier = (_n, _a, result) => {
+    if (typeof result.error === 'string' && result.error.length > 0) {
+        return { ok: false, confidence: 1.0, code: 'failed', reason: result.error };
+    }
+    const inner = result.result;
+    // Two shapes: typed `{ success, content/body }` or raw string.
+    if (typeof inner === 'string') {
+        if (inner.trim().length < WEB_FETCH_MIN_BODY) {
+            return {
+                ok: true,
+                confidence: 0.4,
+                code: 'low_signal',
+                reason: `short body (${inner.trim().length} chars)`,
+                suggestion: 'Try a different URL or check whether the page requires auth.',
+            };
+        }
+        return { ok: true, confidence: 0.9, code: 'ok' };
+    }
+    if (inner !== null && typeof inner === 'object') {
+        const obj = inner;
+        if (obj.success === false) {
+            return {
+                ok: false,
+                confidence: 1.0,
+                code: 'failed',
+                reason: typeof obj.error === 'string' ? obj.error : 'success:false',
+            };
+        }
+        const body = typeof obj.content === 'string' ? obj.content :
+            typeof obj.body === 'string' ? obj.body :
+                typeof obj.text === 'string' ? obj.text : '';
+        if (body.trim().length < WEB_FETCH_MIN_BODY) {
+            return {
+                ok: true,
+                confidence: 0.4,
+                code: 'low_signal',
+                reason: `short body (${body.trim().length} chars)`,
+            };
+        }
+        return { ok: true, confidence: 1.0, code: 'ok' };
+    }
+    return (0, exports.defaultVerifier)(_n, _a, result);
+};
+exports.webFetchVerifier = webFetchVerifier;
+/**
+ * v4.3 Phase 5 — verifier for the 3 interactive browser tools
+ * (`browser_click`, `browser_type`, `browser_fill`) and
+ * `browser_navigate`. Extends defaultVerifier with one extra check:
+ * when the tool returns `success: true` BUT Phase 1's observer flagged
+ * `needs_verifier === true` (page state didn't meaningfully change),
+ * demote `ok` to false so the classifier runs and routes to
+ * `stale_ref` (page unresponsive) for the right recovery action.
+ *
+ * Without this demotion, the `needs_verifier` field would be a
+ * dormant hint with no behavioral effect. The whole point of Phase 1
+ * capturing it was to gate this verifier check.
+ *
+ * Conservative ordering — only runs the demotion AFTER the default
+ * verifier passed. Failed calls still classify via the existing
+ * path; success-but-noop is the specific case Phase 5 handles.
+ */
+const browserInteractiveVerifier = (toolName, args, result) => {
+    const base = (0, exports.defaultVerifier)(toolName, args, result);
+    if (!base.ok)
+        return base;
+    // Read the v4.3 sidecar. Absent when browser depth is opt'd out
+    // (AIDEN_BROWSER_DEPTH=0) — in
+    // that case the verifier falls back to the default-passing result.
+    const inner = result.result;
+    if (!inner || typeof inner !== 'object')
+        return base;
+    const bs = inner.browserState;
+    if (!bs)
+        return base;
+    if (!bs.needs_verifier)
+        return base;
+    // Demote — the tool returned success but the page didn't change
+    // meaningfully. Classifier will route to stale_ref.
+    return {
+        ok: false,
+        confidence: 0.75,
+        code: bs.maybe_noop ? 'no_progress' : 'low_signal',
+        reason: bs.maybe_noop
+            ? 'tool returned success but page state did not change'
+            : `low progress (${bs.progress_score.toFixed(2)}) — UI may not have responded`,
+    };
+};
+exports.browserInteractiveVerifier = browserInteractiveVerifier;
+// ── Factory ────────────────────────────────────────────────────────────────
+/**
+ * Builds a registry pre-wired with the 5 built-in per-tool verifiers.
+ * The agent constructs one of these in `runConversation` when TCE is
+ * enabled. Plugin authors can register their own via the returned
+ * registry instance — Phase 1 doesn't expose a public registration
+ * API, but the foundation is here.
+ */
+function buildDefaultRegistry() {
+    const reg = new VerifierRegistry();
+    reg.register('shell_exec', exports.shellExecVerifier);
+    reg.register('web_search', exports.webSearchVerifier);
+    reg.register('file_write', exports.fileWriteVerifier);
+    reg.register('file_read', exports.fileReadVerifier);
+    reg.register('web_fetch', exports.webFetchVerifier);
+    // Aliases — same verifier handles related shapes.
+    reg.register('fetch_page', exports.webFetchVerifier);
+    reg.register('web_page', exports.webFetchVerifier);
+    // v4.3 Phase 5 — browser interactive verifier reads the Phase 1
+    // sidecar (`needs_verifier` / `maybe_noop`) and demotes
+    // success-but-no-progress cases so the classifier routes them to
+    // `stale_ref` recovery. Falls back to defaultVerifier when sidecar
+    // absent (opt-out via AIDEN_BROWSER_DEPTH=0).
+    reg.register('browser_click', exports.browserInteractiveVerifier);
+    reg.register('browser_type', exports.browserInteractiveVerifier);
+    reg.register('browser_fill', exports.browserInteractiveVerifier);
+    reg.register('browser_navigate', exports.browserInteractiveVerifier);
+    return reg;
+}

package/dist/core/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // AUTO-GENERATED by scripts/inject-version.js — do not edit by hand
-exports.VERSION = '4.1.4';
+exports.VERSION = '4.5.0';

package/dist/core/webSearch.js

@@ -7,6 +7,46 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.reliableWebSearch = reliableWebSearch;
 exports.deepResearch = deepResearch;
 exports.checkSearxNG = checkSearxNG;
+// core/webSearch.ts — Reliable web search with 4-method fallback chain
+//
+// Priority order:
+//   1. SearxNG (self-hosted, unlimited, Docker on port 8888)
+//   2. Brave Search API (if BRAVE_SEARCH_API_KEY env var set)
+//   3. DuckDuckGo Instant Answer API + HTML scrape
+//   4. Wikipedia (always available, good for factual queries)
+//
+// Usage:
+//   import { reliableWebSearch, deepResearch } from './webSearch'
+//   const result = await reliableWebSearch('query')
+// ── Debug logging (v4.1.5 Issue O) ────────────────────────────
+//
+// All `[webSearch]` / `[deepResearch]` chatter goes through these two
+// helpers, both gated on `process.env.AIDEN_DEBUG_WEB === '1'`. The
+// v4 REPL ran with these blasting unconditionally to stdout/stderr,
+// surfacing 20+ lines of fallback-chain diagnostics between the user
+// prompt and Aiden's reply on any web-search turn — overwhelming the
+// signal users actually wanted (the tool-trail row).
+//
+// Power users debugging a flaky search backend export the env var:
+//     AIDEN_DEBUG_WEB=1 aiden
+// Same pattern as `AIDEN_NO_REFORMAT`, `AIDEN_UI_ICONS`. Default off.
+//
+// `core/webSearch.ts` is shared with the legacy v3 path which has no
+// Display dependency, so we cannot route through `display.dim()` /
+// the v4 verbose-mode config. An env var is the lowest-friction
+// transport that works in both paths.
+function debugLog(...args) {
+    if (process.env.AIDEN_DEBUG_WEB === '1') {
+        // eslint-disable-next-line no-console
+        console.log(...args);
+    }
+}
+function debugWarn(...args) {
+    if (process.env.AIDEN_DEBUG_WEB === '1') {
+        // eslint-disable-next-line no-console
+        console.warn(...args);
+    }
+}
 // ── Constants ─────────────────────────────────────────────────
 const SEARXNG_URL = process.env.SEARXNG_URL || 'http://localhost:8888';
 const BRAVE_API_KEY = process.env.BRAVE_SEARCH_API_KEY || '';
@@ -21,7 +61,7 @@ async function searchViaSearxNG(query) {
             signal: AbortSignal.timeout(SEARCH_TIMEOUT),
         });
         if (!res.ok) {
-            console.warn(`[webSearch] SearxNG returned ${res.status}`);
+            debugWarn(`[webSearch] SearxNG returned ${res.status}`);
             return null;
         }
         const data = await res.json();
@@ -35,11 +75,11 @@ async function searchViaSearxNG(query) {
             return null;
         const lines = results.map(r => `**${r.title}**\n${r.snippet}\n${r.url}`);
         const output = `[SearxNG Results for "${query}"]\n\n${lines.join('\n\n')}`;
-        console.log(`[webSearch] SearxNG: ${results.length} results`);
+        debugLog(`[webSearch] SearxNG: ${results.length} results`);
         return { success: true, output, method: 'searxng', results };
     }
     catch (e) {
-        console.warn(`[webSearch] SearxNG failed: ${e.message}`);
+        debugWarn(`[webSearch] SearxNG failed: ${e.message}`);
         return null;
     }
 }
@@ -58,7 +98,7 @@ async function searchViaBrave(query) {
             signal: AbortSignal.timeout(SEARCH_TIMEOUT),
         });
         if (!res.ok) {
-            console.warn(`[webSearch] Brave API returned ${res.status}`);
+            debugWarn(`[webSearch] Brave API returned ${res.status}`);
             return null;
         }
         const data = await res.json();
@@ -73,11 +113,11 @@ async function searchViaBrave(query) {
         }));
         const lines = results.map(r => `**${r.title}**\n${r.snippet}\n${r.url}`);
         const output = `[Brave Search Results for "${query}"]\n\n${lines.join('\n\n')}`;
-        console.log(`[webSearch] Brave: ${results.length} results`);
+        debugLog(`[webSearch] Brave: ${results.length} results`);
         return { success: true, output, method: 'brave', results };
     }
     catch (e) {
-        console.warn(`[webSearch] Brave failed: ${e.message}`);
+        debugWarn(`[webSearch] Brave failed: ${e.message}`);
         return null;
     }
 }
@@ -108,7 +148,7 @@ async function searchViaDDG(query) {
         }
     }
     catch (e) {
-        console.warn(`[webSearch] DDG Instant failed: ${e.message}`);
+        debugWarn(`[webSearch] DDG Instant failed: ${e.message}`);
     }
     // DDG HTML scrape — get snippet text + page content
     try {
@@ -164,12 +204,12 @@ async function searchViaDDG(query) {
             parts.push(...validPages);
     }
     catch (e) {
-        console.warn(`[webSearch] DDG HTML scrape failed: ${e.message}`);
+        debugWarn(`[webSearch] DDG HTML scrape failed: ${e.message}`);
     }
     if (parts.length === 0)
         return null;
     const output = `[DuckDuckGo Results for "${query}"]\n\n${parts.join('\n\n')}`;
-    console.log(`[webSearch] DDG: ${parts.length} sections`);
+    debugLog(`[webSearch] DDG: ${parts.length} sections`);
     return { success: true, output, method: 'ddg' };
 }
 // ── METHOD 4: Wikipedia ───────────────────────────────────────
@@ -193,11 +233,11 @@ async function searchViaWikipedia(query) {
             .filter(s => s.length > 20);
         const extra = snippets.length > 0 ? `\n\nRelated: ${snippets.join(' | ')}` : '';
         const output = `[Wikipedia: ${wiki.title}]\n${wiki.extract.slice(0, 1500)}${extra}`;
-        console.log(`[webSearch] Wikipedia: ${wiki.extract.length} chars for "${wiki.title}"`);
+        debugLog(`[webSearch] Wikipedia: ${wiki.extract.length} chars for "${wiki.title}"`);
         return { success: true, output, method: 'wikipedia' };
     }
     catch (e) {
-        console.warn(`[webSearch] Wikipedia failed: ${e.message}`);
+        debugWarn(`[webSearch] Wikipedia failed: ${e.message}`);
         return null;
     }
 }
@@ -229,11 +269,11 @@ async function fetchWeather(query) {
                 out += `  ${day.date}: High ${day.maxtempC}°C / Low ${day.mintempC}°C${mid ? ' — ' + mid : ''}\n`;
             }
         }
-        console.log(`[webSearch] Weather: retrieved for "${city}"`);
+        debugLog(`[webSearch] Weather: retrieved for "${city}"`);
         return { success: true, output: out.trim(), method: 'wttr.in' };
     }
     catch (e) {
-        console.warn(`[webSearch] Weather failed: ${e.message}`);
+        debugWarn(`[webSearch] Weather failed: ${e.message}`);
         return null;
     }
 }
@@ -241,7 +281,7 @@ async function fetchWeather(query) {
 async function reliableWebSearch(query) {
     if (!query?.trim())
         return { success: false, output: '', error: 'No query provided' };
-    console.log(`[webSearch] Query: "${query}"`);
+    debugLog(`[webSearch] Query: "${query}"`);
     // Weather shortcut
     if (/weather|temperature|forecast|rain|snow|sunny|cloudy|humidity|wind/i.test(query)) {
         const weather = await fetchWeather(query);
@@ -251,28 +291,28 @@ async function reliableWebSearch(query) {
     // Method 1 — SearxNG
     const searxResult = await searchViaSearxNG(query);
     if (searxResult) {
-        console.log(`[webSearch] ✓ SearxNG succeeded`);
+        debugLog(`[webSearch] ✓ SearxNG succeeded`);
         return { success: true, output: searxResult.output.slice(0, 10000) };
     }
     // Method 2 — Brave
     const braveResult = await searchViaBrave(query);
     if (braveResult) {
-        console.log(`[webSearch] ✓ Brave succeeded`);
+        debugLog(`[webSearch] ✓ Brave succeeded`);
         return { success: true, output: braveResult.output.slice(0, 10000) };
     }
     // Method 3 — DDG
     const ddgResult = await searchViaDDG(query);
     if (ddgResult) {
-        console.log(`[webSearch] ✓ DDG succeeded`);
+        debugLog(`[webSearch] ✓ DDG succeeded`);
         return { success: true, output: ddgResult.output.slice(0, 10000) };
     }
     // Method 4 — Wikipedia
     const wikiResult = await searchViaWikipedia(query);
     if (wikiResult) {
-        console.log(`[webSearch] ✓ Wikipedia fallback`);
+        debugLog(`[webSearch] ✓ Wikipedia fallback`);
         return { success: true, output: wikiResult.output };
     }
-    console.warn(`[webSearch] All methods failed for: "${query}"`);
+    debugWarn(`[webSearch] All methods failed for: "${query}"`);
     return {
         success: false,
         output: '',
@@ -283,24 +323,24 @@ async function reliableWebSearch(query) {
 async function deepResearch(topic) {
     if (!topic?.trim())
         return { success: false, output: '', error: 'No topic provided' };
-    console.log(`[deepResearch] Topic: "${topic}"`);
+    debugLog(`[deepResearch] Topic: "${topic}"`);
     const parts = [];
     // Pass 1: Broad
-    console.log(`[deepResearch] Pass 1: broad`);
+    debugLog(`[deepResearch] Pass 1: broad`);
     const broad = await reliableWebSearch(topic);
     if (broad.success && broad.output.length > 100) {
         parts.push(`=== PASS 1: BROAD RESEARCH ===\n${broad.output}`);
     }
     // Pass 2: Latest 2026
     const latestQ = `${topic} 2026 latest`;
-    console.log(`[deepResearch] Pass 2: latest — "${latestQ}"`);
+    debugLog(`[deepResearch] Pass 2: latest — "${latestQ}"`);
     const latest = await reliableWebSearch(latestQ);
     if (latest.success && latest.output.length > 100) {
         parts.push(`=== PASS 2: LATEST (2026) ===\n${latest.output}`);
     }
     // Pass 3: Comparison / review
     const compareQ = `best top ${topic} comparison review`;
-    console.log(`[deepResearch] Pass 3: comparison — "${compareQ}"`);
+    debugLog(`[deepResearch] Pass 3: comparison — "${compareQ}"`);
     const compare = await reliableWebSearch(compareQ);
     if (compare.success && compare.output.length > 100) {
         parts.push(`=== PASS 3: COMPARISON & REVIEWS ===\n${compare.output}`);
@@ -309,7 +349,7 @@ async function deepResearch(topic) {
         return { success: false, output: '', error: `No research results found for: ${topic}` };
     }
     const combined = parts.join('\n\n');
-    console.log(`[deepResearch] Complete: ${combined.length} chars across ${parts.length} passes`);
+    debugLog(`[deepResearch] Complete: ${combined.length} chars across ${parts.length} passes`);
     return { success: true, output: combined.slice(0, 15000) };
 }
 // ── SearxNG health check ──────────────────────────────────────