@aiwayds/dsh-mcp-adapter 0.5.0 → 0.6.0

package/lib/jev/seams.js

@@ -0,0 +1,364 @@
+/**
+ * The three System One seams (jev business wiring) — and ONLY these three
+ * places in the plugin may call out to a decision backend.
+ *
+ * WHERE THEY ARE ALLOWED TO RUN (red line ①, hot paths stay remote-free):
+ *  - {@link askKeepSuggestions} — the background keep-suggestion batch, fired
+ *    by the usage counter and awaited by nobody;
+ *  - {@link rankListQuery} — `mcp_list {query}` only, i.e. when the MODEL
+ *    explicitly asked for a ranked view;
+ *  - {@link rankDidYouMean} — `mcp_call`'s unknown-tool branch, i.e. an error
+ *    the model is going to read anyway.
+ *  The assemble waterfall, `mcp_list` without a query, and a SUCCESSFUL
+ *  dispatch never appear in this file's call graph.
+ *
+ * FAIL-OPEN (red line ②): every export returns a "no opinion" value on ANY
+ * failure — disabled, timeout, 5xx, bad JSON, a thrown hook, an unparseable
+ * answer. None of them throws. The caller's lexical order then stands, which
+ * is the pre-seam behavior; a jev outage is indistinguishable from jev being
+ * off.
+ *
+ * CALIBRATION: the batch in {@link askKeepSuggestions} is the one seam that
+ * reads a band (thresholds.ts, kind 'suggest') — and only as a DISPLAY label
+ * on a suggestion row, and only for a PRIMARY probability. The two ranking
+ * seams log their probabilities with band 'record': a rank is relative
+ * ordering, and adopting/vetoing thresholds ported from another plugin's
+ * protocol would be a category error. An laya probability is not calibrated at
+ * all (dual.ts: relative use only), so a pace-maker answer NEVER takes a band
+ * and NEVER becomes a suggestion row — see {@link askKeepSuggestions}.
+ *
+ * @module jev/seams
+ */
+import { jevAskDual } from "./dual.js";
+import { band } from "./thresholds.js";
+import { digestFor } from "./log.js";
+import { RANK_CANDIDATE_LIMIT } from "../rank.js";
+import { suggestionBasis } from "../usage.js";
+/** A probability is usable only when it is a finite 0..1 number. */
+export function noulProbability(answer) {
+    if (typeof answer !== 'object' || answer === null)
+        return undefined;
+    const p = answer.noul;
+    return typeof p === 'number' && Number.isFinite(p) && p >= 0 && p <= 1 ? p : undefined;
+}
+/** The option-probability map of a `choice` answer, when present and usable. */
+function choiceProbabilities(answer) {
+    if (typeof answer !== 'object' || answer === null)
+        return undefined;
+    const raw = answer.probabilities;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return undefined;
+    const out = {};
+    for (const [option, value] of Object.entries(raw)) {
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1)
+            out[option] = value;
+    }
+    return Object.keys(out).length === 0 ? undefined : out;
+}
+/** The single winning option of a `choice` answer, when present. */
+function choiceWinner(answer) {
+    if (typeof answer !== 'object' || answer === null)
+        return undefined;
+    const choice = answer.choice;
+    return typeof choice === 'string' && choice !== '' ? choice : undefined;
+}
+const RANK_QUESTION_ID = 'r1';
+/**
+ * The ranking question both rank seams share (one batched choice request
+ * each). The option KEY is the tool name, so the answer maps back onto the
+ * candidate pool without an index that could drift.
+ */
+function rankQuestion(instructions, candidates) {
+    const criteria = {};
+    for (const candidate of candidates) {
+        const blurb = candidate.description.replace(/\s+/gu, ' ').trim().slice(0, 200);
+        criteria[candidate.name] = blurb === '' ? candidate.name : `${candidate.name}: ${blurb}`;
+    }
+    return { type: 'choice', instructions, criteria };
+}
+/**
+ * Turn one jev ranking answer into an order. A full probability map sorts by
+ * probability descending (ties keep the lexical order); a bare `choice` field
+ * only moves the winner to the front; anything unparseable reports "no
+ * opinion" so the caller keeps the order it already had.
+ *
+ * @param candidates - the pool the question was asked about, in lexical order.
+ * @param answer - the raw answer value for {@link RANK_QUESTION_ID}.
+ * @returns the reordered names, or undefined for "no opinion".
+ */
+export function orderFromChoice(candidates, answer) {
+    const names = candidates.map(candidate => candidate.name);
+    const index = new Map(names.map((name, position) => [name, position]));
+    const raw = choiceProbabilities(answer);
+    // A probability map that scores NONE of the candidates says nothing about
+    // their order — treat it as no opinion, not as "all equal".
+    const probabilities = raw === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(raw).filter(([name]) => index.has(name)));
+    if (probabilities !== undefined && Object.keys(probabilities).length > 0) {
+        return [...names].sort((left, right) => {
+            const a = probabilities[left] ?? -1;
+            const b = probabilities[right] ?? -1;
+            return (b - a) || ((index.get(left) ?? 0) - (index.get(right) ?? 0));
+        });
+    }
+    const winner = choiceWinner(answer);
+    if (winner === undefined || !index.has(winner))
+        return undefined;
+    return [winner, ...names.filter(name => name !== winner)];
+}
+/**
+ * Log one verdict row per candidate the ranking answer scored. `band: 'record'`
+ * and `agree: 'n/a'` are deliberate: a relative order has no adopt/veto
+ * threshold to reconcile against, and inventing one would poison the
+ * calibration analysis with a band nothing acts on.
+ */
+async function logRankVerdicts(log, lane, state, instructions, candidates, answer, backend, degraded) {
+    const probabilities = choiceProbabilities(answer);
+    if (probabilities === undefined)
+        return;
+    const at = new Date().toISOString();
+    const rows = candidates
+        .map(candidate => ({ candidate, p: probabilities[candidate.name] }))
+        .filter((entry) => entry.p !== undefined)
+        .map(entry => ({
+        at,
+        lane,
+        questionId: RANK_QUESTION_ID,
+        qtype: 'choice',
+        ref: `tool:${entry.candidate.name}`,
+        digest: digestFor(state, RANK_QUESTION_ID, instructions),
+        probability: entry.p,
+        band: 'record',
+        agree: 'n/a',
+        backend,
+        degraded,
+    }));
+    await log.logVerdicts(rows);
+}
+/**
+ * Seam B: rerank `mcp_list {query}` candidates by relevance.
+ *
+ * The incoming order is the LEXICAL one (see ../rank.ts) and is also the
+ * fail-open result: any failure, disabled switch, or unusable answer returns
+ * `undefined`, which the caller reads as "keep what you had".
+ *
+ * A DEGRADED answer (the local laya pace-maker took over because the primary
+ * backend failed) is usable here: relative ordering is exactly what a rank
+ * is, and jev/dual.ts's contract allows degraded results for relative use
+ * only — which is all this seam does.
+ *
+ * @param query - the model's query text.
+ * @param ordered - lexical order (best first), already capped by the caller.
+ * @param env - the live jev runtime.
+ * @returns the jev order, or undefined for "no opinion".
+ */
+export async function rankListQuery(query, ordered, env) {
+    const candidates = ordered.slice(0, RANK_CANDIDATE_LIMIT);
+    if (candidates.length < 2)
+        return undefined;
+    const instructions = `下面这些 MCP 工具里，哪一个与检索 query 最相关？请选出相关性最高的那一个。query：${query}`;
+    const state = [
+        '任务背景：模型正在通过 mcp_list 浏览被折叠出常驻 prompt 的 MCP 工具，需要按与当前任务的相关性挑选。',
+        `检索 query：${query}`,
+        `候选工具数：${candidates.length}`,
+    ].join('\n');
+    return rankSeam('list-rank', state, instructions, candidates, env);
+}
+/**
+ * Seam C: rerank the near-miss candidates of an unregistered tool name.
+ *
+ * Same fail-open contract as {@link rankListQuery}. Only runs when the lexical
+ * prefilter found MORE THAN ONE candidate — a single lexical hit needs no
+ * ranking, so the cold branch stays free when it has nothing to offer.
+ *
+ * @param tool - the name dispatch could not resolve.
+ * @param ordered - lexical near-miss order (best first).
+ * @param env - the live jev runtime.
+ * @returns the jev order, or undefined for "no opinion".
+ */
+export async function rankDidYouMean(tool, ordered, env) {
+    const candidates = ordered.slice(0, RANK_CANDIDATE_LIMIT);
+    if (candidates.length < 2)
+        return undefined;
+    const instructions = `模型刚刚尝试调用 MCP 工具「${tool}」，但这个名字没有注册。哪一个候选最可能就是它想调用的工具？`;
+    const state = [
+        '任务背景：模型通过 mcp_call 分发被折叠出常驻 prompt 的 MCP 工具，工具名拼错时会走到 not-registered 分支。',
+        `未注册的工具名：${tool}`,
+        `候选工具数：${candidates.length}`,
+    ].join('\n');
+    return rankSeam('didyoumean', state, instructions, candidates, env);
+}
+/** Shared body of both ranking seams (one batched choice request each). */
+async function rankSeam(lane, state, instructions, candidates, env) {
+    try {
+        if (!env.enabled())
+            return undefined;
+        const dual = await jevAskDual({
+            state,
+            questions: { [RANK_QUESTION_ID]: rankQuestion(instructions, candidates) },
+            config: env.config(),
+            lane,
+            // fail-open is real here: the caller's lexical order IS the fallback.
+            fallback: true,
+            log: env.log(),
+        });
+        if (!dual.ok)
+            return undefined;
+        const answer = dual.answers[RANK_QUESTION_ID];
+        const order = orderFromChoice(candidates, answer);
+        if (order === undefined)
+            return undefined;
+        // Telemetry must never turn a good answer into a failed seam.
+        await logRankVerdicts(env.log(), lane, state, instructions, candidates, answer, dual.source, dual.source === 'laya').catch(() => undefined);
+        return order;
+    }
+    catch {
+        // contained — the seam has no throw path, by contract
+        return undefined;
+    }
+}
+/** The keep-suggestion question for one candidate (two-sided noul criteria). */
+function keepQuestion(candidate) {
+    const instructions = `候选 MCP 工具「${candidate.tool}」当前不在常驻 prompt 里（已折叠，模型每次要用都得先 mcp_list 查到它）。`
+        + `记录到的使用情况：${suggestionBasis(candidate)}。描述：${candidate.description}。`
+        + '该工具值得在每次对话中都常驻 prompt（即加入 keep 名单）吗？';
+    return {
+        type: 'noul',
+        instructions,
+        criteria: {
+            true: `值得常驻——「${candidate.tool}」被反复调用，把它的 schema 常驻 prompt 能省掉每次查找与展开的成本`,
+            false: `不值得常驻——「${candidate.tool}」的调用频次或不可替代性不足以抵消常驻 schema 的 token 成本，保持折叠即可`,
+        },
+    };
+}
+/** The state text the keep-suggestion batch is asked against. */
+function keepState(candidates) {
+    const lines = candidates.map(candidate => [
+        `- ${candidate.tool}: ${suggestionBasis(candidate)}`,
+        candidate.description === '' ? '' : `  ${candidate.description}`,
+    ].filter(line => line !== '').join('\n'));
+    return [
+        '任务背景：模型通过 mcp_list/mcp_call 使用被折叠出常驻 prompt 的 MCP 工具，每个折叠工具的 schema 都要按需展开。',
+        `候选工具数：${candidates.length}（记录到的调用情况与工具描述）`,
+        ...lines,
+    ].join('\n');
+}
+/**
+ * Seam A: ask, in ONE batched noul request, whether each folded-and-used tool
+ * earns a permanent place in every prompt.
+ *
+ * Fire-and-forget by contract: the caller never awaits this on a hot path.
+ * `null` means "this round produced nothing" (disabled, call failed, no
+ * candidates, unusable answers, DEGRADED primary) — the caller then keeps the
+ * PREVIOUS batch in suggestions.json, and the usage record is unaffected
+ * either way.
+ *
+ * ABSOLUTE SCORES ONLY FROM THE PRIMARY: a suggestion row is a calibrated
+ * probability plus a band plus an actionable "keep it resident" line that a
+ * human reads in `/mcp suggest`. When the primary failed and the local laya
+ * pace-maker took over, that answer is usable for RELATIVE ranking only
+ * (dual.ts) and laya's negatives sit in the same band as its positives — so a
+ * degraded round returns `null` instead of rendering uncalibrated numbers. The
+ * answer is still logged (band 'record', degraded=true): the laya-vs-jev bench
+ * and the fallback-rate health metric must not lose a round.
+ *
+ * @param candidates - folded tools with recorded calls, most-used first.
+ * @param env - the live jev runtime.
+ * @returns one row per answered candidate, or null.
+ */
+export async function askKeepSuggestions(candidates, env) {
+    const batch = candidates.slice(0, RANK_CANDIDATE_LIMIT);
+    if (batch.length === 0)
+        return null;
+    const state = keepState(batch);
+    const questions = {};
+    const meta = [];
+    for (const candidate of batch) {
+        const qid = `c${meta.length + 1}`;
+        const question = keepQuestion(candidate);
+        questions[qid] = question;
+        meta.push({ qid, candidate, instructions: question.instructions });
+    }
+    try {
+        if (!env.enabled())
+            return null;
+        const dual = await jevAskDual({
+            state,
+            questions,
+            config: env.config(),
+            lane: 'usage-suggest',
+            // Nothing to fall back to: suggestions are additive display, and a
+            // failed round simply leaves the previous batch in place.
+            fallback: true,
+            log: env.log(),
+        });
+        if (!dual.ok)
+            return null;
+        // The driving source produces the rows; the pace-maker (when it answered
+        // alongside a healthy primary) contributes comparison rows only, exactly
+        // as §6.2 prescribes.
+        const driving = {
+            answers: dual.answers,
+            backend: dual.source,
+            degraded: dual.source === 'laya',
+        };
+        const sources = [driving];
+        if (dual.source === 'primary' && dual.layaResult?.ok === true) {
+            sources.push({ answers: dual.layaResult.answers, backend: 'laya', degraded: false });
+        }
+        const at = new Date().toISOString();
+        const records = [];
+        const rows = [];
+        for (const source of sources) {
+            for (const entry of meta) {
+                const probability = noulProbability(source.answers[entry.qid]);
+                if (probability === undefined)
+                    continue; // unparseable answer: no fabricated row
+                // A pace-maker probability is uncalibrated, so it never takes a band
+                // (`band()` would be a category error) and never becomes a
+                // suggestion row — whichever way it got here: a comparison row
+                // beside a healthy primary, or a degraded takeover.
+                const fromPaceMaker = source.backend !== 'primary';
+                const verdictBand = fromPaceMaker ? 'record' : band(probability, 'suggest');
+                rows.push({
+                    at,
+                    lane: 'usage-suggest',
+                    questionId: entry.qid,
+                    qtype: 'noul',
+                    ref: `tool:${entry.candidate.tool}`,
+                    digest: digestFor(state, entry.qid, entry.instructions),
+                    probability,
+                    band: verdictBand,
+                    // Candidates are folded by construction, so there is no legacy
+                    // "it was already kept" disposition to reconcile against.
+                    agree: 'n/a',
+                    backend: source.backend,
+                    degraded: source.degraded,
+                });
+                if (fromPaceMaker)
+                    continue; // telemetry/bench row only — never a suggestion
+                records.push({
+                    tool: entry.candidate.tool,
+                    probability,
+                    band: verdictBand,
+                    basis: suggestionBasis(entry.candidate),
+                    _at: at,
+                });
+            }
+        }
+        await env.log().logVerdicts(rows).catch(() => undefined);
+        // A degraded round produced verdict rows and nothing else: no primary
+        // drove it, so there is no calibrated number to show and no record to
+        // write — the previous batch stands (see the module doc).
+        if (records.length === 0)
+            return null;
+        records.sort((left, right) => right.probability - left.probability || left.tool.localeCompare(right.tool));
+        return records;
+    }
+    catch {
+        // contained — a broken batch must never reach the dispatch path
+        return null;
+    }
+}
+//# sourceMappingURL=seams.js.map

package/lib/jev/seams.js.map

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

package/lib/jev/thresholds.d.ts

@@ -0,0 +1,37 @@
+/**
+ * System One decision bands (design 2026-09-25 §5), ported from
+ * dsh-topics-memory `src/jev/thresholds.ts` with the band kind renamed
+ * `rerank` → `suggest` for this plugin's `/mcp suggest` seam.
+ *
+ * !!! CALIBRATION NOTICE — READ BEFORE ACTING ON A BAND !!!
+ * The numbers below are PLACEHOLDERS copied over from topics-memory to keep
+ * the file's shape identical for diffing. They were calibrated for THAT
+ * plugin's own question protocol and corpus; this plugin's protocol differs
+ * (different candidates, different instructions, batch shape), so the
+ * absolute probabilities move. Every value MUST be re-swept against this
+ * plugin's own protocol before any band is treated as a calibration
+ * conclusion — do NOT carry over topics-memory's numbers.
+ *
+ * WHERE A BAND IS READ TODAY: exactly one place — seam A (`jev/seams.ts`
+ * askKeepSuggestions) reads `band(p, 'suggest')` as the DISPLAY label on a
+ * `/mcp suggest` row that already carries the raw probability. Nothing
+ * auto-acts on a band, and a pace-maker (laya) probability never takes one:
+ * uncalibrated scores are logged as band 'record' and produce no suggestion
+ * row, so a degraded round yields no band at all. Until this plugin's own
+ * re-sweep lands, a band must be read as "above the placeholder cutoff", not
+ * as "adopt/veto is justified".
+ *
+ * @module jev/thresholds
+ */
+/** `/mcp suggest` (建议补的 mcp 工具): adopt ≥ 0.60, strong-veto < 0.10. */
+export declare const SUGGEST_ADOPT = 0.6;
+export declare const SUGGEST_FALLBACK = 0.1;
+/** Second band kind, kept for shape parity with the source file and for the
+ *  lanes that are not calibrated yet — the values are placeholders too. */
+export declare const MERGE_PAIR_ADOPT = 0.5;
+export declare const MERGE_PAIR_FALLBACK = 0.15;
+export type JevBand = 'adopt' | 'record' | 'fallback';
+export type JevBandKind = 'suggest' | 'mergePair';
+/** Map a noul probability to its band: adopt → act on it, record → only log
+ *  it, fallback → hard veto back to the legacy behavior. */
+export declare function band(probability: number, kind: JevBandKind): JevBand;

package/lib/jev/thresholds.js

@@ -0,0 +1,44 @@
+/**
+ * System One decision bands (design 2026-09-25 §5), ported from
+ * dsh-topics-memory `src/jev/thresholds.ts` with the band kind renamed
+ * `rerank` → `suggest` for this plugin's `/mcp suggest` seam.
+ *
+ * !!! CALIBRATION NOTICE — READ BEFORE ACTING ON A BAND !!!
+ * The numbers below are PLACEHOLDERS copied over from topics-memory to keep
+ * the file's shape identical for diffing. They were calibrated for THAT
+ * plugin's own question protocol and corpus; this plugin's protocol differs
+ * (different candidates, different instructions, batch shape), so the
+ * absolute probabilities move. Every value MUST be re-swept against this
+ * plugin's own protocol before any band is treated as a calibration
+ * conclusion — do NOT carry over topics-memory's numbers.
+ *
+ * WHERE A BAND IS READ TODAY: exactly one place — seam A (`jev/seams.ts`
+ * askKeepSuggestions) reads `band(p, 'suggest')` as the DISPLAY label on a
+ * `/mcp suggest` row that already carries the raw probability. Nothing
+ * auto-acts on a band, and a pace-maker (laya) probability never takes one:
+ * uncalibrated scores are logged as band 'record' and produce no suggestion
+ * row, so a degraded round yields no band at all. Until this plugin's own
+ * re-sweep lands, a band must be read as "above the placeholder cutoff", not
+ * as "adopt/veto is justified".
+ *
+ * @module jev/thresholds
+ */
+/** `/mcp suggest` (建议补的 mcp 工具): adopt ≥ 0.60, strong-veto < 0.10. */
+export const SUGGEST_ADOPT = 0.6;
+export const SUGGEST_FALLBACK = 0.1;
+/** Second band kind, kept for shape parity with the source file and for the
+ *  lanes that are not calibrated yet — the values are placeholders too. */
+export const MERGE_PAIR_ADOPT = 0.5;
+export const MERGE_PAIR_FALLBACK = 0.15;
+/** Map a noul probability to its band: adopt → act on it, record → only log
+ *  it, fallback → hard veto back to the legacy behavior. */
+export function band(probability, kind) {
+    const floor = kind === 'suggest' ? SUGGEST_FALLBACK : MERGE_PAIR_FALLBACK;
+    const adopt = kind === 'suggest' ? SUGGEST_ADOPT : MERGE_PAIR_ADOPT;
+    if (probability >= adopt)
+        return 'adopt';
+    if (probability >= floor)
+        return 'record';
+    return 'fallback';
+}
+//# sourceMappingURL=thresholds.js.map

package/lib/jev/thresholds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"thresholds.js","sourceRoot":"","sources":["../../src/jev/thresholds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,sEAAsE;AACtE,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAA;AAChC,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAA;AAEnC;2EAC2E;AAC3E,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAA;AACnC,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAA;AAKvC;4DAC4D;AAC5D,MAAM,UAAU,IAAI,CAAC,WAAmB,EAAE,IAAiB;IACzD,MAAM,KAAK,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC,mBAAmB,CAAA;IACzE,MAAM,KAAK,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,gBAAgB,CAAA;IACnE,IAAI,WAAW,IAAI,KAAK;QAAE,OAAO,OAAO,CAAA;IACxC,IAAI,WAAW,IAAI,KAAK;QAAE,OAAO,QAAQ,CAAA;IACzC,OAAO,UAAU,CAAA;AACnB,CAAC"}

package/lib/rank.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Lexical pre-ranking for the two model-facing search seams (`mcp_list
+ * {query}` and `mcp_call`'s unknown-tool branch).
+ *
+ * WHY A SEPARATE MODULE: these are the pure, dependency-free halves of seams
+ * B and C. They must stay callable from `node --test` without the meta-tool
+ * definitions, AND from `jev/seams.ts` (which reranks whatever this module
+ * produced) — so they cannot live in src/index.ts without an import cycle
+ * (index.ts → jev/seams.ts → index.ts).
+ *
+ * CONTRACT (red line ②): everything here is deterministic, synchronous and
+ * offline. A jev answer is only ever a REORDER of what these functions already
+ * produced (see {@link mergeNameOrder}); any jev failure degrades to the
+ * order computed below, so this file is the fail-open baseline of both seams.
+ *
+ * SCRIPT: the lexical prefilter runs over the ASCII tokens when the query has
+ * any, and falls back to a CJK substring match when it has none (see
+ * {@link cjkQuery}) — the model asks this plugin's questions in Chinese.
+ *
+ * @module rank
+ */
+/** Cap on the candidate list handed to a jev batch (both ranking seams). */
+export declare const RANK_CANDIDATE_LIMIT = 40;
+/** How many ranked tools a `mcp_list {query}` answer actually shows. */
+export declare const LIST_RESULT_LIMIT = 10;
+/** How many near-misses the unknown-tool error names. */
+export declare const DID_YOU_MEAN_LIMIT = 3;
+/** Max edit distance a near-miss may have to be offered. */
+export declare const DID_YOU_MEAN_MAX_DISTANCE = 3;
+/** The minimal shape ranking needs from a tool. */
+export interface RankableEntry {
+    readonly name: string;
+    readonly description: string;
+}
+/**
+ * What the ranking seams pass around: a tool plus the blurb that goes into a
+ * decision question (or into the lexical score). Named separately from
+ * {@link RankableEntry} because it crosses the seam boundary (index.ts builds
+ * the pools, jev/seams.ts asks about them).
+ */
+export type RankCandidate = RankableEntry;
+/**
+ * Lowercase alphanumeric tokens of one string, split on non-alphanumeric runs
+ * AND on camelCase / letter-digit boundaries — so `create_issue`,
+ * `createIssue` and `createissue` all reduce to overlapping tokens. Tool
+ * naming conventions vary per MCP vendor; the search seam must not depend on
+ * one of them.
+ *
+ * ASCII ONLY, on purpose: the token weights in {@link scoreQueryMatch} are
+ * calibrated on token equality, and a CJK query has no ASCII tokens to
+ * compare. Chinese/other CJK text is matched by the substring fallback
+ * ({@link cjkQuery}) instead, and that fallback is a SEPARATE path so the
+ * ASCII ranking cannot drift.
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Lexical score of one entry against a tokenized query. 0 means "no match at
+ * all" and is what the rankers filter on — an unmatched entry is never shown
+ * as a result, however long its description is.
+ *
+ * Weights: exact full-name equality dominates; a query token found in the
+ * NAME beats one found only in the DESCRIPTION; a whole-phrase substring hit
+ * beats a scattered per-token hit.
+ *
+ * @param entry - the tool being scored.
+ * @param tokens - query tokens from {@link tokenize}.
+ * @param queryCompact - the whole query squashed to alphanumerics.
+ * @returns the score (0 = no match).
+ */
+export declare function scoreQueryMatch(entry: RankableEntry, tokens: readonly string[], queryCompact: string): number;
+/**
+ * Rank entries against a free-text query: best score first, name ascending as
+ * the deterministic tie-break, entries with no lexical match dropped, at most
+ * `limit` survivors.
+ *
+ * A query with no ASCII token falls back to the CJK substring prefilter
+ * ({@link cjkQuery}) — the model writes this plugin's queries in Chinese, and
+ * "no tokens" must not read as "nothing matched". A query with neither ASCII
+ * nor CJK content (blank, punctuation) still matches nothing.
+ *
+ * Pure and synchronous — this is the order a failed/failed-open jev rerank
+ * degrades to, and the only order produced when `jevEnabled` is false.
+ *
+ * @param query - the model's raw query text.
+ * @param entries - the catalog entries to score (input is never mutated).
+ * @param limit - max survivors; omit for "every match".
+ * @returns the surviving entries, best first.
+ */
+export declare function rankByQuery<T extends RankableEntry>(query: string, entries: readonly T[], limit?: number): T[];
+/**
+ * Reorder a list of NAMES by an external ranking (the jev answer). Names the
+ * ranking does not mention — and names it repeats — keep their original
+ * relative order at the tail, so a short or partial answer degrades to "jev's
+ * prefix + lexical remainder" instead of dropping candidates. Names that were
+ * not in `ordered` at all are ignored.
+ *
+ * @param ordered - the lexical order being permuted.
+ * @param ranking - tool names, best first, as returned by the reranker.
+ * @returns a new array; `ordered` is never mutated.
+ */
+export declare function mergeNameOrder(ordered: readonly string[], ranking: readonly string[]): string[];
+/**
+ * Levenshtein distance between two names, or `undefined` when it is provably
+ * greater than `max`. The length pre-check plus the per-row minimum make the
+ * common "clearly not a near-miss" case O(max) instead of O(n·m); names are
+ * short anyway, but the pool can be a full catalog and this runs inside a
+ * dispatch error path.
+ *
+ * @param a - first name (case-insensitive).
+ * @param b - second name (case-insensitive).
+ * @param max - distances above this report "no".
+ * @returns the distance, or undefined when it exceeds `max`.
+ */
+export declare function editDistanceWithin(a: string, b: string, max: number): number | undefined;
+/** Where one near-miss landed: a typo of the name, or merely a shared token. */
+export type DidYouMeanTier = 'edit' | 'token';
+/** One scored near-miss candidate. */
+export interface DidYouMeanCandidate {
+    /** The candidate's registered tool name. */
+    name: string;
+    /** How it matched: within the edit distance, or on a shared token. */
+    tier: DidYouMeanTier;
+    /** Edit distance (0 for token-only matches, which are not distance-graded). */
+    distance: number;
+    /** Tokens shared with the mistyped name. */
+    shared: number;
+}
+/**
+ * Lexical near-miss candidates for one unregistered tool name: everything
+ * within {@link DID_YOU_MEAN_MAX_DISTANCE} edits, plus anything sharing a
+ * name token, best first. This is the always-on floor of the unknown-tool
+ * branch — it runs whether or not jev is enabled, needs no network, and is
+ * the order that stands when a jev rerank fails.
+ *
+ * @param tool - the name dispatch could not resolve.
+ * @param pool - candidate names (production: the visible prefix tools).
+ * @param limit - max candidates (default {@link DID_YOU_MEAN_LIMIT}).
+ * @param ignoreTokens - tokens that must NOT count as a shared-token match.
+ *   The caller's fold prefix goes here: every candidate in the pool starts
+ *   with it, so "shares mcp" is not evidence of anything.
+ * @returns the candidates, best first (edit tier, then fewest edits, then
+ *   most shared tokens, then shorter, then alphabetical).
+ */
+export declare function didYouMeanCandidates(tool: string, pool: readonly string[], limit?: number, ignoreTokens?: readonly string[]): DidYouMeanCandidate[];
+/** Which ordering produced a suggestion list — shown in the error text. */
+export type DidYouMeanSource = 'lexical' | 'jev';
+/**
+ * The suffix appended to the unknown-tool error. The base message stays
+ * byte-identical to the pre-seam one, so a caller that only knew the old text
+ * still matches it; the suggestion is an addition, and its provenance is
+ * always stated (an unranked guess must not look like a ranked one).
+ *
+ * @param names - suggested tool names, best first.
+ * @param source - who produced the order.
+ * @returns `''` when there is nothing to suggest.
+ */
+export declare function didYouMeanMessage(names: readonly string[], source: DidYouMeanSource): string;