@dsh-edge/dsh-edge-agent 0.0.0-stage → 0.1.1

package/lib/dsh-adapter/intent-router.d.ts

@@ -0,0 +1,710 @@
+/**
+ * intent-router — LLM-based intent classification.
+ *
+ * Uses the local Qwen3-4B (via ctx.llm) to classify user messages as
+ * LOCAL (file ops, device control, calculations) or CLOUD (knowledge,
+ * chat, creative tasks). Falls back to keyword rules when the LLM
+ * call fails (timeout, network error, unclear response).
+ *
+ * @module dsh-edge-agent/intent-router
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { Service } from '@deepseek-ai/cordis';
+import Schema from '@deepseek-ai/schemastery';
+export declare const name = "intent-router";
+export declare const inject: readonly ["llm", "auditLog", "privacyPolicy"];
+/** Minimal interface our router needs from the audit-log service. */
+interface AuditLike {
+    log(entry: {
+        level: 'debug' | 'info' | 'warn' | 'error' | 'security';
+        kind: string;
+        source: string;
+        payload: Record<string, unknown>;
+    }): Promise<unknown>;
+}
+/**
+ * §7.122: 端点是否落在本机。
+ *
+ * provider 名（`local-llm`）**不代表**落点 —— config/edge.json 的
+ * `llm.local.baseUrl` 可以是任何地址，包括公网。operator 要判断
+ * 「这轮原文有没有出网」，看的是落点，不是名字。
+ *
+ * §7.130: 主人裁决——「是否出网」的判据是 **category（哪个池）**，不是端点
+ * 落在哪台机。本函数仍然有用（§7.122 的分类器落点披露是备查信息），但它
+ * **不参与出网判断**：local 池是 operator 自有设施，端点不在本机也不算出网。
+ */
+export declare function isLoopbackEndpoint(endpoint: string | undefined): boolean;
+export interface Config {
+    /** Default realm when classification finds no rule. */
+    defaultCategory: 'LOCAL' | 'CLOUD' | 'SANITIZED';
+    /** Provider to use for intent classification. */
+    classificationProvider: string;
+    /** Model id passed alongside `classificationProvider`. */
+    classificationModel: string;
+    /** Minimum confidence the LLM must express to be trusted.
+     *  Below this value, the router falls back to keyword rules
+     *  (fail-open, not REJECT — see Phase B plan). */
+    confidenceThreshold: number;
+    /** §7.115 (2026-10-25): decision-model-only mode — false = the LLM
+     *  classifier never runs; a jev skip goes straight to the rules tier +
+     *  default LOCAL (fail-closed). Default true. */
+    llmFallback?: boolean;
+    /** Hard cap on a single classify() LLM call. The AbortController fires
+     *  this many ms after the stream starts; on timeout the call throws
+     *  and the caller falls through to the keyword/default path (fail-open).
+     *  Default 4000ms; env DSH_EDGE_INTENT_LLM_TIMEOUT_MS overrides. */
+    llmTimeoutMs?: number;
+    /** Max number of recent messages to embed as multi-turn context.
+     *  0 disables context. Default 3. */
+    recentMessagesLimit?: number;
+    /** Hard cap on input text length. Past this, the router truncates the
+     *  prompt input and audits `intent.classify.truncated`. Default 2000;
+     *  env DSH_EDGE_INTENT_MAX_INPUT overrides. Defense-in-depth against
+     *  pathologically long prompts overwhelming qwen3-4b. */
+    maxInputLength?: number;
+    /** Last-resort LOCAL-keyword list used only when privacy-policy is absent
+     *  or has no matching rule. Default ships EN + CN. Override via env
+     *  DSH_EDGE_INTENT_FALLBACK_KEYWORDS (comma-separated) to add JA / KO /
+     *  ES / domain-specific terms without editing source. Replaces the
+     *  built-in list entirely when set. */
+    fallbackKeywords?: string[];
+    /** §7.47 (2026-09-12): CLOUD-keyword list matched BEFORE fallbackKeywords.
+     *  Catches queries that obviously need web/search/online info (新闻/news/
+     *  搜索/search/latest/最新/today/今天) and routes them to cloud LLM +
+     *  web tools — without waiting for the LLM classifier (which can hang
+     *  on Qwen3-4B). Default ships EN + CN built-in list. Override via env
+     *  DSH_EDGE_INTENT_CLOUD_KEYWORDS (comma-sep) — appended to built-in.
+     *  §7.108: the policy file's stages.intent.cloudKeywords ALSO appends
+     *  (hot-reloadable) — preferred operator surface. */
+    cloudKeywords?: string[];
+    /** §7.58 (2026-09-16): LOCAL-entity list (密盒/ets/etscli built-in)
+     *  matched before every keyword layer and used to override a non-LOCAL
+     *  LLM verdict. Env DSH_EDGE_INTENT_LOCAL_ENTITIES (comma-sep) appends to
+     *  built-in (NOT replaces), same semantics as cloudKeywords. §7.108:
+     *  policy-file stages.intent.localEntities also appends (hot-reloadable). */
+    localEntities?: string[];
+    /** §7.124 (2026-10-27): 家庭设备操作正则层的扩展词表（追加到内置词表）。 */
+    deviceCommands?: {
+        devices?: string[];
+        actions?: string[];
+    };
+    /** §7.92.3 (2026-09-23) + §7.92.5 (2026-09-23): jev HTTP intent
+     *  recognizer (port 8001). Toggle — default OFF (opt-in). When ON,
+     *  jev runs BEFORE the LLM classifier and short-circuits high-
+     *  confidence / low-risk verdicts. See
+     *  ~/work/jev-branch/docs/api_reference.md for the upstream contract.
+     *  §7.92.5 splits the full categories[] taxonomy into ≤16-intent
+     *  batches (jev v0.3.0 hard cap) and fires them concurrently via
+     *  Promise.all. Env DSH_EDGE_INTENT_JEV_ENABLED (literal 'true' activates). */
+    jevEnabled?: boolean;
+    /** §7.92.3: jev base URL. Env DSH_EDGE_INTENT_JEV_URL. */
+    jevUrl?: string;
+    /** §7.112 (2026-10-25): jev backend kind. 'local' = the ONNX /predict
+     *  contract (default); 'bailian-decision' = Alibaba's decision-model
+     *  /systemone structured-decision interface — one call carries the whole
+     *  taxonomy as choice/score questions (no 16-intent cap, no chitchat
+     *  markers). Env DSH_EDGE_INTENT_JEV_PROVIDER. */
+    jevProvider?: 'local' | 'bailian-decision';
+    /** §7.112: decision-model id (bailian-decision only, e.g.
+     *  'decision-model-preview'). Env DSH_EDGE_INTENT_JEV_MODEL. */
+    jevModel?: string;
+    /** §7.112: literal Authorization key (edge.json jev.apiKeyRef →
+     *  secrets.*). Bailian MaaS requires it; local ONNX never did. */
+    jevApiKey?: string;
+    /** §7.112: 'raw' = `Authorization: <key>` (org systemone examples);
+     *  'bearer' = `Authorization: Bearer <key>` (compatible-mode
+     *  convention). Default 'raw'. */
+    jevAuthScheme?: 'raw' | 'bearer';
+    /** §7.114 (2026-10-25): classify path appended to jevUrl. '/systemone'
+     *  (default) = the MaaS deployments; a local MLX serve of the same
+     *  contract exposes '/v1/classify' — point jevUrl at its /v1 root and
+     *  set '/classify'. The decision model is a config-file-bound EXTERNAL
+     *  service: url/path/model/key all live in edge.json, zero hardcoding. */
+    jevPath?: string;
+    /** §7.115: directional confidence gate — a LOCAL-leaning decision-model
+     *  verdict adopts at this floor (default 0.5) instead of paying the LLM
+     *  round-trip for a second opinion; non-LOCAL (data may leave the device)
+     *  keeps the strict jevConfidenceThreshold. */
+    jevLocalAdoptFloor?: number;
+    /** §7.92.3: per-batch jev HTTP timeout in ms (applies to EACH batch
+     *  fired by the §7.92.5 orchestrator). Env DSH_EDGE_INTENT_JEV_TIMEOUT_MS. */
+    jevTimeoutMs?: number;
+    /** §7.92.3: minimum jev confidence to adopt. Below → fall through to
+     *  LLM. Env DSH_EDGE_INTENT_JEV_CONFIDENCE_THRESHOLD. */
+    jevConfidenceThreshold?: number;
+    /** §7.92.3: jev risk_score gate (≥ this value → REJECT). Env
+     *  DSH_EDGE_INTENT_JEV_RISK_THRESHOLD. */
+    jevRiskThreshold?: number;
+    /** §7.92.6 (2026-09-24): circuit-breaker TTL (ms). When all 3
+     *  jev batches fail (transport / parse / timeout) within one
+     *  classify() call, the breaker opens and subsequent classify()
+     *  calls skip jev entirely until TTL elapses. Any successful batch
+     * (HTTP 2xx + parse OK, even if action='fallback_llm') closes the
+     *  breaker immediately. Env DSH_EDGE_INTENT_JEV_BREAKER_TTL_MS. */
+    jevBreakerTtlMs?: number;
+    /** §7.92.7 (2026-09-24): boot-time `/health` probe (toggle). When
+     *  true, the service fires a single GET `${jevUrl}/health` (timeout
+     *  = `jevBootProbeTimeoutMs`, default 2000ms) at `apply()` time. On
+     *  non-2xx / network error / timeout the breaker is **pre-opened**
+     *  with full TTL — first classify() short-circuits without paying
+     *  the ~3 × jevTimeoutMs wall-clock. Default ON; operators set
+     *  false to skip the probe (e.g. when jev boots lazily alongside
+     *  dsh-edge and is reliably up by the time chat starts). Env
+     *  DSH_EDGE_INTENT_JEV_BOOT_PROBE_ENABLED. */
+    jevBootProbeEnabled?: boolean;
+    /** §7.92.7: boot probe timeout (ms). Smaller than `jevTimeoutMs`
+     *  (which is per-batch for classify-time use). Env
+     *  DSH_EDGE_INTENT_JEV_BOOT_PROBE_TIMEOUT_MS. */
+    jevBootProbeTimeoutMs?: number;
+    /** §7.92.7: interval (ms) between breaker-open `/health` probes.
+     *  While the breaker is open, a setInterval pings `/health` every
+     *  N ms (timeout = `jevProbeTimeoutMs`). On 2xx the breaker closes
+     *  immediately (recovery can be faster than waiting for full TTL).
+     *  Default 5000ms — frequent enough that recovery feels snappy,
+     *  infrequent enough to avoid hammering a sick jev. Env
+     *  DSH_EDGE_INTENT_JEV_BREAKER_PROBE_MS. */
+    jevBreakerProbeMs?: number;
+    /** §7.92.7: periodic probe timeout (ms). Smaller than `jevTimeoutMs`
+     *  — we want fast fail on a sick jev rather than waiting the full
+     *  classify-time budget. Env DSH_EDGE_INTENT_JEV_PROBE_TIMEOUT_MS. */
+    jevProbeTimeoutMs?: number;
+    /** §7.92.3 (2026-09-23): intent category specs (LOCAL/CLOUD/SANITIZED/
+     *  REJECT descriptions + jev intent lists). Loaded from
+     *  `ctx.privacyPolicy.getCategories()` at construction. When set, used
+     *  as-is (test override path); when absent AND privacyPolicy is missing,
+     *  falls back to a hardcoded built-in. Same shape as
+     *  privacy-policy.json#categories: array of {id, description,
+     *  examples?, jevIntents[]}. Operators extend by editing
+     *  config/privacy-policy.json (hot-reload picks it up via
+     *  `policy/loaded` event); no env var override. */
+    categories?: import('./privacy-policy.js').IntentCategory[];
+}
+export declare const Config: Schema<Config>;
+export interface Intent {
+    category: 'LOCAL' | 'CLOUD' | 'SANITIZED' | 'REJECT';
+    confidence: number;
+    targetRealm: string;
+    rationale: string;
+    /**
+     * §7.123 (2026-10-27): provenance of `confidence`.
+     *
+     * `false` means "this number is a PLACEHOLDER, not a reported confidence"
+     * — today only the bailian decision-model path produces it: the backend
+     * returns a `choice` without a numeric confidence, so the decoder
+     * substitutes a synthetic 0.9 ("decisive-by-construction"). A synthetic
+     * value must not be able to satisfy an operator's *semantic trust*
+     * threshold (stages.intent.semanticCloudMinConfidence), because the
+     * operator is trusting a measurement that does not exist.
+     *
+     * `undefined` = reported (the normal case: LLM classifier, local ONNX
+     * jev, rules tier). Only `false` disables the semantic unlock.
+     */
+    confidenceReported?: boolean;
+}
+export interface IntentRouterService {
+    classify(text: string, context?: {
+        recentMessages?: unknown[];
+        sessionId?: string;
+    }): Promise<Intent>;
+    /**
+     * §7.107: does this text ask for PUBLIC-WEB information?
+     *
+     * The operator's ruling: the cloud LLM is only for "需要搜索公网上的信息".
+     * This is the signal that unlocks the cloud — a CLOUD verdict from any
+     * other tier (a confident local classifier, a caller route) is honoured
+     * only when this returns a keyword.
+     *
+     * The keyword list is the same one the rules tier uses (built-in
+     * information-acquisition words + `stages.intent.cloudKeywords`), so the
+     * gate and the rules tier can never disagree about what counts as a
+     * web need.
+     */
+    cloudSignal(text: string): string | undefined;
+    resolve(intent: Intent): {
+        realm: string;
+        config: Record<string, unknown>;
+    };
+    /** Snapshot of in-memory counters. O(1) read for ops dashboards. */
+    getStats(): IntentRouterStats;
+}
+/** Built-in last-resort LOCAL keyword list (EN + CN). Used only when
+ *  privacy-policy is absent / empty AND `config.fallbackKeywords` is unset.
+ *  Users override via env `DSH_EDGE_INTENT_FALLBACK_KEYWORDS` (comma-sep).
+ *
+ *  §7.123 (2026-10-27): moved to `./intent-signals.ts` — the strategy DATA
+ *  (keyword tables, entity tables, the fallback taxonomy) now lives apart
+ *  from the decision LOGIC in this file. */
+import { LOCAL_KEYWORDS_DEFAULT, CLOUD_KEYWORDS_DEFAULT, LOCAL_ENTITY_KEYWORDS_DEFAULT, JEV_MAX_INTENTS, CATEGORIES_FALLBACK, RULE_CATEGORIES } from './intent-signals.js';
+export { LOCAL_KEYWORDS_DEFAULT, CLOUD_KEYWORDS_DEFAULT, LOCAL_ENTITY_KEYWORDS_DEFAULT, JEV_MAX_INTENTS, CATEGORIES_FALLBACK, RULE_CATEGORIES, };
+export declare class IntentRouterServiceImpl extends Service {
+    private readonly defaultCategory;
+    private readonly classificationProvider;
+    private readonly classificationModel;
+    private readonly confidenceThreshold;
+    private readonly llmFallback;
+    private readonly llmTimeoutMs;
+    private readonly recentMessagesLimit;
+    private readonly maxInputLength;
+    private readonly fallbackKeywords;
+    /** §7.47 (2026-09-12): CLOUD keyword list, merged with built-in defaults.
+     *  Matched in classifyWithRules BEFORE fallbackKeywords. */
+    private readonly cloudKeywords;
+    /** §7.58 (2026-09-16): LOCAL-entity list, merged with built-in defaults.
+     *  Checked FIRST in classifyWithRules + as LLM-verdict override guardrail. */
+    private readonly localEntities;
+    /** §7.124: operator-extended device-command terms (ADDITIVE on top of the
+     * built-in vocabulary in ./intent-signals.ts). */
+    private readonly deviceCommandOverrides;
+    /** §7.92.3 (2026-09-23): jev HTTP intent recognizer (toggle). When
+     *  true, classify() invokes classifyWithJev() BEFORE classifyWithLlm(). */
+    private readonly jevEnabled;
+    /** §7.92.3: jev base URL, e.g. `http://127.0.0.1:8001`. */
+    private readonly jevUrl;
+    /** §7.112: Bailian decision-model backend surface (see Config docs). */
+    private readonly jevProvider;
+    private readonly jevModel;
+    private readonly jevApiKey;
+    private readonly jevAuthScheme;
+    private readonly jevPath;
+    private readonly jevLocalAdoptFloor;
+    /** §7.92.3: jev fetch timeout (ms). */
+    private readonly jevTimeoutMs;
+    /** §7.92.3: min jev confidence to adopt (else fall through to LLM). */
+    private readonly jevConfidenceThreshold;
+    /** §7.92.3: jev risk_score gate (>= this → REJECT). */
+    private readonly jevRiskThreshold;
+    /** §7.92.6 (2026-09-24): circuit-breaker TTL (ms). When all 3
+     *  batches fail, set `jevBreakerOpenUntil = Date.now() + ttl` and
+     *  classify() short-circuits jev (zero fetch) until that timestamp.
+     *  Any successful batch closes the breaker (sets to 0). */
+    private readonly jevBreakerTtlMs;
+    /** §7.92.6: ms-epoch timestamp until which the breaker is open.
+     *  0 = closed. Mutable; reset on every Promise.all settle. */
+    private jevBreakerOpenUntil;
+    /** §7.92.7: boot probe toggle. When true, `start()` fires one
+     *  `GET ${jevUrl}/health` and pre-opens the breaker on failure. */
+    private readonly jevBootProbeEnabled;
+    /** §7.92.7: boot probe timeout (ms). */
+    private readonly jevBootProbeTimeoutMs;
+    /** §7.92.7: interval between breaker-open `/health` probes (ms).
+     *  Only active while the breaker is open. */
+    private readonly jevBreakerProbeMs;
+    /** §7.92.7: periodic probe timeout (ms). */
+    private readonly jevProbeTimeoutMs;
+    /** §7.92.7: setInterval handle for the periodic recovery probe.
+     *  null = no timer running (breaker closed or probe disabled). */
+    private jevBreakerProbeTimer;
+    /** §7.92.7: in-flight boot probe promise. Tracked so a test or
+     *  shutdown hook can `await stop()` without leaving a dangling
+     *  fetch racing the constructor's first classify() call. */
+    private jevBootProbePromise;
+    /** §7.92.3 (2026-09-23) + §7.108 (2026-10-24): categories spec — loaded
+     *  from privacyPolicy.getCategories() at construction AND refreshed on
+     *  every `policy/loaded` event when the spec came from the policy
+     *  service (config.categories keeps its explicit-override semantics and
+     *  is never refreshed). Drives both the LLM prompt (description field
+     *  per category) AND the jev-intent → category lookup (jevIntents[] per
+     *  category, flattened into jevIntentMap). Tests inject via
+     *  `config.categories` to bypass privacy-policy. */
+    private categories;
+    /** §7.92.3: flat jev-intent-string → category lookup, derived from
+     *  `this.categories[].jevIntents`. Rebuilt together with categories on
+     *  policy hot-reload (§7.108). */
+    private jevIntentMap;
+    private readonly llm;
+    private readonly auditLog;
+    /** ── classify() 结果缓存（LRU + TTL）───────────────────────────────
+     *  只缓存"贵的"路径的最终 verdict（LLM 采纳 / jev 采纳，均过
+     *  gateCloudVerdict）；规则兜底、policy REJECT、jev-reject 都很便宜
+     *  且依赖可热重载的状态，不缓存。没有 in-flight 合并 —— 并发同文本
+     *  各自走 LLM（保持并发计数语义），只有"完成后"的重复才命中。
+     *  verdict 对同一文本是确定性的（gate 也是纯文本判定），TTL 只为
+     *  让关键词表/策略热重载后的新判定尽快生效。 */
+    private static readonly CLASSIFY_CACHE_TTL_MS;
+    private static readonly CLASSIFY_CACHE_MAX;
+    private readonly classifyCache;
+    private classifyCacheKey;
+    private classifyCacheGet;
+    private classifyCacheSet;
+    private readonly stats;
+    constructor(ctx: Context, config: Config, auditLog?: AuditLike);
+    /**
+     * Soft service lookup that works in both Cordis (runtime) and unit tests (bare mock).
+     *
+     * Cordis context: `ctx.get(name)` is available — use it. Throws when the
+     * service is not in the `inject` list, so `get` acts as the gate.
+     * Bare mock context (tests): `ctx.get` is undefined — fall back to direct
+     * property access `ctx[name]`, which is how tests wire fake services.
+     *
+     * Either way, a missing service returns `undefined` rather than throwing.
+     */
+    private softService;
+    private audit;
+    /**
+     * §7.133: jev 决策模型调用的 trace。
+     *
+     * jev 走的是**裸 fetch**，不经过 `ctx.llm` —— 所以 adapter 那条路看不到
+     * 它。而它恰恰是把用户原文送出设备的那一call（当前配置指向百炼云端
+     * decision-model，§7.112/§7.114）。面板若只显示 local-llm 的分类器调用，
+     * 就是在显示一件没发生过的事（§7.107 的诚实性纪律）。
+     *
+     * 所以这里补一路 trace：caller 仍是 `intent-classifier`（它就是意图
+     * 分类器），provider 用 `bailian-decision` / `jev` 区分是哪条后端。
+     */
+    private traceJevRequest;
+    private traceJevResponse;
+    private emitJevTrace;
+    /**
+     * §7.122: 分类器 provider 的**真实落点**。
+     *
+     * provider 名（`local-llm`）不等于落点 —— config/edge.json 的
+     * `llm.local.baseUrl` 可以指向公网。审计要能回答「这轮原文发到哪去了」，
+     * 光有 provider 名不够。
+     *
+     * 解析规则：provider 以 `cloud-` 开头 → cloud 池；否则 local 池。
+     * （与 model-router 的 realm 判定同一口径：`local-*` 前缀 = LOCAL 域，
+     * 其余按 CLOUD 处理。）
+     */
+    private classifierEndpoint;
+    /** §7.113 (2026-10-25): the two evidence scalars the Edge tab renders
+     *  beside the verdict — `keyword` = the regex keyword/entity the rules
+     *  layer matched (derived from the rationale; empty for semantic
+     *  verdicts), `semantic` = the chosen category's description sentence,
+     *  i.e. the "why" the LLM/jev classifier answered with. Both are plain
+     *  scalars so safePayload passes them (PII-scanned) to the intent panel. */
+    private classifyEvidence;
+    /** Redact PII from a short preview string before logging. Soft-dep on
+     *  ctx.piiUtils.redactString. Returns `null` (rather than leaking) if
+     *  redaction is unavailable — callers should log length-only in that case.
+     *  Defense-in-depth: audit-log already runs redactObject on every payload,
+     *  but router-level redaction survives audit-log misconfiguration. */
+    private redactPreview;
+    /**
+     * §7.107 (2026-10-23, operator ruling「只有需要搜索公网上的信息才需要用到
+     * cloudllm」): a CLOUD verdict needs a public-web need.
+     *
+   * The signal is this router's own cloud keyword list (built-in
+   * information-acquisition words + `stages.intent.cloudKeywords` + the
+   * policy file's `stages.intent.cloudKeywords`, §7.108) — the same list the
+   * rules tier matches, so the gate and the rules tier can never disagree
+   * about what counts as a web need.
+     *
+     * The gate is applied to the LLM / jev verdicts ONLY:
+     *   - the rules tier reaches CLOUD either through a privacy-policy rule
+     *     (the operator's own statement — honoured as-is) or through a cloud
+     *     keyword (which IS the signal);
+     *   - the LLM/jev verdicts are a MODEL's opinion, and a model's opinion
+     *     is not what decides whether text may leave the device.
+     *
+     * It lives HERE — at the source of the verdict — and not in the
+     * consumer: the verdict is read by two consumers, input-guard
+     * (agent/pre-step) and http-api (which writes `agent._edgeRoute` from it
+     * and hands that over as an EXPLICIT route that input-guard honours
+     * as-is). A gate in the consumer closed only the input-guard path.
+     */
+    private gateCloudVerdict;
+    classify(text: string, context?: {
+        recentMessages?: unknown[];
+        sessionId?: string;
+    }): Promise<Intent>;
+    /** §7.92.5 (2026-09-23): build the full jev `intents[]` payload from
+     *  `this.categories[]`. Two-phase priority, NO 16-cap (the cap is
+     *  enforced one level up by `chunkIntents()`):
+     *
+     *    Phase 1: emit every REJECT category's jevIntents first
+     *             (security priority — must not be dropped)
+     *    Phase 2: emit all other categories in `categories[]` config order
+     *             (LOCAL → CLOUD → SANITIZED by default)
+     *
+     *  Dedup by name via a Set<string> so operators who accidentally list
+     *  the same intent in two categories don't produce a duplicate name
+     *  (which would confuse jev's own zero-shot classifier).
+     *
+     *  Returns the un-truncated array — the orchestrator batches it. */
+    private buildJevIntentsPayload;
+    /** §7.92.5 (2026-09-23): single-batch jev fetcher. Extracted from
+     *  the old monolithic `classifyWithJev()` so the orchestrator can
+     *  fire N concurrent calls via `Promise.all` and merge the results.
+     *
+     *  Takes the same `text` + `sessionId` as the old function, plus an
+     *  already-≤16 `intents[]` slice and `chitchatIntents` (defensive
+     *  marker for jev v0.3.0+). Returns the same shape:
+     *  - `action: 'reject' | 'adopt' | 'skip'`
+     *  - `confidence` / `riskScore` / `latencyMs` (always set)
+     *  - `skipReason` when action='skip' — caller can tell whether to
+     *    retry the verdict on the next batch (we don't — we just merge)
+     *
+     *  Every audit / counter side-effect for THIS batch fires here, not
+     *  in the orchestrator, so partial failures are observable per-batch
+     *  in the JSONL audit stream. */
+    private fetchJevBatch;
+    /** §7.92.5 (2026-09-23): jev HTTP prefilter — batched orchestrator.
+     *  Splits the full `categories[].jevIntents[]` payload into ≤16-size
+     *  batches (jev v0.3.0 hard cap from `head_max_len=256`), fires all
+     *  batches concurrently via `Promise.all`, and merges the verdicts
+     *  with a max-confidence pick:
+     *
+     *    1. Any `reject` action → pick highest `riskScore` (security signal)
+     *    2. Else any `adopt` action → pick highest `confidence`; tie-break
+     *       by earlier batch index (REJECT-priority intents live in
+     *       batch 0, so the security-first ordering is preserved on ties)
+     *    3. Else all skipped → return the first skip result
+     *
+     *  Returns one of:
+     *  - `action: 'reject'`  → `risk_score >= jevRiskThreshold` (security-level)
+     *  - `action: 'adopt'`   → `data.action === 'execute'`, confidence ≥
+     *                           threshold, intent string found in jevIntentMap
+     *                           (mapped to realm)
+     *  - `action: 'skip'`    → any other condition (low-conf, fallback_llm,
+     *                           unrecognized intent, transport / parse error).
+     *                           Caller falls through to classifyWithLlm.
+     *
+     *  Failure handling: every per-batch error path (timeout, network,
+     *  parse) is audited at warn level and produces `action: 'skip'` for
+     *  THAT batch — jev being unavailable MUST NOT degrade the existing
+     *  LLM classification path. This is the same fail-open contract used
+     *  by classifyWithLlm's classifyWithRules fallback.
+     *
+     *  See ~/work/jev-branch/docs/api_reference.md for the wire spec.
+     *  Implementation notes:
+     *  - Uses global `fetch` (Node ≥18). AbortSignal for timeout.
+     *  - No auth header — jev is local-network by design.
+     *  - `metadata.session_id` for cross-service trace correlation.
+     *  - `lang` hardcoded 'zh' (we don't auto-detect; the operator's UI
+     *    can pass it later if multilingual queries become common). */
+    /** §7.112: headers for every jev HTTP surface (predict / health /
+     *  systemone). Content-Type always; Authorization only when a key is
+     *  configured — Bailian MaaS requires it, the local ONNX service never
+     *  did. */
+    private jevHeaders;
+    /** §7.112 (2026-10-25): Bailian decision-model backend for the jev stage.
+     *
+     *  One POST `${jevUrl}/systemone` replaces the batched /predict flow:
+     *  the structured-decision interface carries the whole taxonomy at once —
+     *    questions.intent = choice over categories (criteria = id → description)
+     *    questions.risk    = score over 4 danger levels (→ risk_score 0..1)
+     *  so there is no 16-intent cap and no chitchat markers. Confidence/risk
+     *  gates, breaker semantics and audit rows mirror the local flow so
+     *  classify() cannot tell the backends apart. */
+    private classifyWithBailianDecision;
+    private classifyWithJev;
+    private classifyWithLlm;
+    /** §7.58 (2026-09-16): match a LOCAL-entity keyword. CJK entries are
+     *  substring matches; ASCII entries require non-alphanumeric boundaries
+     *  (so 'ets' never fires inside "assets"/"settings"). Returns the matched
+     *  (lower-cased) keyword, or undefined. */
+    private matchLocalEntity;
+    /** §7.108 (2026-10-24): the policy file's stages.intent signal tables,
+     *  read LIVE on every classify so a policy hot-reload takes effect on
+     *  the next turn. Missing service / old policy → undefined (callers
+     *  fall back to the constructor-built lists). */
+    private policyIntentStages;
+    /** §7.108: the FULL cloud signal list = built-in + patch config +
+     *  policy stages.intent.cloudKeywords. ONE definition shared by the
+     *  rules tier and the §7.107 gate — they can never disagree about what
+     *  counts as a public-web need. */
+    private cloudKeywordsAll;
+    /** §7.108: the FULL LOCAL entity list = built-in + patch config + policy. */
+    private localEntitiesAll;
+    /** §7.108: LOCAL last-resort list — policy stages.intent.fallbackKeywords
+     *  (non-empty) REPLACES, mirroring the env var's replace semantics. */
+    /** §7.124 (2026-10-27): the device-command extension terms = patch config
+     *  (config/edge.json stages.intent.deviceCommands) + the policy file's
+     *  stages.intent.deviceCommands (hot-reloadable, read LIVE per classify).
+     *  Both are ADDITIVE on top of the built-in vocabulary. */
+    private deviceCommandTerms;
+    private fallbackKeywordsAll;
+    /**
+     * §7.107: the public-web signal — the keyword that unlocks the cloud.
+     *
+     * Same list the rules tier matches (built-in information-acquisition words
+     * + patch `stages.intent.cloudKeywords` + policy-file
+     * `stages.intent.cloudKeywords` (§7.108)); `classifyWithRules` calls this
+     * so the gate and the rules tier cannot drift apart.
+     */
+    cloudSignal(text: string): string | undefined;
+    private classifyWithRules;
+    resolve(intent: Intent): {
+        realm: string;
+        config: Record<string, unknown>;
+    };
+    /** Snapshot of in-memory counters. Returned object is a copy so callers
+     *  can't mutate the live state. Counters are process-local — restart
+     *  zeroes them. */
+    /** §7.92.7 (2026-09-24): boot-time health probe. Fires once at
+     *  `start()` (called from `apply()`). Fire-and-forget — does NOT
+     *  block plugin init. On 2xx → no-op (the breaker stays closed;
+     *  classify() proceeds normally). On non-2xx / network error /
+     *  timeout → pre-opens the breaker for `jevBreakerTtlMs` so the
+     *  first classify() short-circuits instead of paying
+     *  3 × `jevTimeoutMs` wall-clock.
+     *
+     *  Why fire-and-forget: blocking plugin init on a 2s jev probe
+     *  adds 2s to cold boot, and a chat-less boot (e.g. CI smoke) has
+     *  no classify() to gate. Race against first classify() is fine
+     *  because: (1) plugin apply() runs before http-api opens its
+     *  port, so the earliest chat is several hundred ms away, (2) if
+     *  classify() runs first it just trips the breaker the normal
+     *  way (3 batch fails) — same outcome as the probe. */
+    start(): void;
+    /** §7.92.7: dispose hook. Awaits the in-flight boot probe (if
+     *  any) and clears the recovery-probe timer. Tests call this to
+     *  keep the event loop clean between cases; cordis calls this
+     *  on plugin teardown. */
+    stop(): Promise<void>;
+    /** §7.92.7: probe jev `/health`. Returns true on HTTP 2xx, false
+     *  on anything else (network error, timeout, non-2xx). Always
+     *  resolves — never throws. The `phase` arg distinguishes boot-time
+     *  vs periodic-recovery audit kinds so ops can tell them apart in
+     *  the log. */
+    private probeJevHealth;
+    /** §7.92.7: start the recovery probe setInterval. Idempotent.
+     *  Called from classifyWithJev() right after `jevBreakerOpenUntil`
+     *  is set. When the periodic probe lands on 2xx it closes the
+     *  breaker (and stops itself) — recovery is faster than waiting
+     *  for full TTL. */
+    private startBreakerProbe;
+    /** §7.92.7: clear the recovery probe setInterval. Idempotent. */
+    private stopBreakerProbe;
+    /** §7.92.7 helper: wall-clock spent in the most recent successful
+     *  probe (used in `intent.jev.recovered` audit payload). The
+     *  setInterval callback captures `probeStart` in its closure but
+     *  doesn't surface it cleanly — keep this lightweight by storing
+     *  the latest observed latency in instance state. */
+    private jevLastProbeLatencyMs;
+    private jevProbeTimerLatency;
+    getStats(): IntentRouterStats;
+}
+/** Map an Intent to a realm/config tuple the rest of the agent loop can consume. */
+export declare function resolveIntent(intent: Intent): {
+    realm: string;
+    config: Record<string, unknown>;
+};
+/** Parsed shape of the LLM's classification response. */
+interface ClassificationVerdict {
+    /** §7.92.3 (2026-09-23): widened from the historical 2-category union
+     *  (LOCAL | CLOUD) to match the categories spec in privacy-policy.json
+     *  — the LLM prompt now lists all 4 (LOCAL/CLOUD/SANITIZED/REJECT),
+     *  so the verdict parser must accept them too. The downstream code
+     *  (entity guardrail, classifyWithRules fallback, etc.) was already
+     *  4-category-aware via `RULE_CATEGORIES`. */
+    category: 'LOCAL' | 'CLOUD' | 'SANITIZED' | 'REJECT';
+    confidence: number;
+}
+/** In-memory counters exposed via getStats(). Pure observability; the audit
+ *  log already carries every per-call kind, but counters give operators an
+ *  O(1) read for dashboards / alerts (rate of timeouts, % sanitized, etc.)
+ *  without parsing JSONL. */
+export interface IntentRouterStats {
+    total: number;
+    empty: number;
+    truncated: number;
+    /** LLM verdict adopted as the final intent. */
+    llmHit: number;
+    /** TTL/LRU 缓存命中 —— 同文本+同上下文的重复 classify() 不再付
+     *  LLM/jev 往返（"你好" 类闲聊在 §7.107 gate 下尤其常见）。 */
+    cacheHit: number;
+    /** classifyWithRules adopted — privacy-policy match OR hardcoded keyword. */
+    ruleHit: number;
+    /** §7.124 (2026-10-27): Tier-0 device-command regex hit — the turn was
+     * decided locally by regex, without calling jev or the LLM classifier.
+     * Every hit saved one decision-model round-trip (~150ms-6s). */
+    deviceCommandHit: number;
+    /** No LLM verdict, no keyword → defaultCategory returned. */
+    defaultHit: number;
+    /** LLM returned below confidence threshold (cause of fallback to rules). */
+    lowConfidence: number;
+    /** AbortController fired during LLM stream. */
+    timeout: number;
+    /** LLM threw a non-timeout error (network, parse, etc.). */
+    llmError: number;
+    /** P1: LLM stream returned text that parseClassificationVerdict could
+     *  not turn into a verdict (all three tiers failed). Distinct from
+     *  `llmError` (network / timeout) — the LLM DID respond, the response
+     *  just wasn't structured. Operators can compare
+     *  `parseFailure / (llmHit + lowConfidence + parseFailure + llmError)`
+     *  to gauge parse health. */
+    parseFailure: number;
+    /** REJECT verdict returned (pre-check or fallback). */
+    rejected: number;
+    /** Sanitizer applied to CLOUD-classification prompt. */
+    sanitized: number;
+    /** Sanitizer threw (fail-closed → throws, falls back to classifyWithRules). */
+    sanitizeError: number;
+    /** CLOUD realm but no sanitizer handle mounted (fail-closed → throws). */
+    sanitizeSkipped: number;
+    /** §7.92.3 (2026-09-23): jev verdict ADOPTED (path: jev-adopt). Sum
+     *  with `llmHit + ruleHit + defaultHit + jevHit` to verify all paths
+     *  hit a final verdict. Compare `jevHit / total` to estimate latency
+     *  savings from the toggle (every jevHit replaces a 4-30s LLM call
+     *  with a ~150ms jev call). */
+    jevHit: number;
+    /** §7.92.3: jev risk-gated REJECT (risk_score >= threshold). Subset
+     *  of `rejected`. */
+    jevReject: number;
+    /** §7.92.3: jev SKIPPED to LLM (low-conf / fallback_llm / unmapped).
+     *  Distinct from jevError (transport failure) — skip means jev
+     *  worked fine, just deferred to LLM for quality reasons. */
+    jevSkip: number;
+    /** §7.92.3: jev transport / parse failure. Counts alongside jevSkip
+     *  in classify()'s tally but operators triage them separately:
+     *  jevError rate climbing → jev service health issue, jevSkip rate
+     *  climbing → jev's intent set doesn't match our traffic. */
+    jevError: number;
+    /** §7.92.3: subset of jevError where AbortSignal fired. */
+    jevTimeout: number;
+    /** §7.92.3: cumulative jev `data.latency_ms` sum (ms). Use with
+     *  `getStats()` calls to compute average jev latency without
+     *  parsing JSONL. */
+    jevLatencyMsTotal: number;
+    /** §7.92.6 (2026-09-24): circuit-breaker opened N times in this
+     *  process lifetime. Climbs → jev service is flapping. Pair with
+     *  jevCircuitSkip to estimate total bypassed latency: each skip
+     *  avoided ~3 × jevTimeoutMs = 7500ms worst-case wall-clock. */
+    jevCircuitOpen: number;
+    /** §7.92.6: classify() calls that returned early because breaker
+     *  was open. Total latency saved ≈ jevCircuitSkip × 7500ms. */
+    jevCircuitSkip: number;
+    /** §7.92.7 (2026-09-24): boot probe counters. jevBootProbeOk
+     *  climbs when the startup `GET /health` returned 2xx; jevBootProbeFail
+     *  climbs when it failed (breaker pre-opened, first classify()
+     *  short-circuits). Operators compare these to gauge whether jev
+     *  is consistently unhealthy at boot. */
+    jevBootProbeOk: number;
+    jevBootProbeFail: number;
+    /** §7.92.7: periodic recovery probe counters. jevProbeAttempts =
+     *  total `/health` pings fired while the breaker was open;
+     *  jevRecoveredProbe = times a probe succeeded and closed the
+     *  breaker (recovery was faster than waiting for full TTL).
+     *  Healthy ratio ≈ jevRecoveredProbe / jevProbeAttempts. */
+    jevProbeAttempts: number;
+    jevRecoveredProbe: number;
+    /** G9: 10-bucket histogram of LLM confidence values × (accepted | rejected).
+     *  Bucket key is `String(Math.floor(c * 10))` clamped to [0,9]. Use
+     *  `getStats()` to obtain a deep copy. Empty until the first parsed
+     *  verdict — timeouts / errors / unclear responses are not recorded. */
+    confidenceHistogram: {
+        [bucket: string]: {
+            accepted: number;
+            rejected: number;
+        };
+    };
+}
+/**
+ * Fence-tolerant parser for `{ category, confidence }` JSON the LLM returns.
+ * Falls back to: extract the first {...} block → regex token match for
+ * `category` + a best-effort confidence float from the surrounding text.
+ */
+export declare function parseClassificationVerdict(raw: string): ClassificationVerdict | null;
+export declare function coerceClassification(obj: unknown): ClassificationVerdict | null;
+/** Best-effort extract a text payload from a recent-message object.
+ *  Handles dsh-llm's `{content: [{type:'text', text}]}`, plain `{text}`,
+ *  `{message: string}`, or anything stringifiable. Returns '' on failure. */
+export declare function extractMessageText(m: unknown): string;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        intentRouter: IntentRouterServiceImpl;
+    }
+}
+export declare function apply(ctx: Context, config: Config): Promise<() => Promise<void>>;
+//# sourceMappingURL=intent-router.d.ts.map