@aiwayds/dsh-mcp-adapter 0.5.0 → 0.6.0

package/lib/rank.js

@@ -0,0 +1,327 @@
+/**
+ * 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 const RANK_CANDIDATE_LIMIT = 40;
+/** How many ranked tools a `mcp_list {query}` answer actually shows. */
+export const LIST_RESULT_LIMIT = 10;
+/** How many near-misses the unknown-tool error names. */
+export const DID_YOU_MEAN_LIMIT = 3;
+/** Max edit distance a near-miss may have to be offered. */
+export const DID_YOU_MEAN_MAX_DISTANCE = 3;
+/**
+ * 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 function tokenize(text) {
+    const out = [];
+    for (const chunk of text.split(/[^A-Za-z0-9]+/)) {
+        if (chunk === '')
+            continue;
+        for (const part of chunk.split(/(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Za-z])(?=[0-9])/)) {
+            if (part !== '')
+                out.push(part.toLowerCase());
+        }
+    }
+    return out;
+}
+/** All alphanumerics of one string, lowercased (`create_issue` → `createissue`). */
+function compact(text) {
+    return text.toLowerCase().replace(/[^a-z0-9]+/gu, '');
+}
+// ---------------------------------------------------------------------------
+// CJK fallback (added 09-27). dsh is a Chinese-language ecosystem, so the
+// model's `mcp_list {query}` is very often Chinese — and Chinese has no
+// spaces, no case and no ASCII letters, so tokenize() returns NOTHING and the
+// prefilter reported "no MCP tool matches the query" for a query it had never
+// actually searched. The fallback is a substring match over the query's CJK
+// runs, kept out of the ASCII path so the ASCII weights stay exactly as
+// calibrated.
+// ---------------------------------------------------------------------------
+/** One run of Han / kana / Hangul text. */
+const CJK_RUN = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]+/gu;
+/** The CJK content of one string, with everything else dropped. */
+function cjkText(text) {
+    return (text.match(CJK_RUN) ?? []).join('');
+}
+/**
+ * Reduce a query to its CJK content, or null when it has none (an ASCII or
+ * punctuation-only query takes the token path instead).
+ *
+ * BIGRAMS, not single characters: they are the Chinese analogue of an ASCII
+ * word, so `搜索文件` searches 搜索 / 索文 / 文件 and a description that
+ * merely happens to contain 文 is not a match. A one-character run has no
+ * bigram and stands for itself, so `文` still finds `读取文件`.
+ */
+function cjkQuery(query) {
+    const text = cjkText(query);
+    if (text === '')
+        return null;
+    const tokens = [];
+    for (const run of query.match(CJK_RUN) ?? []) {
+        if (run.length < 2) {
+            tokens.push(run);
+            continue;
+        }
+        for (let i = 0; i + 1 < run.length; i += 1)
+            tokens.push(run.slice(i, i + 2));
+    }
+    return { text, tokens };
+}
+/**
+ * The CJK counterpart of {@link scoreQueryMatch}: substring, not equality —
+ * a CJK tool name is compared as a whole, then bigram-by-bigram against the
+ * NAME before the DESCRIPTION, with the same weights as the ASCII path so the
+ * two rank a mixed catalog the same way.
+ *
+ * Latin text is stripped from both sides: it cannot carry a CJK query, and
+ * leaving it in would let `读取文件` match the latin bytes of a name.
+ */
+function scoreCjkMatch(entry, query) {
+    const name = cjkText(entry.name);
+    if (name !== '' && name === query.text)
+        return 1000;
+    const description = cjkText(entry.description);
+    let score = 0;
+    for (const token of query.tokens) {
+        if (name.includes(token))
+            score += 4;
+        else if (description.includes(token))
+            score += 1;
+    }
+    if (query.tokens.length > 1 && name.includes(query.text))
+        score += 8;
+    return score;
+}
+/**
+ * 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 function scoreQueryMatch(entry, tokens, queryCompact) {
+    const nameCompact = compact(entry.name);
+    if (nameCompact === queryCompact && queryCompact !== '')
+        return 1000;
+    const nameTokens = new Set(tokenize(entry.name));
+    const descriptionTokens = new Set(tokenize(entry.description));
+    // Vendors ship glued names in prose ("Create an issue on GitHub"), where the
+    // token splitter sees git+hub. The squashed description is the last resort
+    // so a query for "github" still finds them — at description weight.
+    const descriptionCompact = compact(entry.description);
+    let score = 0;
+    for (const token of tokens) {
+        if (nameTokens.has(token))
+            score += 4;
+        else if (nameCompact.includes(token))
+            score += 2;
+        else if (descriptionTokens.has(token))
+            score += 1;
+        else if (descriptionCompact.includes(token))
+            score += 1;
+    }
+    if (tokens.length > 1 && queryCompact !== '' && nameCompact.includes(queryCompact))
+        score += 8;
+    return score;
+}
+/**
+ * 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 function rankByQuery(query, entries, limit = Number.POSITIVE_INFINITY) {
+    const tokens = tokenize(query);
+    const queryCompact = compact(query);
+    // Only a query the ASCII tokenizer cannot see at all takes the CJK path;
+    // a mixed query keeps the (calibrated) ASCII ranking it always had.
+    const cjk = tokens.length === 0 ? cjkQuery(query) : null;
+    if (tokens.length === 0 && cjk === null)
+        return [];
+    const scored = [];
+    for (const entry of entries) {
+        const score = cjk === null ? scoreQueryMatch(entry, tokens, queryCompact) : scoreCjkMatch(entry, cjk);
+        if (score > 0)
+            scored.push({ entry, score });
+    }
+    scored.sort((left, right) => (right.score - left.score) || left.entry.name.localeCompare(right.entry.name));
+    return scored.slice(0, limit === Number.POSITIVE_INFINITY ? undefined : limit).map(item => item.entry);
+}
+/**
+ * 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 function mergeNameOrder(ordered, ranking) {
+    const known = new Set(ordered);
+    const out = [];
+    const taken = new Set();
+    for (const name of ranking) {
+        if (!known.has(name) || taken.has(name))
+            continue;
+        taken.add(name);
+        out.push(name);
+    }
+    for (const name of ordered)
+        if (!taken.has(name))
+            out.push(name);
+    return out;
+}
+/**
+ * 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 function editDistanceWithin(a, b, max) {
+    const left = a.toLowerCase();
+    const right = b.toLowerCase();
+    if (left === right)
+        return 0;
+    if (Math.abs(left.length - right.length) > max)
+        return undefined;
+    let previous = Array.from({ length: right.length + 1 }, (_unused, index) => index);
+    for (let row = 1; row <= left.length; row += 1) {
+        const current = [row];
+        let rowMin = row;
+        for (let column = 1; column <= right.length; column += 1) {
+            const cost = left[row - 1] === right[column - 1] ? 0 : 1;
+            const value = Math.min(previous[column] + 1, current[column - 1] + 1, previous[column - 1] + cost);
+            current.push(value);
+            if (value < rowMin)
+                rowMin = value;
+        }
+        if (rowMin > max)
+            return undefined;
+        previous = current;
+    }
+    const distance = previous[right.length];
+    return distance <= max ? distance : undefined;
+}
+/**
+ * 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 function didYouMeanCandidates(tool, pool, limit = DID_YOU_MEAN_LIMIT, ignoreTokens = []) {
+    const ignored = new Set(ignoreTokens);
+    const toolTokens = new Set(tokenize(tool).filter(token => !ignored.has(token)));
+    const scored = [];
+    for (const name of pool) {
+        if (name === tool)
+            continue;
+        const distance = editDistanceWithin(tool, name, DID_YOU_MEAN_MAX_DISTANCE);
+        if (distance !== undefined) {
+            scored.push({ name, tier: 'edit', distance, shared: sharedTokens(toolTokens, name) });
+            continue;
+        }
+        const shared = sharedTokens(toolTokens, name);
+        if (shared > 0)
+            scored.push({ name, tier: 'token', distance: 0, shared });
+    }
+    scored.sort((left, right) => (tierRank(left.tier) - tierRank(right.tier))
+        || (left.distance - right.distance)
+        || (right.shared - left.shared)
+        || (left.name.length - right.name.length)
+        || left.name.localeCompare(right.name));
+    return scored.slice(0, limit === Number.POSITIVE_INFINITY ? undefined : limit);
+}
+/** Edit-tier candidates always outrank token-only ones. */
+function tierRank(tier) {
+    return tier === 'edit' ? 0 : 1;
+}
+/** How many distinct tokens the candidate's name shares with the mistyped one. */
+function sharedTokens(toolTokens, name) {
+    let shared = 0;
+    for (const token of new Set(tokenize(name)))
+        if (toolTokens.has(token))
+            shared += 1;
+    return shared;
+}
+/**
+ * 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 function didYouMeanMessage(names, source) {
+    if (names.length === 0)
+        return '';
+    const label = source === 'jev' ? 'jev reranked' : 'lexical';
+    return ` Did you mean: ${names.map(name => `"${name}"`).join(', ')}? (${label})`;
+}
+//# sourceMappingURL=rank.js.map

package/lib/rank.js.map

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

package/lib/usage.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Per-tool usage statistics and the keep-suggestion document (seam A — the
+ * self-evolution core).
+ *
+ * WHAT THIS MODULE OWNS: the durable facts only.
+ *  - `usage.json` — `{ tools: { <name>: { calls, errors, firstUsedAt,
+ *    lastUsedAt } } }`, one document in the plugin's own gate directory
+ *    (beside gate.json / decisions.jsonl / suggestions.json);
+ *  - `suggestions.json` — the last jev keep-suggestion batch.
+ *
+ * WHAT IT DELIBERATELY DOES NOT OWN: any jev call. The batch that fills
+ * suggestions.json lives in `jev/seams.ts`; this module only knows the shape
+ * of its result (so the command surface can render it without importing the
+ * client). Keeping the decision out of here is what makes the record path
+ * synchronous and remote-free: `record()` updates memory and schedules a
+ * write, and returns. Red line ① (no jev on the hot path) holds structurally
+ * because this file cannot call out at all.
+ *
+ * FAIL-OPEN (red line ②): a corrupt or unreadable document is warned about
+ * once and degrades to zero statistics — never to a crash and never to a
+ * wedged dispatch. Suggestions that cannot be read degrade to "no
+ * suggestions yet", which is exactly what an empty file means.
+ *
+ * @module usage
+ */
+import type { JevBand } from './jev/thresholds.ts';
+/** The usage document file name inside the plugin's gate directory. */
+export declare const USAGE_FILE_NAME = "usage.json";
+/** The keep-suggestion document file name inside the plugin's gate directory. */
+export declare const SUGGESTIONS_FILE_NAME = "suggestions.json";
+/** Absolute usage.json path for one gate directory. */
+export declare function usageFile(dir: string): string;
+/** Absolute suggestions.json path for one gate directory. */
+export declare function suggestionsFile(dir: string): string;
+/**
+ * Recorded counters for one tool. Timestamps are ISO strings (`''` when the
+ * document was hand-written without them) so the document stays
+ * human-readable and diffable.
+ */
+export interface ToolUsageStats {
+    /** Dispatches through mcp_call, successes AND failures. */
+    calls: number;
+    /** How many of those dispatches came back as this plugin's `{ error }` wrap. */
+    errors: number;
+    /** ISO time of the first recorded call; `''` when unknown. */
+    firstUsedAt: string;
+    /** ISO time of the most recent recorded call; `''` when unknown. */
+    lastUsedAt: string;
+}
+/** The whole usage document. */
+export interface UsageDocument {
+    tools: Record<string, ToolUsageStats>;
+}
+/** Fresh-install zero state. */
+export declare const EMPTY_USAGE: UsageDocument;
+/** The warning seam (production: `ctx.logger.warn`; tests: a collector). */
+export type UsageWarn = (message: string) => void;
+/**
+ * Sanitize any parsed usage document. Entry-by-entry: a corrupt counter
+ * becomes zero, a corrupt timestamp becomes `''`, and a non-object document
+ * becomes the empty one. Hand-edited or half-written files therefore cost
+ * precision, never correctness.
+ *
+ * @param raw - the parsed JSON (or anything at all).
+ * @returns a fresh document; the input is never retained.
+ */
+export declare function normalizeUsage(raw: unknown): UsageDocument;
+/**
+ * Fold one dispatch into a document and return the NEXT document (pure — the
+ * input object and its stats are never mutated, so a caller holding a snapshot
+ * keeps it). `firstUsedAt` is stamped on the tool's first call only, so it
+ * stays a true "when did this tool start being used" answer.
+ *
+ * @param doc - the current document.
+ * @param tool - the dispatched tool name.
+ * @param failed - whether the dispatch came back as a structured error.
+ * @param now - ISO timestamp to stamp (default: now).
+ * @returns the next document.
+ */
+export declare function recordUsageCall(doc: UsageDocument, tool: string, failed: boolean, now?: string): UsageDocument;
+/** Total dispatches recorded across every tool. */
+export declare function usageTotalCalls(doc: UsageDocument): number;
+/** Number of tools carrying at least one recorded call. */
+export declare function usageToolCount(doc: UsageDocument): number;
+/**
+ * How many total calls pass before a suggestion batch may fire.
+ * Deliberately coarse: the batch is a remote round trip whose answers are
+ * about prompt economics, not correctness, so it runs on a slow cadence
+ * instead of per call.
+ */
+export declare const SUGGEST_BATCH_EVERY = 20;
+/**
+ * Whether crossing into `totalCalls` opens a new suggestion batch. True only
+ * on the call that MAKES a multiple (20, 40, …), so N calls trigger exactly
+ * floor(N/20) batches and never more — the threshold predicate is a pure
+ * function precisely so the hot path can ask it without any jev work.
+ *
+ * @param totalCalls - total calls AFTER the just-recorded one.
+ * @param every - batch cadence (default {@link SUGGEST_BATCH_EVERY}).
+ * @returns whether a batch should be started.
+ */
+export declare function shouldRunSuggestBatch(totalCalls: number, every?: number): boolean;
+/**
+ * The live usage handle. Reads are served from the in-memory mirror and NEVER
+ * touch the disk; `record` updates the mirror synchronously (so a caller can
+ * threshold on the total it just produced) and schedules an atomic write.
+ *
+ * WRITE POLICY — write-through with coalescing: the first record starts a
+ * write; records arriving while one is in flight are folded into ONE follow-up
+ * write carrying the newest state. So the document on disk is at most one
+ * write cycle behind the mirror, and a crash can lose only the records counted
+ * during that single in-flight write (milliseconds, one tmp+rename pair) — not
+ * an unbounded tail. `flush()` awaits the queue for shutdown/tests.
+ */
+export interface UsageStore {
+    /** Current mirror (corrupt input already sanitized away). */
+    get(): UsageDocument;
+    /** Total calls in the mirror. */
+    total(): number;
+    /** Count one dispatch; returns the new total. Never throws. */
+    record(tool: string, failed: boolean): number;
+    /** Await the pending write(s), if any. */
+    flush(): Promise<void>;
+}
+/**
+ * Build the usage store over one gate directory. The initial read is
+ * synchronous (boot-time, once, mirroring the gate store); writes land
+ * atomically (tmp file + rename) so a crash mid-write can never leave a torn
+ * document.
+ *
+ * @param dir - the plugin's gate directory (`resolveGateDir(...)`).
+ * @param warn - warning seam for a corrupt document / failed write.
+ * @returns the store handle.
+ */
+export declare function createUsageStore(dir: string, warn: UsageWarn): UsageStore;
+/**
+ * One suggestion row. `basis` is the human-readable usage evidence the
+ * suggestion was derived from (calls / errors / recency) — the row is a
+ * PROPOSAL about prompt economics, never an applied config change (red line
+ * ③: the model face writes nothing, and neither does the operator's
+ * settings — `/mcp suggest` only renders).
+ */
+export interface SuggestionRecord {
+    /** The folded tool the row is about. */
+    tool: string;
+    /** jev's calibrated probability that it is worth keeping in every prompt. */
+    probability: number;
+    /** Band the probability fell into (thresholds.ts, kind 'suggest'). */
+    band: JevBand;
+    /** Usage evidence, e.g. `24 calls, 1 error, last used 2026-09-27`. */
+    basis: string;
+    /** ISO time the batch produced this row. */
+    _at: string;
+}
+/**
+ * Sanitize a parsed suggestions document into rows that are safe to render.
+ * Rows without a name or a usable probability are dropped rather than shown as
+ * "0%" — a fabricated number is worse than a missing row.
+ *
+ * @param raw - the parsed JSON (an array of rows, or anything at all).
+ * @returns the renderable rows, in document order.
+ */
+export declare function normalizeSuggestions(raw: unknown): SuggestionRecord[];
+/**
+ * Replace the whole suggestion document with one batch (atomic tmp+rename;
+ * a crash leaves either the previous batch or the new one, never a mix).
+ * Throws on failure — the caller is the fire-and-forget seam, which contains
+ * it; a failed write means "this round's suggestions are lost", never a broken
+ * caller.
+ *
+ * @param dir - the plugin's gate directory.
+ * @param records - the batch rows.
+ */
+export declare function writeSuggestions(dir: string, records: readonly SuggestionRecord[]): Promise<void>;
+/**
+ * Read the current suggestions (empty when there are none, unreadable, or
+ * corrupt — the display layer's "no suggestions yet" is the same shape as
+ * "the file was lost", so the operator is never shown a half-truth).
+ *
+ * @param dir - the plugin's gate directory.
+ * @param warn - optional warning seam for an unreadable document.
+ * @returns the renderable rows.
+ */
+export declare function readSuggestions(dir: string, warn?: UsageWarn): Promise<SuggestionRecord[]>;
+/** One tool the keep-suggestion batch may ask about. */
+export interface SuggestCandidate {
+    /** The folded tool name. */
+    tool: string;
+    /** Recorded dispatches — the evidence a "keep" claim must rest on. */
+    calls: number;
+    /** How many of them failed. */
+    errors: number;
+    /** ISO time of the most recent call. */
+    lastUsedAt: string;
+    /** First {@link SUGGEST_DESCRIPTION_CHARS} chars of the description. */
+    description: string;
+}
+/** How much of a tool's description travels into the jev state text. */
+export declare const SUGGEST_DESCRIPTION_CHARS = 200;
+/** The minimal shape a folded-tool pool must have. */
+export interface DescribableSchema {
+    readonly name: string;
+    readonly description: string;
+}
+/**
+ * The candidate set for one keep-suggestion batch: the tools that are
+ * CURRENTLY FOLDED OUT of the prompt (the fold predicate is injected, so this
+ * function stays free of config plumbing) AND have at least one recorded call.
+ *
+ * A folded tool nobody ever called is deliberately excluded: it has no usage
+ * evidence to build a "keep this in every prompt" claim on, and burning a
+ * remote question on it would put the least informative tools first. Ordered
+ * by calls descending (the tools that already earn their place come first),
+ * name ascending as the tie-break, capped at {@link RANK_CANDIDATE_LIMIT}.
+ *
+ * @param doc - the usage mirror.
+ * @param schemas - visible schemas (production: `ctx.tools.schemas()`).
+ * @param isFolded - the live fold predicate for one name.
+ * @param limit - max candidates (default {@link RANK_CANDIDATE_LIMIT}).
+ * @returns the candidates, most-used first.
+ */
+export declare function usageSuggestCandidates(doc: UsageDocument, schemas: readonly DescribableSchema[], isFolded: (name: string) => boolean, limit?: number): SuggestCandidate[];
+/** The usage evidence rendered next to a suggestion, in one line. */
+export declare function suggestionBasis(candidate: Pick<SuggestCandidate, 'calls' | 'errors' | 'lastUsedAt'>): string;
+/**
+ * The exact `keep` config fragment a suggestion would translate to. Rendered
+ * as TEXT for the operator — nothing writes it (red line ③).
+ *
+ * @param tool - the suggested tool name.
+ * @returns a copy-pasteable keep-pattern line.
+ */
+export declare function keepSuggestionFragment(tool: string): string;