@lacneu/openclaw-knowledge 3.1.2 → 3.2.1

package/dist/jina/reranker.js

@@ -0,0 +1,95 @@
+// Jina Reranker client.
+//
+// Wraps POST /v1/rerank for use after a pgvector cosine-similarity pass:
+// vector search returns N coarse candidates, then a cross-encoder rerank
+// promotes the ones that actually answer the query.
+//
+// Implementation choices:
+//
+// 1. **`return_documents: false` is hardcoded.** The caller (pgvector source)
+//    already owns the `PgvectorResult` objects and only needs the new
+//    ordering. Asking Jina to echo the documents back would multiply the
+//    response payload by ~10× for nothing.
+//
+// 2. **`truncate: true` by default.** Lets Jina silently shrink each document
+//    to the model's per-doc cap rather than failing the whole batch. The
+//    LightRAG-side reranker uses the same setting (`RERANK_ENABLE_CHUNKING`).
+//
+// 3. **Defensive response parsing.** We validate the structural shape
+//    (`results: [{index, score}]`) and silently skip malformed entries
+//    rather than crashing. An empty or unrecognized response yields an
+//    empty array — the caller falls back to the original cosine order.
+import { postJson } from "./client.js";
+const RERANK_URL = "https://api.jina.ai/v1/rerank";
+/**
+ * Default reranker model. v2-base-multilingual is the best-balanced choice
+ * for French-heavy corpora (LightRAG-side tuning notes from 2026-05-14 show
+ * v3 plateauing at 0.05-0.15 on short French queries vs dense chunks).
+ */
+const DEFAULT_RERANKER_MODEL = "jina-reranker-v2-base-multilingual";
+/**
+ * Rerank `documents` against `query` and return the new ordering.
+ *
+ * Each item carries the ORIGINAL index from the input array plus the new
+ * relevance score. Callers should use the `index` to look up their own
+ * data structures rather than relying on document text.
+ *
+ * @returns `[]` for an empty input (no API call) or when the response
+ *          shape is unrecognized (fail-open semantics).
+ * @throws  on network / auth / API errors so the cooldown breaker can react.
+ */
+export async function rerank({ apiKey, query, documents, model = DEFAULT_RERANKER_MODEL, topN, timeoutMs, signal, }) {
+    if (documents.length === 0)
+        return [];
+    const body = {
+        model,
+        query,
+        documents,
+        return_documents: false,
+        truncate: true,
+    };
+    if (typeof topN === "number" && topN > 0) {
+        body.top_n = topN;
+    }
+    const raw = await postJson({
+        url: RERANK_URL,
+        body,
+        apiKey,
+        timeoutMs,
+        signal,
+    });
+    return parseRerankResponse(raw, documents.length);
+}
+/**
+ * Defensive parser for the /v1/rerank response.
+ *
+ * @internal exported for unit testing
+ */
+export function parseRerankResponse(raw, inputCount) {
+    if (!isRecord(raw))
+        return [];
+    const results = raw.results;
+    if (!Array.isArray(results))
+        return [];
+    const out = [];
+    for (const item of results) {
+        if (!isRecord(item))
+            continue;
+        const index = item.index;
+        const score = item.relevance_score ?? item.score;
+        if (typeof index !== "number" ||
+            !Number.isInteger(index) ||
+            index < 0 ||
+            index >= inputCount ||
+            typeof score !== "number" ||
+            !Number.isFinite(score)) {
+            continue;
+        }
+        out.push({ index, score });
+    }
+    return out;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=reranker.js.map

package/dist/jina/reranker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.js","sourceRoot":"","sources":["../../src/jina/reranker.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB,EAAE;AACF,yEAAyE;AACzE,yEAAyE;AACzE,oDAAoD;AACpD,EAAE;AACF,0BAA0B;AAC1B,EAAE;AACF,8EAA8E;AAC9E,sEAAsE;AACtE,yEAAyE;AACzE,2CAA2C;AAC3C,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,8EAA8E;AAC9E,EAAE;AACF,sEAAsE;AACtE,uEAAuE;AACvE,uEAAuE;AACvE,uEAAuE;AAEvE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAOvC,MAAM,UAAU,GAAG,+BAA+B,CAAC;AAEnD;;;;GAIG;AACH,MAAM,sBAAsB,GAAkB,oCAAoC,CAAC;AAkBnF;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,EAC3B,MAAM,EACN,KAAK,EACL,SAAS,EACT,KAAK,GAAG,sBAAsB,EAC9B,IAAI,EACJ,SAAS,EACT,MAAM,GACO;IACb,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEtC,MAAM,IAAI,GAAsB;QAC9B,KAAK;QACL,KAAK;QACL,SAAS;QACT,gBAAgB,EAAE,KAAK;QACvB,QAAQ,EAAE,IAAI;KACf,CAAC;IACF,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,GAAG,CAAC,EAAE,CAAC;QACzC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAoB;QAC5C,GAAG,EAAE,UAAU;QACf,IAAI;QACJ,MAAM;QACN,SAAS;QACT,MAAM;KACP,CAAC,CAAC;IAEH,OAAO,mBAAmB,CAAC,GAAG,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAY,EACZ,UAAkB;IAElB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAE9B,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAC5B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvC,MAAM,GAAG,GAAmB,EAAE,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;QAC3B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YAAE,SAAS;QAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,KAAK,CAAC;QACjD,IACE,OAAO,KAAK,KAAK,QAAQ;YACzB,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;YACxB,KAAK,GAAG,CAAC;YACT,KAAK,IAAI,UAAU;YACnB,OAAO,KAAK,KAAK,QAAQ;YACzB,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EACvB,CAAC;YACD,SAAS;QACX,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/dist/jina/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Embedding model used as backbone for Classifier zero-shot requests.
+ * The Reranker endpoint uses its own model identifiers (see RerankerModel).
+ */
+export type ClassifierEmbeddingModel = "jina-embeddings-v3" | "jina-embeddings-v4" | "jina-clip-v2";
+/**
+ * Supported Jina reranker models.
+ *
+ * - `jina-reranker-v2-base-multilingual` (default in this plugin) — trained on
+ *   100+ languages, ideal for French content. Context cap: 8 192 tokens.
+ * - `jina-reranker-v3` — bigger context (131 K), primarily English-trained.
+ * - `jina-reranker-m0` — multimodal.
+ * - `jina-colbert-v2` — late-interaction.
+ */
+export type RerankerModel = "jina-reranker-v2-base-multilingual" | "jina-reranker-v3" | "jina-reranker-m0" | "jina-colbert-v2" | (string & {});
+/**
+ * Input element for the Classifier endpoint. Text-only is what the plugin
+ * uses; the API also supports `{image: "..."}` with `jina-clip-v2`, but the
+ * router never classifies images.
+ */
+export interface ClassifierTextInput {
+    text: string;
+}
+/**
+ * Zero-shot classification request body for POST /v1/classify.
+ *
+ * `labels` must contain semantic category strings (the Classifier embeds
+ * them and picks the closest one to each input). At least 2 labels.
+ */
+export interface JinaClassifyZeroShotRequest {
+    model: ClassifierEmbeddingModel;
+    input: ClassifierTextInput[];
+    labels: string[];
+}
+/**
+ * Few-shot classification request body for POST /v1/classify (with a
+ * pre-trained classifier_id obtained out-of-band — the plugin does NOT
+ * implement /v1/train; operators train via the Jina Playground or CLI and
+ * paste the ID into the plugin config).
+ */
+export interface JinaClassifyFewShotRequest {
+    classifier_id: string;
+    input: ClassifierTextInput[];
+}
+export type JinaClassifyRequest = JinaClassifyZeroShotRequest | JinaClassifyFewShotRequest;
+/**
+ * Normalized classification outcome as seen by the rest of the plugin.
+ * `label` is the picked class. `score` is the confidence in [0, 1] when
+ * Jina returns it; `null` when the field is not in the response (the
+ * defensive parser still produces a label in that case).
+ */
+export interface ClassificationOutcome {
+    label: string;
+    score: number | null;
+}
+/**
+ * Reranker request body for POST /v1/rerank.
+ *
+ * We always send `return_documents: false`: the caller already holds the
+ * original documents (PgvectorResult[]) and only needs the new ordering. This
+ * saves a meaningful chunk of egress tokens on large payloads.
+ */
+export interface JinaRerankRequest {
+    model: RerankerModel;
+    query: string;
+    documents: string[];
+    top_n?: number;
+    return_documents: false;
+    truncate?: boolean;
+}
+/**
+ * Single reranked result item — `index` references the original `documents`
+ * array position.
+ */
+export interface RerankedItem {
+    index: number;
+    score: number;
+}

package/dist/jina/types.js

@@ -0,0 +1,12 @@
+// Jina AI API request/response types.
+//
+// Documented at:
+//   https://jina.ai/classifier/   (POST /v1/classify, zero-shot + few-shot)
+//   https://jina.ai/reranker/     (POST /v1/rerank)
+//
+// We deliberately keep the response shapes flexible (`unknown`-leaning) so the
+// parser can stay defensive: Jina has changed field names between iterations
+// (e.g. `predictions[]` vs `results[]`), and a brittle interface would mask
+// silent breakage. Strong typing happens at the parser boundary.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/jina/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/jina/types.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,iBAAiB;AACjB,4EAA4E;AAC5E,oDAAoD;AACpD,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,4EAA4E;AAC5E,iEAAiE"}

package/dist/pgvector.d.ts

@@ -1,3 +1,4 @@
+import type { RerankerModel } from "./jina/types.js";
 import type { PgPoolLike, PgvectorResult } from "./types.js";
 /**
  * Search a single collection in `knowledge_vectors` using cosine similarity.
@@ -19,3 +20,31 @@ export declare function searchCollection(pool: PgPoolLike, collection: string, v
  * easily skip empty sections.
  */
 export declare function formatPgvectorResults(results: PgvectorResult[], maxChars: number): string | null;
+export interface RerankPgvectorParams {
+    apiKey: string;
+    query: string;
+    model?: RerankerModel;
+    /** Cap on the number of results returned post-rerank. */
+    topN?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Re-order `results` using the Jina cross-encoder reranker.
+ *
+ * This is the precision stage on top of pgvector's recall: the cosine pass
+ * grabs ~20 coarse candidates, the reranker promotes the ones that actually
+ * match the user's intent.
+ *
+ * Contract:
+ * - On success, returns at most `topN` items in descending relevance order.
+ *   The original cosine `score` is **preserved** on each item; the reranker
+ *   produces its own score we expose via the log event, not in the
+ *   PgvectorResult.
+ * - On any error (including auth / rate limit), throws a `JinaError`. The
+ *   caller is responsible for falling back to the original cosine order —
+ *   we do NOT swallow here because the caller wants to track the failure
+ *   for the cooldown breaker.
+ * - On empty input, returns `[]` without hitting the network.
+ */
+export declare function rerankPgvectorResults(results: PgvectorResult[], params: RerankPgvectorParams): Promise<PgvectorResult[]>;

package/dist/pgvector.js

@@ -4,6 +4,12 @@
 // `halfvec(3072)` because pgvector's HNSW implementation caps at 2000 dims
 // for the native `vector` type. Both the column cast and the query parameter
 // cast must match, otherwise the planner falls back to a sequential scan.
+//
+// As of v3.2.0, results from `searchCollection` may optionally be re-ordered
+// by a Jina cross-encoder reranker (see `rerankPgvectorResults`). The vector
+// search remains the recall stage; the reranker is the precision stage.
+import { rerank } from "./jina/reranker.js";
+import { JinaError } from "./jina/errors.js";
 const SEARCH_SQL = `SELECT file_name, mime_type, text, file_id, source, owner,
               chunk_index, total_chunks, timestamp_start, timestamp_end,
               embedded_at,
@@ -78,4 +84,66 @@ export function formatPgvectorResults(results, maxChars) {
     }
     return output;
 }
+/**
+ * Re-order `results` using the Jina cross-encoder reranker.
+ *
+ * This is the precision stage on top of pgvector's recall: the cosine pass
+ * grabs ~20 coarse candidates, the reranker promotes the ones that actually
+ * match the user's intent.
+ *
+ * Contract:
+ * - On success, returns at most `topN` items in descending relevance order.
+ *   The original cosine `score` is **preserved** on each item; the reranker
+ *   produces its own score we expose via the log event, not in the
+ *   PgvectorResult.
+ * - On any error (including auth / rate limit), throws a `JinaError`. The
+ *   caller is responsible for falling back to the original cosine order —
+ *   we do NOT swallow here because the caller wants to track the failure
+ *   for the cooldown breaker.
+ * - On empty input, returns `[]` without hitting the network.
+ */
+export async function rerankPgvectorResults(results, params) {
+    if (results.length === 0)
+        return [];
+    // 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
+        .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);
+    try {
+        const reranked = await rerank({
+            apiKey: params.apiKey,
+            query: params.query,
+            documents: indexed.map((x) => x.text),
+            model: params.model,
+            topN: params.topN,
+            timeoutMs: params.timeoutMs,
+            signal: params.signal,
+        });
+        if (reranked.length === 0) {
+            // Defensive: reranker returned no usable items. Surface the original
+            // cosine order rather than wiping the candidate list.
+            return results.slice(0, params.topN ?? results.length);
+        }
+        // Map back to PgvectorResult using the reranker's `index` (which points
+        // into our filtered `indexed` array, NOT the original `results` array).
+        const out = [];
+        for (const item of reranked) {
+            const found = indexed[item.index];
+            if (found)
+                out.push(found.row);
+        }
+        return out;
+    }
+    catch (err) {
+        // Re-throw only if it's a Jina error the caller will recognize. Any
+        // other failure (programmer error) propagates as-is.
+        if (err instanceof JinaError)
+            throw err;
+        throw err;
+    }
+}
 //# sourceMappingURL=pgvector.js.map

package/dist/pgvector.js.map

@@ -1 +1 @@
-{"version":3,"file":"pgvector.js","sourceRoot":"","sources":["../src/pgvector.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,EAAE;AACF,iEAAiE;AACjE,2EAA2E;AAC3E,6EAA6E;AAC7E,0EAA0E;AAI1E,MAAM,UAAU,GAAG;;;;;;;gBAOH,CAAC;AAEjB;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAgB,EAChB,UAAkB,EAClB,MAAgB,EAChB,IAAY,EACZ,cAAsB;IAEtB,MAAM,SAAS,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IAE1C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC;QAE3E,wEAAwE;QACxE,OAAO,MAAM,CAAC,IAAI;aACf,GAAG,CAAC,CAAC,GAAgB,EAAkB,EAAE,CAAC,CAAC;YAC1C,UAAU;YACV,KAAK,EAAE,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC;YAC5B,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,IAAI;YAChC,SAAS,EAAE,GAAG,CAAC,SAAS,IAAI,IAAI;YAChC,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,IAAI;YACtB,OAAO,EAAE,GAAG,CAAC,OAAO,IAAI,IAAI;YAC5B,MAAM,EAAE,GAAG,CAAC,MAAM,IAAI,IAAI;YAC1B,KAAK,EAAE,GAAG,CAAC,KAAK,IAAI,IAAI;YACxB,WAAW,EAAE,GAAG,CAAC,WAAW,IAAI,IAAI;YACpC,YAAY,EAAE,GAAG,CAAC,YAAY,IAAI,IAAI;YACtC,eAAe,EAAE,GAAG,CAAC,eAAe,IAAI,IAAI;YAC5C,aAAa,EAAE,GAAG,CAAC,aAAa,IAAI,IAAI;SACzC,CAAC,CAAC;aACF,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,IAAI,cAAc,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,OAAyB,EACzB,QAAgB;IAEhB,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEtC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,KAAK,GAAa;YACtB,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,SAAS,IAAI,SAAS,YAAY,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG;SAC/E,CAAC;QAEF,IAAI,CAAC,CAAC,eAAe,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,eAAe,MAAM,CAAC,CAAC,aAAa,IAAI,EAAE,EAAE,CAAC,CAAC;QACzE,CAAC;QAED,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;YACX,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACnC,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,uCAAuC;QACvD,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE/B,IAAI,MAAM,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG,QAAQ;YAAE,MAAM;QACnD,MAAM,IAAI,KAAK,CAAC;IAClB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"pgvector.js","sourceRoot":"","sources":["../src/pgvector.ts"],"names":[],"mappings":"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"}

package/dist/router/heuristic.d.ts

@@ -0,0 +1,29 @@
+import type { Route, RouterReason } from "./types.js";
+/**
+ * Triggers from the OpenClaw SDK that mean "not a user-initiated turn".
+ *
+ * Sourced from `PluginHookAgentContext.trigger` in the OpenClaw plugin SDK:
+ * `"user" | "heartbeat" | "cron" | "memory"`.
+ */
+export declare const NON_USER_TRIGGERS: Set<string>;
+export interface HeuristicInput {
+    /** The extracted user query (already trimmed and length-validated). */
+    query: string;
+    /** Trigger from `PluginHookAgentContext`. May be undefined on legacy SDKs. */
+    trigger?: string;
+    /** Whether the sender is the local CLI test harness (id: "cli"). */
+    isCli?: boolean;
+}
+export interface HeuristicVerdict {
+    route: Route | null;
+    reason: RouterReason;
+}
+/**
+ * Decide a route from cheap signals only. Returns `route: null` when the
+ * input is ambiguous and a classifier (or `ALL` fallback) should take over.
+ *
+ * The returned `reason` always identifies the rule that fired (or
+ * `"classifier_fallback"` if no rule did — yes that's reused, but a `null`
+ * route forces the caller to consult the classifier or fall back).
+ */
+export declare function heuristicRoute(input: HeuristicInput): HeuristicVerdict;

package/dist/router/heuristic.js

@@ -0,0 +1,104 @@
+// Zero-cost router heuristics.
+//
+// Runs BEFORE any Jina call. Three jobs:
+//
+//   1. **Deterministic skip on operational triggers.** When OpenClaw fires
+//      `before_prompt_build` with `ctx.trigger ∈ {heartbeat, cron, memory}`,
+//      we know the turn is not a real user question — skip retrieval
+//      unconditionally. This is the cheapest and most important gain:
+//      heartbeats fire continuously and were eating ~95% of the previous
+//      Jina quota.
+//
+//   2. **Meta-agent regex matches.** Questions like "what is your session
+//      id" or "combien d'agents ici" cannot be answered by the knowledge
+//      base, so we skip them deterministically too.
+//
+//   3. **Keyword fast-paths for common business questions.** A small set of
+//      regex hints lets the heuristic decide on its own (PGVECTOR_ONLY vs
+//      LIGHTRAG_ONLY) without paying for a Jina call. The router falls back
+//      to the classifier — or to `ALL` — when nothing matches.
+//
+// Everything in this module is pure (no I/O, no side effects) so the tests
+// can exhaustively cover the matrix.
+/**
+ * Triggers from the OpenClaw SDK that mean "not a user-initiated turn".
+ *
+ * Sourced from `PluginHookAgentContext.trigger` in the OpenClaw plugin SDK:
+ * `"user" | "heartbeat" | "cron" | "memory"`.
+ */
+export const NON_USER_TRIGGERS = new Set(["heartbeat", "cron", "memory"]);
+// ---------------------------------------------------------------------------
+// Meta-agent questions — skip entirely
+// ---------------------------------------------------------------------------
+const META_PATTERNS = [
+    // Identifiant/Id de session, session id, runId, agent id
+    /\b(?:session\s*id|runid|run\s*id|identifiant\s+(?:de\s+)?session|sessions?\s*identifi(?:ant|cation))\b/i,
+    // Combien d'agents/subagents
+    /\bcombien\s+d['e\s]?\s*(?:sub-?)?agent/i,
+    // Self-introspection "qui es-tu", "what model are you", "who are you"
+    /\b(?:qui\s+es-tu|what\s+model\s+are\s+you|who\s+are\s+you|what\s+is\s+your\s+name|comment\s+t['e]appelles?-tu)\b/i,
+    // Trivial system pings — the WHOLE prompt must be a status/ping check.
+    // Anchored on `^` so business questions ending with the word "status"
+    // (e.g. "what is the ACME project status?") are NOT classified as meta.
+    // Same anchoring for the FR variants ("tu es là ?").
+    /^\s*(?:(?:system|the\s+system)\s+)?(?:status|ping|heartbeat)\s*[?!.]*\s*$/i,
+    /^\s*(?:are\s+you\s+(?:there|alive)|t['e]es?\s+(?:la|en\s+ligne))\s*[?!.]*\s*$/i,
+];
+// ---------------------------------------------------------------------------
+// CLI test guards — short trivial prompts coming from `id:"cli"`
+// ---------------------------------------------------------------------------
+const CLI_TRIVIAL_PATTERN = /^\s*(?:test|test\s+de\s+(?:bon\s+)?fonctionnement|ping|hello|hi|salut|coucou|ok|yes|no|oui|non)\W*\s*$/i;
+// ---------------------------------------------------------------------------
+// Keyword fast-paths
+// ---------------------------------------------------------------------------
+const PGVECTOR_KEYWORDS = [
+    /\bversion\b/i,
+    /\brelease\s+notes?\b/i,
+    /\bchangelog\b/i,
+    /\bsource\s+(?:document|file|pdf|markdown)\b/i,
+    /\b\w+\.(?:md|pdf|yaml|yml|json|ts|js|py|sh)\b/i, // file name with extension
+];
+const LIGHTRAG_KEYWORDS = [
+    /\bcompare\w*\b/i,
+    /\baudit\b/i,
+    /\bsynth[éè]se\b/i,
+    /\brelations?\s+entre\b/i,
+    /\bqui\s+(?:travaille|collabore|coach|forme)\s+(?:avec|pour|chez)\b/i,
+    /\bdifferent\w*\s+(?:entre|de)\b/i,
+];
+/**
+ * Decide a route from cheap signals only. Returns `route: null` when the
+ * input is ambiguous and a classifier (or `ALL` fallback) should take over.
+ *
+ * The returned `reason` always identifies the rule that fired (or
+ * `"classifier_fallback"` if no rule did — yes that's reused, but a `null`
+ * route forces the caller to consult the classifier or fall back).
+ */
+export function heuristicRoute(input) {
+    const { query, trigger, isCli } = input;
+    // 1. Operational trigger → NEVER call any source.
+    if (trigger && NON_USER_TRIGGERS.has(trigger)) {
+        return { route: "NONE", reason: "heuristic_trigger" };
+    }
+    // 2. Meta-agent question → NEVER call any source.
+    for (const re of META_PATTERNS) {
+        if (re.test(query)) {
+            return { route: "NONE", reason: "heuristic_meta" };
+        }
+    }
+    // 3. CLI trivial prompt → NEVER call any source. Restricted to CLI to
+    //    avoid blocking legitimate-but-short collaborator questions.
+    if (isCli && CLI_TRIVIAL_PATTERN.test(query)) {
+        return { route: "NONE", reason: "heuristic_short" };
+    }
+    // 4. Keyword fast-paths.
+    if (PGVECTOR_KEYWORDS.some((re) => re.test(query))) {
+        return { route: "PGVECTOR_ONLY", reason: "heuristic_keyword" };
+    }
+    if (LIGHTRAG_KEYWORDS.some((re) => re.test(query))) {
+        return { route: "LIGHTRAG_ONLY", reason: "heuristic_keyword" };
+    }
+    // 5. Nothing fired — defer to the classifier (or fallback to ALL).
+    return { route: null, reason: "classifier_fallback" };
+}
+//# sourceMappingURL=heuristic.js.map

package/dist/router/heuristic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heuristic.js","sourceRoot":"","sources":["../../src/router/heuristic.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,EAAE;AACF,yCAAyC;AACzC,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,qEAAqE;AACrE,sEAAsE;AACtE,yEAAyE;AACzE,mBAAmB;AACnB,EAAE;AACF,0EAA0E;AAC1E,yEAAyE;AACzE,oDAAoD;AACpD,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,4EAA4E;AAC5E,+DAA+D;AAC/D,EAAE;AACF,2EAA2E;AAC3E,qCAAqC;AAIrC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE1E,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E,MAAM,aAAa,GAAa;IAC9B,yDAAyD;IACzD,yGAAyG;IACzG,6BAA6B;IAC7B,yCAAyC;IACzC,sEAAsE;IACtE,mHAAmH;IACnH,uEAAuE;IACvE,sEAAsE;IACtE,wEAAwE;IACxE,qDAAqD;IACrD,4EAA4E;IAC5E,gFAAgF;CACjF,CAAC;AAEF,8EAA8E;AAC9E,iEAAiE;AACjE,8EAA8E;AAE9E,MAAM,mBAAmB,GACvB,yGAAyG,CAAC;AAE5G,8EAA8E;AAC9E,qBAAqB;AACrB,8EAA8E;AAE9E,MAAM,iBAAiB,GAAa;IAClC,cAAc;IACd,uBAAuB;IACvB,gBAAgB;IAChB,8CAA8C;IAC9C,gDAAgD,EAAE,2BAA2B;CAC9E,CAAC;AAEF,MAAM,iBAAiB,GAAa;IAClC,iBAAiB;IACjB,YAAY;IACZ,kBAAkB;IAClB,yBAAyB;IACzB,qEAAqE;IACrE,kCAAkC;CACnC,CAAC;AAoBF;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,KAAqB;IAClD,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IAExC,kDAAkD;IAClD,IAAI,OAAO,IAAI,iBAAiB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACxD,CAAC;IAED,kDAAkD;IAClD,KAAK,MAAM,EAAE,IAAI,aAAa,EAAE,CAAC;QAC/B,IAAI,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACnB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;QACrD,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,iEAAiE;IACjE,IAAI,KAAK,IAAI,mBAAmB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IACtD,CAAC;IAED,yBAAyB;IACzB,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACnD,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACjE,CAAC;IACD,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACnD,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC;IACjE,CAAC;IAED,mEAAmE;IACnE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,qBAAqB,EAAE,CAAC;AACxD,CAAC"}

package/dist/router/index.d.ts

@@ -0,0 +1,33 @@
+import type { RouterDecision } from "./types.js";
+export interface RouterConfig {
+    /** Master switch. When false, every call returns `{route: "ALL"}`. */
+    enabled: boolean;
+    /** Which engine fills the gap when heuristics are ambiguous. */
+    mode: "heuristic" | "jina-classifier";
+    /** Jina API key — required when mode === "jina-classifier". */
+    jinaApiKey: string;
+    /**
+     * Optional few-shot classifier ID. When provided, the router calls
+     * `/v1/classify` with this ID instead of running zero-shot.
+     */
+    classifierId?: string;
+    /** Labels for zero-shot classification. Defaults to {@link DEFAULT_ROUTER_LABELS}. */
+    labels?: readonly string[];
+    /** Triggers that bypass retrieval (subset of NON_USER_TRIGGERS). */
+    skipTriggers?: readonly string[];
+}
+export interface RouterRuntimeContext {
+    query: string;
+    trigger?: string;
+    /** Whether the sender is the local CLI test harness. */
+    isCli?: boolean;
+    /** Optional AbortSignal propagated to the classifier HTTP call. */
+    signal?: AbortSignal;
+}
+/**
+ * Decide the route for one user turn.
+ *
+ * Returns a {@link RouterDecision}. The plugin caller logs `reason` and
+ * uses `route` to gate source calls.
+ */
+export declare function decideRoute(cfg: RouterConfig, ctx: RouterRuntimeContext): Promise<RouterDecision>;

package/dist/router/index.js

@@ -0,0 +1,94 @@
+// Router orchestrator: heuristic → classifier (optional) → fallback.
+//
+// Public entry point is `decideRoute(...)`. It produces a `RouterDecision`
+// the hook handler consumes to gate calls to pgvector / LightRAG.
+//
+// Design contract (fail-open):
+//   - Any error in the classifier MUST yield `ALL` so retrieval keeps
+//     working. The router never blocks the agent.
+//   - The classifier is only called when the heuristic returns `null`
+//     (ambiguous input). Heuristic hits are deterministic and free.
+//   - Classifier results that don't map to a known label fall back to
+//     `ALL` with reason `"classifier_fallback"`.
+import { classifyFewShot, classifyZeroShot, } from "../jina/classifier.js";
+import { JinaError } from "../jina/errors.js";
+import { DEFAULT_ROUTER_LABELS, ROUTER_LABEL_NAMES, extractRouteFromLabel, } from "./labels.js";
+import { heuristicRoute } from "./heuristic.js";
+const FALLBACK = "ALL";
+/**
+ * Decide the route for one user turn.
+ *
+ * Returns a {@link RouterDecision}. The plugin caller logs `reason` and
+ * uses `route` to gate source calls.
+ */
+export async function decideRoute(cfg, ctx) {
+    // 0. Disabled → preserve legacy behavior.
+    if (!cfg.enabled) {
+        return { route: "ALL", reason: "router_disabled", score: null };
+    }
+    // 1. Heuristic pass — cheap and deterministic.
+    const verdict = heuristicRoute({
+        query: ctx.query,
+        trigger: ctx.trigger,
+        isCli: ctx.isCli,
+    });
+    if (verdict.route !== null) {
+        return { route: verdict.route, reason: verdict.reason, score: null };
+    }
+    // 2. Classifier pass — only when heuristics were ambiguous.
+    if (cfg.mode === "heuristic") {
+        // Operator asked for heuristic-only routing; ambiguous → ALL.
+        return { route: FALLBACK, reason: "classifier_fallback", score: null };
+    }
+    if (!cfg.jinaApiKey) {
+        // Misconfiguration safety net — never crash, just fall back.
+        return { route: FALLBACK, reason: "classifier_fallback", score: null };
+    }
+    try {
+        const outcome = cfg.classifierId
+            ? await classifyFewShot({
+                apiKey: cfg.jinaApiKey,
+                text: ctx.query,
+                classifierId: cfg.classifierId,
+                expectedLabels: ROUTER_LABEL_NAMES,
+                signal: ctx.signal,
+            })
+            : await classifyZeroShot({
+                apiKey: cfg.jinaApiKey,
+                text: ctx.query,
+                labels: (cfg.labels ?? DEFAULT_ROUTER_LABELS),
+                signal: ctx.signal,
+            });
+        if (!outcome) {
+            return { route: FALLBACK, reason: "classifier_fallback", score: null };
+        }
+        const routeName = 
+        // Few-shot classifiers return the raw label name as trained; zero-shot
+        // returns the full descriptive label — strip the colon prefix.
+        cfg.classifierId
+            ? outcome.label
+            : (extractRouteFromLabel(outcome.label) ?? outcome.label);
+        if (!isKnownRoute(routeName)) {
+            return { route: FALLBACK, reason: "classifier_fallback", score: outcome.score };
+        }
+        return {
+            route: routeName,
+            reason: "classifier_hit",
+            score: outcome.score,
+        };
+    }
+    catch (err) {
+        // Re-throw non-Jina errors (programmer errors, type mismatches). Jina
+        // failures fail open.
+        if (!(err instanceof JinaError))
+            throw err;
+        return { route: FALLBACK, reason: "classifier_error", score: null };
+    }
+}
+function isKnownRoute(value) {
+    return (value === "NONE" ||
+        value === "PGVECTOR_ONLY" ||
+        value === "LIGHTRAG_ONLY" ||
+        value === "ALL");
+}
+//# sourceMappingURL=index.js.map

package/dist/router/index.js.map

@@ -0,0 +1 @@
+{"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;AAC9C,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AA8BhD,MAAM,QAAQ,GAAU,KAAK,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,GAAiB,EACjB,GAAyB;IAEzB,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,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;aACnB,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;aACnB,CAAC,CAAC;QAEP,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,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/router/labels.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Public constants — MUST stay in sync with `Route` in `types.js`.
+ *
+ * The label prefix passed to Jina (zero-shot) and the canonical name a
+ * few-shot classifier MUST be trained against share the same literal
+ * values as the `Route` union ("NONE" | "PGVECTOR_ONLY" | "LIGHTRAG_ONLY"
+ * | "ALL"). If they diverged, the classifier path would always fall back
+ * to "ALL" because `isKnownRoute` would reject the predicted label.
+ */
+export declare const ROUTE_NONE = "NONE";
+export declare const ROUTE_PGVECTOR_ONLY = "PGVECTOR_ONLY";
+export declare const ROUTE_LIGHTRAG_ONLY = "LIGHTRAG_ONLY";
+export declare const ROUTE_ALL = "ALL";
+/**
+ * Default labels handed to Jina `/v1/classify` in zero-shot mode when the
+ * operator does not supply a few-shot `classifierId`.
+ *
+ * Order does not matter for correctness, but we keep `NONE` first by
+ * convention so test output is stable.
+ */
+export declare const DEFAULT_ROUTER_LABELS: readonly string[];
+/**
+ * The label names that the classifier may legitimately return.
+ * Used by the defensive parser to refuse hallucinated classes.
+ */
+export declare const ROUTER_LABEL_NAMES: readonly string[];
+/**
+ * Extract the route name from a full label string (the part before the
+ * colon). Returns `null` when the label is malformed.
+ *
+ * @internal exported for unit testing
+ */
+export declare function extractRouteFromLabel(label: string): string | null;