@lacneu/openclaw-knowledge 3.2.3 → 3.2.5

package/dist/pgvector.js

@@ -54,17 +54,26 @@ export async function searchCollection(pool, collection, vector, topK, scoreThre
         .filter((row) => row.score >= scoreThreshold);
 }
 /**
- * Format pgvector results for injection into the system prompt.
- * Respects a character budget so we never blow the context window with a
- * single oversized chunk — entries are appended whole until the budget is hit.
+ * Format pgvector results for injection into the system prompt AND report
+ * how many input entries were actually included.
  *
- * Returns `null` when there is nothing useful to inject so the caller can
- * easily skip empty sections.
+ * Internal sibling of the public `formatPgvectorResults`. The public
+ * variant returns only the prompt text and is kept backward-compatible;
+ * this one exposes `injectedCount` so the plugin's render path can size
+ * the provenance report to the injected subset (contract: "emit what
+ * was injected, not what was retrieved").
+ *
+ * Returns `null` when there is nothing useful to inject (empty input OR
+ * the budget cannot fit a single entry) so the caller can skip empty
+ * sections AND skip emitting a provenance report for zero injected items.
+ *
+ * @since 3.2.5
  */
-export function formatPgvectorResults(results, maxChars) {
+export function formatPgvectorResultsDetailed(results, maxChars) {
     if (results.length === 0)
         return null;
     let output = "";
+    let injectedCount = 0;
     for (const r of results) {
         const lines = [
             `[${r.collection}] ${r.file_name ?? "unknown"} (score: ${r.score.toFixed(2)})`,
@@ -80,8 +89,29 @@ export function formatPgvectorResults(results, maxChars) {
         if (output.length + entry.length > maxChars)
             break;
         output += entry;
+        injectedCount += 1;
     }
-    return output;
+    // No entry fit the budget — equivalent to "nothing to inject" so the
+    // caller skips the header AND the provenance report. Preserves the
+    // pre-3.2.5 `if (!formatted)` semantics when output was an empty string.
+    if (injectedCount === 0)
+        return null;
+    return { output, injectedCount };
+}
+/**
+ * Format pgvector results for injection into the system prompt.
+ * Respects a character budget so we never blow the context window with a
+ * single oversized chunk — entries are appended whole until the budget is hit.
+ *
+ * Returns `null` when there is nothing useful to inject so the caller can
+ * easily skip empty sections.
+ *
+ * Public API — signature kept stable across the v3.x line. Callers needing
+ * the count of entries actually injected should use
+ * `formatPgvectorResultsDetailed` (internal to this package).
+ */
+export function formatPgvectorResults(results, maxChars) {
+    return formatPgvectorResultsDetailed(results, maxChars)?.output ?? null;
 }
 /**
  * Re-order `results` using the Jina cross-encoder reranker.
@@ -107,21 +137,44 @@ export async function rerankPgvectorResults(results, params) {
     // The reranker only sees the textual content. Empty/null texts cannot be
     // ranked, so we filter them out BEFORE the API call to avoid wasting
     // tokens on rows the cross-encoder can't score anyway.
-    const indexed = results
+    let indexed = results
         .map((r, i) => ({ row: r, originalIndex: i, text: r.text ?? "" }))
         .filter((x) => x.text.trim().length > 0);
     if (indexed.length === 0)
         return results.slice(0, params.topN ?? results.length);
+    // 3.2.4 — payload-size guards. Both are no-ops when undefined so the
+    // legacy behavior is preserved for callers that haven't migrated.
+    if (typeof params.candidatePoolMax === "number" &&
+        params.candidatePoolMax > 0 &&
+        indexed.length > params.candidatePoolMax) {
+        // `results` is already cosine-sorted by the caller (runPgvectorSource).
+        // `indexed` preserves that order via the `originalIndex` mapping, so
+        // slicing to the first N keeps the best candidates and drops the tail.
+        indexed = indexed.slice(0, params.candidatePoolMax);
+    }
+    const documents = typeof params.maxCharsPerDoc === "number" && params.maxCharsPerDoc > 0
+        ? indexed.map((x) => x.text.slice(0, params.maxCharsPerDoc))
+        : indexed.map((x) => x.text);
+    const startedAt = Date.now();
     try {
         const reranked = await rerank({
             apiKey: params.apiKey,
             query: params.query,
-            documents: indexed.map((x) => x.text),
+            documents,
             model: params.model,
             topN: params.topN,
             timeoutMs: params.timeoutMs,
             signal: params.signal,
+            rpmMonitor: params.rpmMonitor,
         });
+        if (params.onUsage) {
+            const totalChars = documents.reduce((sum, d) => sum + d.length, 0);
+            params.onUsage({
+                inputCount: documents.length,
+                totalChars,
+                durationMs: Date.now() - startedAt,
+            });
+        }
         if (reranked.length === 0) {
             // Defensive: reranker returned no usable items. Surface the original
             // cosine order rather than wiping the candidate list.

package/dist/pgvector.js.map

@@ -1 +1 @@
-{"version":3,"file":"pgvector.js","sourceRoot":"","sources":["../src/pgvector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"pgvector.js","sourceRoot":"","sources":["../src/pgvector.ts"],"names":[],"mappings":"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"}

package/dist/provenance.d.ts

@@ -0,0 +1,105 @@
+import type { PluginLogger } from "openclaw/plugin-sdk/plugin-entry";
+import type { PgvectorResult } from "./types.js";
+export type ProvenanceReportLevel = "off" | "metadata" | "full";
+export declare const PROVENANCE_REPORT_LEVELS: readonly ProvenanceReportLevel[];
+/** Gateway-scoped stream this plugin emits on (see contract §2). */
+export declare const PROVENANCE_STREAM = "openclaw-knowledge.provenance";
+/** Mirrors the consumer's per-item excerpt bound (contract §3). */
+export declare const PROVENANCE_EXCERPT_MAX_CHARS = 2000;
+/** Mirrors the consumer's per-report item cap (contract §3). */
+export declare const PROVENANCE_MAX_ITEMS = 24;
+export interface ProvenanceItemV1 {
+    id?: string;
+    type?: string;
+    date?: string;
+    score?: number;
+    text?: string;
+    file_name?: string;
+    collection?: string;
+}
+export interface ProvenanceReportV1 {
+    v: 1;
+    source: "knowledge";
+    kind: "documents";
+    injected?: {
+        chars?: number;
+        position?: string;
+        truncated?: boolean;
+    };
+    retrieval?: {
+        route?: string;
+        collections?: string[];
+        lightrag?: {
+            mode?: string;
+        };
+    };
+    items: ProvenanceItemV1[];
+}
+/** Structural emitAgentEvent surface (the installed SDK types may predate it). */
+export type EmitAgentEventFn = (event: {
+    runId: string;
+    sessionKey?: string;
+    stream: string;
+    data: unknown;
+}) => unknown;
+/** Normalize the operator's config value; anything off-list means "off". */
+export declare function resolveProvenanceLevel(raw: unknown): ProvenanceReportLevel;
+/**
+ * Feature-detect emitAgentEvent on the (first-registration) plugin api.
+ *
+ * GATEWAY QUIRK (bench-verified 2026-06-12): the agent runtime RE-REGISTERS
+ * plugins per run, and emitting through a re-registration's api is rejected
+ * `"plugin is not loaded"` — callers MUST pass the FIRST registration's api
+ * (module-level singleton; see registerKnowledgePlugin).
+ */
+export declare function resolveEmitAgentEvent(api: unknown): EmitAgentEventFn | undefined;
+/**
+ * Report for an injected pgvector section. `data` is the FINAL injected list
+ * (post-rerank, post-topN — exactly what reached the LLM). Returns null when
+ * the level is "off" or there is nothing citable.
+ */
+export declare function buildPgvectorProvenance(data: PgvectorResult[], collections: string[], level: ProvenanceReportLevel, injectedChars: number): ProvenanceReportV1 | null;
+/**
+ * Report for an injected LightRAG section. The graph response is one opaque
+ * context blob (no per-document structure yet — the docstore initiative will
+ * enrich this), so the report carries ONE item describing the injected
+ * context; "full" includes its leading excerpt VERBATIM from what was
+ * actually injected (the post-truncation text).
+ *
+ * @param injectedText  body of the section actually delivered to the LLM
+ *                      (post-truncation, header EXCLUDED). Used for the
+ *                      `full`-level excerpt.
+ * @param mode          LightRAG query mode (`mix`, `hybrid`, …).
+ * @param level         provenance gate (`off` / `metadata` / `full`).
+ * @param injectedChars total length of the system-prompt section actually
+ *                      delivered (header INCLUDED). Defaults to
+ *                      `injectedText.length` for callers that don't track
+ *                      the header separately; the plugin's render path
+ *                      passes the full section length so `injected.chars`
+ *                      reflects exactly what reached the LLM
+ *                      (codex pass #36 P3). Negative values fall back to
+ *                      `injectedText.length` to keep the report
+ *                      well-formed even on caller mistakes.
+ */
+export declare function buildLightRAGProvenance(injectedText: string, mode: string, level: ProvenanceReportLevel, injectedChars?: number): ProvenanceReportV1 | null;
+/**
+ * Stable categories logged when emission fails. Operators triage by code;
+ * the underlying gateway reason / Error message is intentionally NEVER
+ * passed to the logger because in `full` mode it may echo back the
+ * payload (excerpts of the injected documents) it was rejecting — and the
+ * tracing invariant of this module is that report content never reaches
+ * logs.
+ *
+ * @since 3.2.5 (codex pass #36 P2 — sanitize emission failure logs)
+ */
+export type ProvenanceEmitFailureCode = "plugin_not_loaded" | "missing_run_context" | "invalid_stream" | "validation_error" | "rate_limited" | "rejected" | "throw";
+/**
+ * Emit the turn's reports. Every guard degrades to SILENCE (a missing SDK
+ * function, a missing runId, a gateway rejection) — provenance must never
+ * break or delay a turn. Failures are logged as a STABLE CATEGORY CODE
+ * (never the raw gateway reason or Error message) because a silent
+ * `{emitted:false}` is undiagnosable in the field, but echoing the raw
+ * reason could leak fragments of the injected payload back into the log
+ * stream — violating the module's tracing invariant.
+ */
+export declare function emitProvenanceReports(emit: EmitAgentEventFn | undefined, logger: PluginLogger, runId: string | undefined, sessionKey: string | undefined, reports: (ProvenanceReportV1 | null)[]): void;

package/dist/provenance.js

@@ -0,0 +1,186 @@
+// Provenance reporting (provenance/v1) — what this plugin ACTUALLY injected
+// into the LLM, emitted on the gateway agent-event bus so a chat frontend
+// (openclaw-webchat) can show the user "which documents fed this reply".
+//
+// Normative contract: openclaw-webchat docs/PROVENANCE_CONTRACT.md.
+// Transport rules (gateway-enforced, bench-verified 2026-06-12):
+//   - stream MUST be scoped to this plugin: "openclaw-knowledge.provenance";
+//   - runId is REQUIRED (the before_prompt_build ctx carries it);
+//   - the gateway stamps pluginId/pluginName into `data` (authenticated
+//     emitter identity — we never claim it ourselves);
+//   - a violation returns `{emitted:false, reason}` WITHOUT throwing.
+//
+// PRIVACY: this channel is DISTINCT from the tracing events module — reports
+// land in the chat frontend's store under the chat's own ACL. The level knob
+// keeps content out unless the operator opts in:
+//   - "off"      (default): no emission at all;
+//   - "metadata": items WITHOUT text (file names, collections, scores);
+//   - "full":     plus the exact injected excerpts.
+// The tracing invariant is untouched: NOTHING here goes through logs.
+export const PROVENANCE_REPORT_LEVELS = [
+    "off",
+    "metadata",
+    "full",
+];
+/** Gateway-scoped stream this plugin emits on (see contract §2). */
+export const PROVENANCE_STREAM = "openclaw-knowledge.provenance";
+/** Mirrors the consumer's per-item excerpt bound (contract §3). */
+export const PROVENANCE_EXCERPT_MAX_CHARS = 2_000;
+/** Mirrors the consumer's per-report item cap (contract §3). */
+export const PROVENANCE_MAX_ITEMS = 24;
+/** Normalize the operator's config value; anything off-list means "off". */
+export function resolveProvenanceLevel(raw) {
+    return PROVENANCE_REPORT_LEVELS.includes(raw)
+        ? raw
+        : "off";
+}
+/**
+ * Feature-detect emitAgentEvent on the (first-registration) plugin api.
+ *
+ * GATEWAY QUIRK (bench-verified 2026-06-12): the agent runtime RE-REGISTERS
+ * plugins per run, and emitting through a re-registration's api is rejected
+ * `"plugin is not loaded"` — callers MUST pass the FIRST registration's api
+ * (module-level singleton; see registerKnowledgePlugin).
+ */
+export function resolveEmitAgentEvent(api) {
+    const candidate = api?.emitAgentEvent;
+    if (typeof candidate !== "function")
+        return undefined;
+    return candidate.bind(api);
+}
+/**
+ * Report for an injected pgvector section. `data` is the FINAL injected list
+ * (post-rerank, post-topN — exactly what reached the LLM). Returns null when
+ * the level is "off" or there is nothing citable.
+ */
+export function buildPgvectorProvenance(data, collections, level, injectedChars) {
+    if (level === "off" || data.length === 0)
+        return null;
+    const items = data
+        .slice(0, PROVENANCE_MAX_ITEMS)
+        .map((r) => {
+        const item = { collection: r.collection, score: r.score };
+        if (r.file_name)
+            item.file_name = r.file_name;
+        else if (r.file_id)
+            item.id = r.file_id;
+        if (level === "full" && r.text) {
+            item.text = r.text.slice(0, PROVENANCE_EXCERPT_MAX_CHARS);
+        }
+        return item;
+    });
+    return {
+        v: 1,
+        source: "knowledge",
+        kind: "documents",
+        injected: { chars: injectedChars, position: "system_append" },
+        retrieval: { route: "pgvector", collections },
+        items,
+    };
+}
+/**
+ * Report for an injected LightRAG section. The graph response is one opaque
+ * context blob (no per-document structure yet — the docstore initiative will
+ * enrich this), so the report carries ONE item describing the injected
+ * context; "full" includes its leading excerpt VERBATIM from what was
+ * actually injected (the post-truncation text).
+ *
+ * @param injectedText  body of the section actually delivered to the LLM
+ *                      (post-truncation, header EXCLUDED). Used for the
+ *                      `full`-level excerpt.
+ * @param mode          LightRAG query mode (`mix`, `hybrid`, …).
+ * @param level         provenance gate (`off` / `metadata` / `full`).
+ * @param injectedChars total length of the system-prompt section actually
+ *                      delivered (header INCLUDED). Defaults to
+ *                      `injectedText.length` for callers that don't track
+ *                      the header separately; the plugin's render path
+ *                      passes the full section length so `injected.chars`
+ *                      reflects exactly what reached the LLM
+ *                      (codex pass #36 P3). Negative values fall back to
+ *                      `injectedText.length` to keep the report
+ *                      well-formed even on caller mistakes.
+ */
+export function buildLightRAGProvenance(injectedText, mode, level, injectedChars) {
+    if (level === "off" || injectedText.length === 0)
+        return null;
+    const item = { id: "lightrag-context", type: mode };
+    if (level === "full") {
+        item.text = injectedText.slice(0, PROVENANCE_EXCERPT_MAX_CHARS);
+    }
+    const reportedChars = typeof injectedChars === "number" && injectedChars >= 0
+        ? injectedChars
+        : injectedText.length;
+    return {
+        v: 1,
+        source: "knowledge",
+        kind: "documents",
+        injected: { chars: reportedChars, position: "system_append" },
+        retrieval: { route: "lightrag", lightrag: { mode } },
+        items: [item],
+    };
+}
+/**
+ * Map a gateway-supplied `reason` to a stable category code. Matching is
+ * substring-based on the lower-cased reason — coarse on purpose so a
+ * future gateway wording change does not break the classifier silently.
+ * Unknown reasons collapse to `"rejected"` so the field always has a
+ * non-empty, content-free value.
+ */
+function classifyRejectionReason(reason) {
+    if (!reason)
+        return "rejected";
+    const lower = reason.toLowerCase();
+    if (lower.includes("not loaded"))
+        return "plugin_not_loaded";
+    if (lower.includes("runid") || lower.includes("session")) {
+        return "missing_run_context";
+    }
+    if (lower.includes("stream"))
+        return "invalid_stream";
+    if (lower.includes("validation") || lower.includes("schema")) {
+        return "validation_error";
+    }
+    if (lower.includes("rate") || lower.includes("limit"))
+        return "rate_limited";
+    return "rejected";
+}
+/**
+ * Emit the turn's reports. Every guard degrades to SILENCE (a missing SDK
+ * function, a missing runId, a gateway rejection) — provenance must never
+ * break or delay a turn. Failures are logged as a STABLE CATEGORY CODE
+ * (never the raw gateway reason or Error message) because a silent
+ * `{emitted:false}` is undiagnosable in the field, but echoing the raw
+ * reason could leak fragments of the injected payload back into the log
+ * stream — violating the module's tracing invariant.
+ */
+export function emitProvenanceReports(emit, logger, runId, sessionKey, reports) {
+    if (!emit)
+        return;
+    if (!runId)
+        return; // gateway-required; absent on some triggers
+    for (const report of reports) {
+        if (report === null)
+            continue;
+        try {
+            const res = emit({
+                runId,
+                ...(sessionKey ? { sessionKey } : {}),
+                stream: PROVENANCE_STREAM,
+                data: report,
+            });
+            if (res && res.emitted === false) {
+                const code = classifyRejectionReason(res.reason);
+                logger.warn(`openclaw-knowledge: provenance report rejected — ${code}`);
+            }
+        }
+        catch (err) {
+            // Log only the Error.name (`TypeError`, `RangeError`, ...) — NEVER the
+            // `.message`, which third-party libs commonly enrich with input data.
+            const name = err && typeof err === "object" && typeof err.name === "string"
+                ? err.name
+                : "Error";
+            logger.warn(`openclaw-knowledge: provenance emit failed — throw:${name}`);
+        }
+    }
+}
+//# sourceMappingURL=provenance.js.map

package/dist/provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenance.js","sourceRoot":"","sources":["../src/provenance.ts"],"names":[],"mappings":"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"}

package/dist/router/index.d.ts

@@ -1,3 +1,4 @@
+import type { RpmMonitor } from "../jina/rate-limit.js";
 import type { RouterDecision } from "./types.js";
 export interface RouterConfig {
     /** Master switch. When false, every call returns `{route: "ALL"}`. */
@@ -32,6 +33,20 @@ export interface RouterConfig {
      * Trusting only confident scores keeps the gate fail-safe.
      */
     minConfidence?: number;
+    /**
+     * Optional callback fired AFTER a successful Jina `/v1/classify` call
+     * with payload-level numbers (duration, model). The plugin uses it to
+     * emit a `jina` usage event so dashboards can track classify spend
+     * per turn independently of the router decision.
+     *
+     * @since 3.2.4
+     */
+    onClassifierUsage?: (usage: {
+        durationMs: number;
+        model: "zero-shot" | "few-shot";
+    }) => void;
+    /** Optional RPM monitor (forwarded to the Jina client). @since 3.2.4 */
+    rpmMonitor?: RpmMonitor;
 }
 /**
  * Default applied by {@link decideRoute} when a caller omits

package/dist/router/index.js

@@ -66,6 +66,7 @@ export async function decideRoute(cfg, ctx) {
         return { route: FALLBACK, reason: "classifier_fallback", score: null };
     }
     try {
+        const startedAt = Date.now();
         const outcome = cfg.classifierId
             ? await classifyFewShot({
                 apiKey: cfg.jinaApiKey,
@@ -73,13 +74,21 @@ export async function decideRoute(cfg, ctx) {
                 classifierId: cfg.classifierId,
                 expectedLabels: ROUTER_LABEL_NAMES,
                 signal: ctx.signal,
+                rpmMonitor: cfg.rpmMonitor,
             })
             : await classifyZeroShot({
                 apiKey: cfg.jinaApiKey,
                 text: ctx.query,
                 labels: (cfg.labels ?? DEFAULT_ROUTER_LABELS),
                 signal: ctx.signal,
+                rpmMonitor: cfg.rpmMonitor,
             });
+        if (cfg.onClassifierUsage) {
+            cfg.onClassifierUsage({
+                durationMs: Date.now() - startedAt,
+                model: cfg.classifierId ? "few-shot" : "zero-shot",
+            });
+        }
         if (!outcome) {
             return { route: FALLBACK, reason: "classifier_fallback", score: null };
         }

package/dist/router/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/router/index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,EAAE;AACF,2EAA2E;AAC3E,kEAAkE;AAClE,EAAE;AACF,+BAA+B;AAC/B,sEAAsE;AACtE,kDAAkD;AAClD,sEAAsE;AACtE,oEAAoE;AACpE,sEAAsE;AACtE,iDAAiD;AAEjD,OAAO,EACL,eAAe,EACf,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAoDhD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAE3C,+EAA+E;AAC/E,SAAS,eAAe,CAAC,KAAa;IACpC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACxB,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,CAAC,CAAC;IACxB,OAAO,KAAK,CAAC;AACf,CAAC;AAWD,MAAM,QAAQ,GAAU,KAAK,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,GAAiB,EACjB,GAAyB;IAEzB,mEAAmE;IACnE,oEAAoE;IACpE,uEAAuE;IACvE,MAAM,aAAa,GAAG,eAAe,CAAC,GAAG,CAAC,aAAa,IAAI,sBAAsB,CAAC,CAAC;IAEnF,0CAA0C;IAC1C,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACjB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAClE,CAAC;IAED,+CAA+C;IAC/C,MAAM,OAAO,GAAG,cAAc,CAAC;QAC7B,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,KAAK,EAAE,GAAG,CAAC,KAAK;KACjB,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI,EAAE,CAAC;QAC3B,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACvE,CAAC;IAED,4DAA4D;IAC5D,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;QAC7B,8DAA8D;QAC9D,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,qBAAqB,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzE,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC;QACpB,6DAA6D;QAC7D,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,qBAAqB,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzE,CAAC;IAED,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,GAAG,CAAC,YAAY;YAC9B,CAAC,CAAC,MAAM,eAAe,CAAC;gBACpB,MAAM,EAAE,GAAG,CAAC,UAAU;gBACtB,IAAI,EAAE,GAAG,CAAC,KAAK;gBACf,YAAY,EAAE,GAAG,CAAC,YAAY;gBAC9B,cAAc,EAAE,kBAA8B;gBAC9C,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,UAAU,EAAE,GAAG,CAAC,UAAU;aAC3B,CAAC;YACJ,CAAC,CAAC,MAAM,gBAAgB,CAAC;gBACrB,MAAM,EAAE,GAAG,CAAC,UAAU;gBACtB,IAAI,EAAE,GAAG,CAAC,KAAK;gBACf,MAAM,EAAE,CAAC,GAAG,CAAC,MAAM,IAAI,qBAAqB,CAAa;gBACzD,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,UAAU,EAAE,GAAG,CAAC,UAAU;aAC3B,CAAC,CAAC;QAEP,IAAI,GAAG,CAAC,iBAAiB,EAAE,CAAC;YAC1B,GAAG,CAAC,iBAAiB,CAAC;gBACpB,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;gBAClC,KAAK,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,WAAW;aACnD,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,qBAAqB,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QACzE,CAAC;QAED,MAAM,SAAS;QACb,uEAAuE;QACvE,+DAA+D;QAC/D,GAAG,CAAC,YAAY;YACd,CAAC,CAAC,OAAO,CAAC,KAAK;YACf,CAAC,CAAC,CAAC,qBAAqB,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;QAE9D,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7B,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,qBAAqB,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;QAClF,CAAC;QAED,iEAAiE;QACjE,kEAAkE;QAClE,mEAAmE;QACnE,kEAAkE;QAClE,kEAAkE;QAClE,+CAA+C;QAC/C,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,GAAG,aAAa,EAAE,CAAC;YAC5D,OAAO;gBACL,KAAK,EAAE,QAAQ;gBACf,MAAM,EAAE,2BAA2B;gBACnC,KAAK,EAAE,OAAO,CAAC,KAAK;aACrB,CAAC;QACJ,CAAC;QAED,OAAO;YACL,KAAK,EAAE,SAAS;YAChB,MAAM,EAAE,gBAAgB;YACxB,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,sEAAsE;QACtE,sBAAsB;QACtB,IAAI,CAAC,CAAC,GAAG,YAAY,SAAS,CAAC;YAAE,MAAM,GAAG,CAAC;QAC3C,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,kBAAkB,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACtE,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,CACL,KAAK,KAAK,MAAM;QAChB,KAAK,KAAK,eAAe;QACzB,KAAK,KAAK,eAAe;QACzB,KAAK,KAAK,KAAK,CAChB,CAAC;AACJ,CAAC"}

package/dist/tracing/events.d.ts

@@ -78,7 +78,19 @@ export interface CooldownEvent {
     scope: "global" | "router" | "pgvector_reranker";
     consecutiveErrors: number;
 }
-export type KnowledgeEvent = RouterEvent | PgvectorEvent | LightRAGEvent | JinaUsageEvent | CooldownEvent;
+/**
+ * Emitted (at most once per 60-second window) when the plugin's
+ * Jina RPM soft monitor observes the configured budget being exceeded.
+ * Pure observability — does not block any call.
+ *
+ * @since 3.2.4
+ */
+export interface JinaRpmExceededEvent {
+    type: "jina_rpm_exceeded";
+    count: number;
+    budget: number;
+}
+export type KnowledgeEvent = RouterEvent | PgvectorEvent | LightRAGEvent | JinaUsageEvent | CooldownEvent | JinaRpmExceededEvent;
 /**
  * Emit a structured event line through `logger.info`.
  *

package/dist/tracing/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/tracing/events.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,2EAA2E;AAC3E,yEAAyE;AACzE,yDAAyD;AACzD,EAAE;AACF,wEAAwE;AACxE,+DAA+D;AAC/D,wEAAwE;AACxE,+BAA+B;AAC/B,EAAE;AACF,sEAAsE;AACtE,qEAAqE;AACrE,gEAAgE;AAChE,wEAAwE;AACxE,iCAAiC;AACjC,EAAE;AACF,oEAAoE;AACpE,uEAAuE;AACvE,qEAAqE;AACrE,sEAAsE;AACtE,uEAAuE;AACvE,8DAA8D;AAC9D,EAAE;AACF,2EAA2E;AAC3E,0EAA0E;AAC1E,mBAAmB;AAcnB;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAsDhD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAG,CAAC;AAuBnD,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,MAAqB,EAAE,KAAqB;IACpE,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACtC,MAAM,CAAC,IAAI,CAAC,GAAG,YAAY,IAAI,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,4DAA4D;IAC9D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAqB,EACrB,KAAyB,EACzB,WAAmB;IAEnB,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO;IAC1B,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACzD,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,wBAAwB,EAAE,SAAS,WAAW,EAAE,CAAC,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,gDAAgD;IAClD,CAAC;AACH,CAAC"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/tracing/events.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,EAAE;AACF,2EAA2E;AAC3E,yEAAyE;AACzE,yDAAyD;AACzD,EAAE;AACF,wEAAwE;AACxE,+DAA+D;AAC/D,wEAAwE;AACxE,+BAA+B;AAC/B,EAAE;AACF,sEAAsE;AACtE,qEAAqE;AACrE,gEAAgE;AAChE,wEAAwE;AACxE,iCAAiC;AACjC,EAAE;AACF,oEAAoE;AACpE,uEAAuE;AACvE,qEAAqE;AACrE,sEAAsE;AACtE,uEAAuE;AACvE,8DAA8D;AAC9D,EAAE;AACF,2EAA2E;AAC3E,0EAA0E;AAC1E,mBAAmB;AAcnB;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAsDhD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAG,CAAC;AAqCnD,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,MAAqB,EAAE,KAAqB;IACpE,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QACtC,MAAM,CAAC,IAAI,CAAC,GAAG,YAAY,IAAI,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,4DAA4D;IAC9D,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAqB,EACrB,KAAyB,EACzB,WAAmB;IAEnB,IAAI,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO;IAC1B,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QACzD,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,wBAAwB,EAAE,SAAS,WAAW,EAAE,CAAC,CAAC;IAChF,CAAC;IAAC,MAAM,CAAC;QACP,gDAAgD;IAClD,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -39,12 +39,34 @@ export interface KnowledgePluginConfig {
     lightragMaxChars?: number;
     lightragEnabled?: boolean;
     jina?: JinaPluginConfig;
+    /**
+     * Provenance reporting toward chat frontends (provenance/v1 — see the
+     * openclaw-webchat PROVENANCE_CONTRACT): "off" (default, no emission),
+     * "metadata" (file names/collections/scores, no content), "full"
+     * (plus the exact injected excerpts).
+     *
+     * @since 3.3.0
+     */
+    provenanceReport?: string;
 }
 export interface JinaPluginConfig {
     /** Jina API key. Required for `router.mode=jina-classifier` or `pgvectorReranker.enabled`. Supports `${ENV_VAR}` substitution. */
     apiKey?: string;
     router?: RouterPluginConfig;
     pgvectorReranker?: PgvectorRerankerPluginConfig;
+    /**
+     * Soft RPM budget for ALL outbound Jina calls (router + reranker
+     * combined). When the sliding 60-second window exceeds this number,
+     * a `jina_rpm_exceeded` event is emitted (at most once per window)
+     * and a warning is logged. **The call is NEVER blocked** — the
+     * existing 429 cooldown breaker is the hard backstop.
+     *
+     * Default: 60. Set well below the Jina free-tier ceiling (100 RPM)
+     * to leave headroom for a shared key (e.g. plugin + Hindsight).
+     *
+     * @since 3.2.4
+     */
+    rpmBudget?: number;
 }
 export interface RouterPluginConfig {
     enabled?: boolean;
@@ -69,6 +91,25 @@ export interface PgvectorRerankerPluginConfig {
     model?: RerankerModel;
     /** Cap on results returned post-rerank. Default: `5`. */
     topN?: number;
+    /**
+     * Maximum number of candidate documents submitted to Jina per call.
+     * Pgvector recall is typically broad (20-50 hits) but only the top
+     * 10-15 are worth reranking. Trimming the tail saves Jina tokens
+     * linearly. Default: `20`. Set to `0` to disable the cap.
+     *
+     * @since 3.2.4
+     */
+    candidatePoolMax?: number;
+    /**
+     * Per-candidate text length cap (characters) before submission to
+     * Jina. The first ~2000 chars carry most of the relevance signal;
+     * longer chunks (transcripts, books) waste tokens on context the
+     * cross-encoder gets little additional signal from. Default: `2000`.
+     * Set to `0` to disable the truncation.
+     *
+     * @since 3.2.4
+     */
+    maxCharsPerDoc?: number;
 }
 export type LightRAGQueryMode = "naive" | "local" | "global" | "hybrid";
 /**
@@ -90,6 +131,13 @@ export interface ResolvedKnowledgeConfig {
     lightragMaxChars: number;
     lightragEnabled: boolean;
     jinaApiKey: string;
+    /**
+     * Soft RPM budget for ALL outbound Jina calls. Default: 60.
+     * `0` disables the monitor entirely.
+     *
+     * @since 3.2.4
+     */
+    jinaRpmBudget: number;
     routerEnabled: boolean;
     routerMode: "heuristic" | "jina-classifier";
     routerClassifierId: string;
@@ -102,6 +150,26 @@ export interface ResolvedKnowledgeConfig {
     pgvectorRerankerEnabled: boolean;
     pgvectorRerankerModel: RerankerModel;
     pgvectorRerankerTopN: number;
+    /**
+     * Cap on the number of candidates submitted to Jina /v1/rerank. `0`
+     * disables the cap (legacy v3.2.3 behavior). Default: `20`.
+     *
+     * @since 3.2.4
+     */
+    pgvectorRerankerCandidatePoolMax: number;
+    /**
+     * Per-candidate text truncation length in characters. `0` disables
+     * truncation. Default: `2000`.
+     *
+     * @since 3.2.4
+     */
+    pgvectorRerankerMaxCharsPerDoc: number;
+    /**
+     * Provenance reporting level (provenance/v1). Default "off".
+     *
+     * @since 3.3.0
+     */
+    provenanceReport: "off" | "metadata" | "full";
 }
 /**
  * One search hit from the PostgreSQL `knowledge_vectors` table, after score