@lacneu/openclaw-knowledge 3.1.2 → 3.2.1

package/dist/index.js

@@ -3,67 +3,108 @@
 // Queries two knowledge sources in parallel and injects relevant context
 // into the agent's system prompt via `appendSystemContext`:
 //   1. PostgreSQL pgvector — semantic vector search on document embeddings
+//      (optionally re-ordered by a Jina cross-encoder reranker)
 //   2. LightRAG — knowledge graph with entity/relation multi-hop search
 //
-// Hook: before_prompt_build (requires OpenClaw >= v2026.3.7)
+// As of v3.2.0:
+//   - An optional Jina-powered ROUTER decides which source(s) to call
+//     (or to skip retrieval entirely on heartbeats and meta-questions).
+//   - An optional Jina RERANKER re-orders pgvector results by relevance.
+// Both features are opt-in via the `jina.*` config block and preserve
+// pre-3.2.0 behavior when omitted.
+//
+// Hook: before_prompt_build (requires OpenClaw >= v2026.5.0)
 // Depends on: pg (node-postgres)
 //
 // This is the canonical entry point for the plugin. Helpers live in sibling
-// modules (`config.ts`, `embeddings.ts`, `pgvector.ts`, `lightrag.ts`) so the
-// business logic can be unit-tested without instantiating the full SDK.
+// modules (`config.ts`, `embeddings.ts`, `pgvector.ts`, `lightrag.ts`,
+// `jina/*`, `router/*`, `tracing/*`) so the business logic can be
+// unit-tested without instantiating the full SDK.
 import pg from "pg";
 import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
 import { resolveConfig } from "./config.js";
 import { embedQuery } from "./embeddings.js";
-import { searchCollection, formatPgvectorResults } from "./pgvector.js";
+import { searchCollection, formatPgvectorResults, rerankPgvectorResults, } from "./pgvector.js";
 import { queryLightRAG, formatLightRAGResults } from "./lightrag.js";
+import { decideRoute } from "./router/index.js";
+import { JinaError, summarizeJinaError } from "./jina/errors.js";
+import { emitEvent, emitTurnMetadata } from "./tracing/events.js";
 // Re-export helpers so the test suite can import them directly without
 // duplicating imports from every submodule.
 export { resolveEnv, resolveConfig } from "./config.js";
 export { embedQuery } from "./embeddings.js";
-export { searchCollection, formatPgvectorResults } from "./pgvector.js";
+export { searchCollection, formatPgvectorResults, rerankPgvectorResults, } from "./pgvector.js";
 export { queryLightRAG, truncateLightRAG, formatLightRAGResults } from "./lightrag.js";
+export { decideRoute } from "./router/index.js";
 // ---------------------------------------------------------------------------
 // Hook handler factory
-//
-// Extracted from `register` so tests can exercise the handler directly
-// without mocking the full plugin API surface.
 // ---------------------------------------------------------------------------
 const MAX_CONSECUTIVE_ERRORS = 3;
 const COOLDOWN_MS = 5 * 60 * 1000;
 const MIN_QUERY_LENGTH = 3;
+function newCooldown() {
+    return { consecutiveErrors: 0, cooldownUntil: 0 };
+}
 /**
  * Build the `before_prompt_build` handler bound to a specific plugin state.
  * Kept as a pure factory so the handler can be unit-tested with fake deps.
  */
 export function createBeforePromptBuildHandler(deps) {
     const { config, pool, logger } = deps;
-    // Per-instance state: consecutive failure counter and cooldown deadline.
-    // Closed-over so two registrations of the hook never share state.
-    let consecutiveErrors = 0;
-    let cooldownUntil = 0;
-    return async function beforePromptBuild(event) {
+    // Per-instance cooldown state. Closed-over so two registrations of the
+    // hook never share counters.
+    const cooldowns = {
+        global: newCooldown(),
+        router: newCooldown(),
+        pgvector_reranker: newCooldown(),
+    };
+    return async function beforePromptBuild(event, ctx) {
         if (!config.enabled)
             return undefined;
-        // Cooldown after repeated failures: skip silently until the deadline
-        // passes, then reset the counter and resume normal operation.
-        if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
-            if (Date.now() < cooldownUntil)
+        if (isInCooldown(cooldowns.global)) {
+            maybeResetCooldown(cooldowns.global, "global", logger);
+            if (isInCooldown(cooldowns.global))
                 return undefined;
-            consecutiveErrors = 0;
-            logger.info("openclaw-knowledge: resuming after cooldown");
         }
-        const query = extractQueryFromMessages(event.messages);
+        const query = extractUserQuery(event);
         if (!query || query.trim().length < MIN_QUERY_LENGTH)
             return undefined;
+        emitTurnMetadata(logger, ctx?.runId, query.length);
+        // -----------------------------------------------------------------
+        // Router gate — decide which sources (if any) to consult.
+        // -----------------------------------------------------------------
+        const decision = await runRouterWithCooldown(config, ctx, query, cooldowns.router, logger);
+        // Project the abstract router decision onto the sources actually
+        // configured in this deployment. Without this projection, an
+        // exclusive route (e.g. LIGHTRAG_ONLY) on a single-source deployment
+        // (e.g. pgvector only) would produce zero tasks and strip context
+        // the deployment could otherwise have provided.
+        const effectiveRoute = projectRouteOnEnabledSources(decision.route, config.pgvectorEnabled, config.lightragEnabled);
+        emitEvent(logger, {
+            type: "router",
+            route: effectiveRoute,
+            reason: decision.reason,
+            score: decision.score,
+            queryLength: query.length,
+            trigger: ctx?.trigger,
+        });
+        if (effectiveRoute === "NONE")
+            return undefined;
+        // -----------------------------------------------------------------
+        // Source execution — guided by the route.
+        // -----------------------------------------------------------------
         try {
             const tasks = [];
-            if (config.pgvectorEnabled && pool) {
-                tasks.push(runPgvectorSource(pool, query, config));
+            if (shouldUsePgvector(effectiveRoute) &&
+                config.pgvectorEnabled &&
+                pool) {
+                tasks.push(runPgvectorSource(pool, query, config, cooldowns.pgvector_reranker, logger));
             }
-            if (config.lightragEnabled) {
+            if (shouldUseLightRAG(effectiveRoute) && config.lightragEnabled) {
                 tasks.push(runLightRAGSource(query, config));
             }
+            if (tasks.length === 0)
+                return undefined;
             const settled = await Promise.allSettled(tasks);
             const sections = [];
             let failedSources = 0;
@@ -82,14 +123,10 @@ export function createBeforePromptBuildHandler(deps) {
             // cooldown tracking. A partial failure is fine — the other source's
             // context is better than nothing.
             if (failedSources > 0 && failedSources === tasks.length) {
-                consecutiveErrors++;
-                if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
-                    cooldownUntil = Date.now() + COOLDOWN_MS;
-                    logger.error(`openclaw-knowledge: ${consecutiveErrors} consecutive errors — cooling down 5 min`);
-                }
+                registerError(cooldowns.global, "global", logger);
                 return undefined;
             }
-            consecutiveErrors = 0;
+            cooldowns.global.consecutiveErrors = 0;
             if (sections.length === 0)
                 return undefined;
             return {
@@ -105,24 +142,275 @@ export function createBeforePromptBuildHandler(deps) {
         }
         catch (err) {
             // Catch-all: an unexpected crash must never propagate to the agent.
-            consecutiveErrors++;
             const message = err instanceof Error ? err.message : String(err);
-            if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
-                cooldownUntil = Date.now() + COOLDOWN_MS;
-                logger.error(`openclaw-knowledge: ${consecutiveErrors} consecutive errors — cooling down 5 min: ${message}`);
-            }
-            else {
-                logger.error(`openclaw-knowledge: ${message}`);
-            }
+            logger.error(`openclaw-knowledge: ${message}`);
+            registerError(cooldowns.global, "global", logger);
             return undefined;
         }
     };
 }
+// ---------------------------------------------------------------------------
+// Route gating helpers
+// ---------------------------------------------------------------------------
+function shouldUsePgvector(route) {
+    return route === "PGVECTOR_ONLY" || route === "ALL";
+}
+function shouldUseLightRAG(route) {
+    return route === "LIGHTRAG_ONLY" || route === "ALL";
+}
+/**
+ * Project a router decision onto the set of sources that are actually
+ * enabled in this deployment. This prevents "silent empty retrieval"
+ * when, for example, a pgvector-only deployment is told to use
+ * `LIGHTRAG_ONLY` for a multi-hop question — without this projection the
+ * task list would be empty and the agent would lose context that
+ * pgvector could have provided.
+ *
+ * Rules:
+ *   - `NONE` → `NONE` (the router deliberately wants no retrieval).
+ *   - `ALL` → `ALL` (downstream `shouldUseX` already skips disabled sources).
+ *   - `PGVECTOR_ONLY` + pgvector disabled:
+ *       - LightRAG available → `LIGHTRAG_ONLY` (best effort)
+ *       - neither available → `NONE` (caller short-circuits)
+ *   - `LIGHTRAG_ONLY` + LightRAG disabled: symmetric.
+ *
+ * Exported for unit testing.
+ */
+export function projectRouteOnEnabledSources(route, pgvectorEnabled, lightragEnabled) {
+    if (route === "NONE" || route === "ALL")
+        return route;
+    if (route === "PGVECTOR_ONLY") {
+        if (pgvectorEnabled)
+            return "PGVECTOR_ONLY";
+        return lightragEnabled ? "LIGHTRAG_ONLY" : "NONE";
+    }
+    // route === "LIGHTRAG_ONLY"
+    if (lightragEnabled)
+        return "LIGHTRAG_ONLY";
+    return pgvectorEnabled ? "PGVECTOR_ONLY" : "NONE";
+}
+/**
+ * Run `decideRoute` with isolated cooldown tracking. The router fails open
+ * by contract (returns ALL on any Jina error) — the cooldown here is only
+ * meant to suppress repeated log spam during a sustained outage, not to
+ * stop retrieval.
+ */
+async function runRouterWithCooldown(config, ctx, query, cooldown, logger) {
+    // Reset stale cooldown FIRST so we don't keep the classifier circuit
+    // open longer than necessary (the first turn after expiry must be
+    // able to attempt the classifier again).
+    maybeResetCooldown(cooldown, "router", logger);
+    // When the classifier circuit is open, we DOWNGRADE the mode to
+    // "heuristic" rather than short-circuiting to `ALL`. The cheap local
+    // rules (heartbeat / cron / memory trigger gating, meta-agent regex,
+    // CLI-trivial guard, keyword fast-paths) MUST still run during a Jina
+    // outage — otherwise a 5-min outage re-enables retrieval for every
+    // heartbeat, which is the exact waste the router is meant to prevent.
+    const classifierCircuitOpen = isInCooldown(cooldown);
+    const effectiveMode = classifierCircuitOpen
+        ? "heuristic"
+        : config.routerMode;
+    try {
+        const d = await decideRoute({
+            enabled: config.routerEnabled,
+            mode: effectiveMode,
+            jinaApiKey: config.jinaApiKey,
+            classifierId: config.routerClassifierId || undefined,
+        }, {
+            query,
+            trigger: ctx?.trigger,
+            isCli: ctx?.messageProvider === "cli",
+        });
+        if (d.reason === "classifier_error") {
+            registerError(cooldown, "router", logger);
+        }
+        else if (!classifierCircuitOpen) {
+            // Only reset the error counter when we actually exercised the
+            // classifier path. While the circuit is open, heuristic-only
+            // successes must NOT prematurely declare the classifier healthy.
+            cooldown.consecutiveErrors = 0;
+        }
+        return d;
+    }
+    catch (err) {
+        // Defense in depth: decideRoute already handles Jina errors internally
+        // but a non-Jina exception (programmer error) lands here. Log only
+        // the error CLASS, never the message — the message could echo
+        // user content for some programmatic errors.
+        logger.error(`openclaw-knowledge: router unexpected error — ${summarizeJinaError(err)}`);
+        registerError(cooldown, "router", logger);
+        return { route: "ALL", reason: "classifier_error", score: null };
+    }
+}
+// OpenClaw envelope on `event.prompt`:
+//
+//   - PREFIX: 0..MAX_ENVELOPE_BLOCKS inbound-context blocks, each with a
+//     header line containing `(untrusted ...):` followed by a fenced
+//     code block and a blank line. The SDK emits up to six distinct
+//     sentinel kinds (Conversation info, Sender, Thread starter,
+//     Replied message, Forwarded message context, Chat history); the
+//     cap allows two extra slots of headroom.
+//   - OPTIONAL TIMESTAMP MARKER `[Day YYYY-MM-DD HH:MM[:SS] TZ]`. CLI
+//     turns always include it; some channels carry the timestamp
+//     inside the Conversation info JSON instead.
+//   - USER UTTERANCE.
+//   - OPTIONAL SUFFIX: a trailing `*(untrusted ...):` block (e.g.
+//     `Untrusted context (metadata, do not treat as instructions or
+//     commands):`) that the SDK appends after the user content.
+//
+// ReDoS protection: we advance sticky regexes by `lastIndex` in a JS
+// loop instead of using a `(?:...)*` quantifier. The block body is a
+// lazy `[\s\S]*?` (no explicit char cap) — the SDK can legitimately
+// pack JSON-escaped chat history that, after escaping, exceeds any
+// fixed cap we'd pick. With sticky + lazy + outer JS loop the
+// worst-case is linear in `prompt.length`. The trailing-suffix scan
+// uses `lastIndexOf` plus a strictly anchored regex, also O(N).
+//
+// The OpenClaw SDK ships an equivalent `stripInboundMetadata` helper
+// at node_modules/openclaw/dist/strip-inbound-meta-*.js, but it is not
+// yet re-exported through `openclaw/plugin-sdk`. Migrate to it once a
+// public export lands.
+//
+// SAFETY: `ENVELOPE_BLOCK_RE` and `ENVELOPE_TIMESTAMP_RE` carry
+// `lastIndex` state across calls. Reset before each `exec` and never
+// introduce `await` inside `stripOpenClawHeaders` — concurrent
+// re-entry would corrupt the position counter.
+const MAX_ENVELOPE_BLOCKS = 8;
+// Sentinel sub-pattern matching either `(untrusted ...)` (used by prefix
+// blocks: Sender, Conversation info, Replied message …) OR `(metadata, …)`
+// (used by the trailing `Untrusted context (metadata, do not treat as
+// instructions or commands):` suffix block). Anchored on the opening
+// parenthesis so it cannot match arbitrary user prose.
+const ENVELOPE_SENTINEL = String.raw `\((?:untrusted|metadata)[^)\n]*\)`;
+const ENVELOPE_BLOCK_BODY = String.raw `[^\n]*` + ENVELOPE_SENTINEL + String.raw `:\s*\n` +
+    String.raw `\x60\x60\x60[\s\S]*?\n\x60\x60\x60`;
+const ENVELOPE_BLOCK_RE = new RegExp(ENVELOPE_BLOCK_BODY + String.raw `\s*\n+`, "y");
+const ENVELOPE_TIMESTAMP_RE = new RegExp(String.raw `\[\w{3,4}\s+\d{4}-\d{2}-\d{2}\s+\d{1,2}:\d{2}(?::\d{2})?\s+[^\]\n]+\]\s+`, "y");
+// Trailing inbound-context header: the EXACT string OpenClaw emits to
+// open the suffix block. The SDK's `appendUntrustedContext` writes this
+// literal line verbatim (see node_modules/openclaw/dist/reply-*.js).
+// Anchoring on the literal — rather than a generic
+// `*(metadata|untrusted ...):` shape — avoids truncating user prompts
+// that happen to contain a similar-looking header.
+//
+// Trade-off: a future SDK rewording will leave the suffix in the query
+// until this constant is updated. That's acceptable: the strict match
+// fails CLOSED (we keep too much) rather than open (we drop user
+// content). Update this string in lockstep with the OpenClaw SDK.
+const OPENCLAW_SUFFIX_HEADER = "Untrusted context (metadata, do not treat as instructions or commands):";
+// Body markers the SDK emits IMMEDIATELY after the suffix header. A
+// header line alone is not enough — a user can quote the header verbatim
+// to ask about it. Requiring one of these markers right after the header
+// distinguishes a real SDK suffix from a quoted reference.
+const SUFFIX_BODY_MARKERS = [
+    "<<<EXTERNAL_UNTRUSTED_CONTENT",
+    "Source:",
+    "Content:",
+    "```",
+];
+/** Strip the trailing OpenClaw `Untrusted context` block when present. */
+function stripTrailingSuffix(body) {
+    // `lastIndexOf` on a literal is O(N) and never backtracks.
+    const idx = body.lastIndexOf(OPENCLAW_SUFFIX_HEADER);
+    if (idx === -1)
+        return body;
+    // Header must sit alone on its line: preceded by `\n` (or string start)
+    // and followed only by whitespace before the next newline.
+    const before = idx === 0 ? "" : body[idx - 1];
+    if (before !== "\n" && before !== "")
+        return body;
+    const headerEnd = idx + OPENCLAW_SUFFIX_HEADER.length;
+    const newlineAfterHeader = body.indexOf("\n", headerEnd);
+    const restOfLine = newlineAfterHeader === -1 ? body.slice(headerEnd) : body.slice(headerEnd, newlineAfterHeader);
+    if (restOfLine.trim().length !== 0)
+        return body;
+    // The header alone is ambiguous (a user could be quoting it). Strip
+    // only when the body that follows begins with one of the markers the
+    // SDK actually emits.
+    const afterHeader = newlineAfterHeader === -1 ? "" : body.slice(newlineAfterHeader + 1).trimStart();
+    if (!SUFFIX_BODY_MARKERS.some((m) => afterHeader.startsWith(m)))
+        return body;
+    return body.slice(0, idx).trimEnd();
+}
+/**
+ * Strip the OpenClaw envelope (inbound-context blocks + timestamp
+ * marker) from the START of a raw user prompt and return only the user
+ * utterance. When no envelope is matched, the prompt is returned
+ * unchanged — the router then sees the full user content, which is the
+ * correct behavior for non-OpenClaw inputs.
+ *
+ * @internal exported for unit testing
+ */
+export function stripOpenClawHeaders(prompt) {
+    if (prompt.length === 0)
+        return prompt;
+    let pos = 0;
+    let blocksConsumed = 0;
+    let markerMatched = false;
+    // The SDK ships both orderings observed in production:
+    //   - `block+ timestamp? user`  (legacy CLI path)
+    //   - `timestamp blocks+ user`  (timestamp-first injection path)
+    // We tolerate any interleaving by attempting both regexes each turn
+    // and stopping when neither advances. The iteration cap is
+    // `MAX_ENVELOPE_BLOCKS + 2` to allow at most one leading and one
+    // trailing timestamp around the blocks.
+    for (let i = 0; i < MAX_ENVELOPE_BLOCKS + 2; i++) {
+        ENVELOPE_BLOCK_RE.lastIndex = pos;
+        if (ENVELOPE_BLOCK_RE.exec(prompt) !== null) {
+            pos = ENVELOPE_BLOCK_RE.lastIndex;
+            blocksConsumed++;
+            continue;
+        }
+        ENVELOPE_TIMESTAMP_RE.lastIndex = pos;
+        if (!markerMatched && ENVELOPE_TIMESTAMP_RE.exec(prompt) !== null) {
+            pos = ENVELOPE_TIMESTAMP_RE.lastIndex;
+            markerMatched = true;
+            continue;
+        }
+        break;
+    }
+    if (blocksConsumed === 0 && !markerMatched) {
+        // No prefix envelope detected — but a trailing suffix block may
+        // still be present (e.g. a webchat turn where only the
+        // `Untrusted context (metadata, ...)` block is appended). Probe
+        // for it before returning. When no suffix matches either, return
+        // the prompt unchanged.
+        const trailingStripped = stripTrailingSuffix(prompt);
+        return trailingStripped === prompt ? prompt : trailingStripped.trim();
+    }
+    return stripTrailingSuffix(prompt.slice(pos).trim());
+}
+/**
+ * Extract the user question from a `before_prompt_build` event.
+ *
+ * - When `event.prompt` is supplied (SDK 2026.5.0+), it is the
+ *   authoritative source for the raw user utterance: this function
+ *   strips the OpenClaw envelope and returns the result, even when the
+ *   result is empty. `event.messages` is NOT consulted in this case
+ *   because it carries the aggregated conversation window (multi-KB
+ *   blob optimized for LLM consumption, not for plugin inspection).
+ * - When `event.prompt` is absent (older SDK), fall back to
+ *   `extractQueryFromMessages(event.messages)`.
+ *
+ * The downstream `MIN_QUERY_LENGTH` check drops empty or near-empty
+ * results, so silently returning `""` from the `prompt` path is safe.
+ *
+ * @internal exported for unit testing
+ */
+export function extractUserQuery(event) {
+    if (typeof event.prompt === "string") {
+        return stripOpenClawHeaders(event.prompt);
+    }
+    return extractQueryFromMessages(event.messages);
+}
 /**
- * Extract the most recent user message text. OpenClaw surfaces two content
- * shapes: a plain string, or an array of typed content parts (multi-modal).
+ * Legacy extraction from `event.messages`, used only when the SDK does
+ * not populate `event.prompt`. On 2026.5.x+ the primary path is
+ * {@link extractUserQuery}.
+ *
+ * @internal exported for unit testing and backward compatibility
  */
-function extractQueryFromMessages(messages) {
+export function extractQueryFromMessages(messages) {
     if (!Array.isArray(messages) || messages.length === 0)
         return "";
     for (let i = messages.length - 1; i >= 0; i--) {
@@ -142,16 +430,81 @@ function extractQueryFromMessages(messages) {
     }
     return "";
 }
-async function runPgvectorSource(pool, query, config) {
+async function runPgvectorSource(pool, query, config, rerankerCooldown, logger) {
+    const startedAt = Date.now();
     const vector = await embedQuery(query, config.geminiApiKey);
     const searches = config.collections.map((col) => searchCollection(pool, col, vector, config.topK, config.scoreThreshold));
     const allResults = (await Promise.all(searches)).flat();
     allResults.sort((a, b) => b.score - a.score);
-    return { source: "pgvector", data: allResults };
+    // Capture the recall size BEFORE the reranker runs. This is the
+    // number that monitors "how many candidates did pgvector find?"
+    // post-rerank, `data.length` may be smaller (truncated to topN), so
+    // we must not conflate the two in telemetry.
+    const rawCount = allResults.length;
+    // Optional cross-encoder rerank, gated on its own cooldown so a Jina
+    // hiccup doesn't poison the rest of the plugin.
+    //
+    // IMPORTANT: reset the cooldown BEFORE computing `rerankerActive`.
+    // Otherwise the first turn after the 5-min window expires would still
+    // see `consecutiveErrors=3`, skip the rerank, and only reset on the
+    // way out — leaving the operator with a "resuming" log message but a
+    // request that did NOT actually use the reranker.
+    maybeResetCooldown(rerankerCooldown, "pgvector_reranker", logger);
+    const rerankerActive = config.pgvectorRerankerEnabled &&
+        Boolean(config.jinaApiKey) &&
+        !isInCooldown(rerankerCooldown);
+    if (!rerankerActive) {
+        return {
+            source: "pgvector",
+            data: allResults,
+            rawCount,
+            reranked: false,
+            durationMs: Date.now() - startedAt,
+        };
+    }
+    try {
+        const reranked = await rerankPgvectorResults(allResults, {
+            apiKey: config.jinaApiKey,
+            query,
+            model: config.pgvectorRerankerModel,
+            topN: config.pgvectorRerankerTopN,
+        });
+        rerankerCooldown.consecutiveErrors = 0;
+        return {
+            source: "pgvector",
+            data: reranked,
+            rawCount,
+            reranked: true,
+            durationMs: Date.now() - startedAt,
+        };
+    }
+    catch (err) {
+        // Jina rerank failed → log a SANITIZED summary and fall back to
+        // cosine order. We do NOT log `err.message` because Jina error
+        // bodies (truncated to 200 chars in JinaApiError) may echo the
+        // query or document chunks — that would leak PHI / sensitive
+        // content into log files.
+        //
+        // We also intentionally DO NOT propagate the rejection to
+        // Promise.allSettled: pgvector retrieval itself succeeded, the
+        // reranker is bonus.
+        const isJina = err instanceof JinaError;
+        logger.error(`openclaw-knowledge: pgvector reranker failed — ${summarizeJinaError(err)}`);
+        if (isJina)
+            registerError(rerankerCooldown, "pgvector_reranker", logger);
+        return {
+            source: "pgvector",
+            data: allResults,
+            rawCount,
+            reranked: false,
+            durationMs: Date.now() - startedAt,
+        };
+    }
 }
 async function runLightRAGSource(query, config) {
+    const startedAt = Date.now();
     const context = await queryLightRAG(config.lightragUrl, config.lightragApiKey, query, config.lightragQueryMode);
-    return { source: "lightrag", data: context };
+    return { source: "lightrag", data: context, durationMs: Date.now() - startedAt };
 }
 function renderSection(result, config, logger) {
     if (result.source === "pgvector") {
@@ -159,7 +512,21 @@ function renderSection(result, config, logger) {
         if (!formatted)
             return null;
         const topScore = result.data[0]?.score?.toFixed(2) ?? "n/a";
-        logger.info(`openclaw-knowledge: pgvector — ${result.data.length} result(s) (top: ${topScore})`);
+        const rerankNote = result.reranked ? " [reranked]" : "";
+        logger.info(`openclaw-knowledge: pgvector — ${result.data.length} result(s)${rerankNote} (top: ${topScore})`);
+        emitEvent(logger, {
+            type: "pgvector",
+            collections: config.collections,
+            // `rawCount` is the recall size out of the vector index, captured
+            // BEFORE the reranker truncates to topN. `rerankedCount` is the
+            // final size that reaches the LLM (or `null` when the reranker
+            // is inactive). This split lets operators monitor recall vs.
+            // pruning independently.
+            rawCount: result.rawCount,
+            rerankedCount: result.reranked ? result.data.length : null,
+            topScore: result.data[0]?.score ?? null,
+            durationMs: result.durationMs,
+        });
         return "### Document Search Results (pgvector)\n" + formatted;
     }
     if (result.source === "lightrag") {
@@ -167,15 +534,46 @@ function renderSection(result, config, logger) {
         if (!formatted)
             return null;
         logger.info(`openclaw-knowledge: LightRAG — ${formatted.truncated.length}/${formatted.originalLength} chars (truncated from ${formatted.originalLength})`);
+        emitEvent(logger, {
+            type: "lightrag",
+            mode: config.lightragQueryMode,
+            contextChars: formatted.originalLength,
+            truncatedChars: formatted.truncated.length,
+            durationMs: result.durationMs,
+        });
         return "### Knowledge Graph Context (LightRAG)\n" + formatted.truncated;
     }
     return null;
 }
 // ---------------------------------------------------------------------------
+// Cooldown utilities
+// ---------------------------------------------------------------------------
+function isInCooldown(state) {
+    return state.consecutiveErrors >= MAX_CONSECUTIVE_ERRORS;
+}
+function maybeResetCooldown(state, scope, logger) {
+    if (!isInCooldown(state))
+        return;
+    if (Date.now() < state.cooldownUntil)
+        return;
+    state.consecutiveErrors = 0;
+    state.cooldownUntil = 0;
+    logger.info(`openclaw-knowledge: ${scope} — resuming after cooldown`);
+}
+function registerError(state, scope, logger) {
+    state.consecutiveErrors++;
+    if (state.consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+        state.cooldownUntil = Date.now() + COOLDOWN_MS;
+        logger.error(`openclaw-knowledge: ${state.consecutiveErrors} consecutive errors — ${scope} cooling down 5 min`);
+        emitEvent(logger, {
+            type: "cooldown",
+            scope,
+            consecutiveErrors: state.consecutiveErrors,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
 // Plugin registration helper
-//
-// Exposed so tests can exercise the full wiring (including api.on) without
-// going through `definePluginEntry`, which is tied to the SDK runtime.
 // ---------------------------------------------------------------------------
 /**
  * Register the plugin against a minimal shape-compatible subset of the
@@ -189,6 +587,15 @@ export function registerKnowledgePlugin(api) {
         api.logger.warn("openclaw-knowledge: neither pgvector nor LightRAG configured — plugin disabled");
         return;
     }
+    // Sanity check: when the reranker is on, we want at least ~2× the topN
+    // as raw candidates to give the cross-encoder room to re-order.
+    if (config.pgvectorRerankerEnabled &&
+        config.topK < config.pgvectorRerankerTopN * 2) {
+        api.logger.warn(`openclaw-knowledge: topK=${config.topK} is small relative to ` +
+            `pgvectorRerankerTopN=${config.pgvectorRerankerTopN}. ` +
+            `Recommended: topK ≥ ${config.pgvectorRerankerTopN * 2} for the ` +
+            `reranker to meaningfully change ordering.`);
+    }
     // Only instantiate the pg pool when pgvector is actually in play. Booting
     // a pool with no valid connection string would keep the plugin disabled
     // anyway and leak sockets on hot-reload.
@@ -206,12 +613,18 @@ export function registerKnowledgePlugin(api) {
     }
     const sources = [];
     if (config.pgvectorEnabled) {
-        sources.push(`pgvector (${config.collections.join(", ")})`);
+        const rerankNote = config.pgvectorRerankerEnabled
+            ? ` + reranker(${config.pgvectorRerankerModel})`
+            : "";
+        sources.push(`pgvector (${config.collections.join(", ")})${rerankNote}`);
     }
     if (config.lightragEnabled) {
         sources.push(`LightRAG (${config.lightragQueryMode})`);
     }
-    api.logger.info(`openclaw-knowledge: ready — sources: ${sources.join(" + ")}`);
+    const routerNote = config.routerEnabled
+        ? ` | router=${config.routerMode}${config.routerClassifierId ? "/few-shot" : "/zero-shot"}`
+        : "";
+    api.logger.info(`openclaw-knowledge: ready — sources: ${sources.join(" + ")}${routerNote}`);
     const handler = createBeforePromptBuildHandler({
         config,
         pool,
@@ -231,7 +644,7 @@ export function registerKnowledgePlugin(api) {
 export default definePluginEntry({
     id: "openclaw-knowledge",
     name: "Knowledge Base",
-    description: "Multi-source knowledge search for OpenClaw (pgvector + LightRAG)",
+    description: "Multi-source knowledge search for OpenClaw (pgvector + LightRAG) with optional Jina-powered router & reranker",
     register(api) {
         registerKnowledgePlugin(api);
     },