@wirecat/cli-core 0.401.0 → 0.402.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ shape of this file.
 
 ## Unreleased
 
+## 0.402.0 — 24.10.2026
+
+### Changed — may break callers
+
+- **MCP offers `bot api`, behind `bot.api`.** The generated `bot api <operation>` commands (raw calls to Bot API methods, which skip the send guard and the bot's recipient list) are bot MCP tools again, offered only where the profile sets `permissions.bot.api` to `allow`; it is `deny` by default for an MCP server, so nothing changes until the owner turns it on, and a broader `bot: allow` does not lift it. A call made after the owner turned it off is refused naming the key and the terminal command; an agent cannot set the key through `config set` (the guard on `permissions.mcp…` covers `permissions.bot.api`). Breaking for a CLI: `generatedApiCommand` no longer marks the group `mcp: false`, and each operation now declares effects (`remote: read` or `write`), so `commands --json` shows them and a catalogue built with `toolsFromCommands` without `levels` lists the operations; update a pinned bot catalogue and a document that lists what MCP leaves out. Under `<PREFIX>_READ_ONLY` a write operation now refuses on the command line too. The command line's `bot api` is otherwise unchanged.
+
+### Fixed
+
+- **Voice-note search no longer turns an English word into another real English word.** A word in a transcript widens to the spellings speech recognition garbles only past a dictionary of its language: Russian as before, and now English and Spanish, following the store's word-form languages (`search_stemmers`). Before, «cost» also found «cast». A Latin word with no dictionary for its language, and English and Spanish number words, no longer widen.
+
 ## 0.401.0 — 24.10.2026
 
 ### Changed — may break callers

package/dist/cli/bot/api.js

@@ -1,15 +1,18 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { Command, Option } from "commander";
+import { REMOTE_READ, REMOTE_WRITE } from "../effects.js";
 import { apiFlagOf, apiOptionKey, readApiBody } from "./api-input.js";
 export const generatedApiCommand = (api) => {
-    const group = annotate(new Command("api"), { mcp: false }).description(api.description ?? "every operation of the official Bot API, generated from its schema");
+    const group = new Command("api").description(api.description ?? "every operation of the official Bot API, generated from its schema");
     group.option("--store-token <profile>", "keep a returned authentication token only in this bot profile's OS keyring; never print it");
     for (const operation of api.operations) {
         const binding = operation.binding.kind === "http"
             ? `${operation.binding.method} ${operation.binding.path}`
             : operation.binding.name;
-        const command = new Command(operation.command).description(`${operation.summary ?? operation.id} — ${operation.effect} (${binding})`);
+        const command = annotate(new Command(operation.command), {
+            effects: operation.effect === "read" ? REMOTE_READ : REMOTE_WRITE,
+        }).description(`${operation.summary ?? operation.id} — ${operation.effect} (${binding})`);
         for (const parameter of operation.parameters) {
             if (parameter.sensitive)
                 continue;

package/dist/cli/config-command.js

@@ -2,7 +2,7 @@ import { CliError, pathsAreOverridden } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
 import { envName } from "../ports/app.js";
-import { AUTHORITY_KEY } from "../sends/permissions.js";
+import { AUTHORITY_KEY, BOT_API_KEY } from "../sends/permissions.js";
 import { loadSnakeCaseConfig } from "./config-keys.js";
 import { baseContext, environmentOf } from "./context.js";
 import { grantsAuthority, LOCAL_READ, LOCAL_WRITE } from "./effects.js";
@@ -96,7 +96,7 @@ export const configCommand = (app, config, { permissionKey } = {}) => {
                 throw new CliError("permission_error", `this process is locked to profile ${settings.profile} (${lock}) — ${setting === "default_profile" ? setting : "--defaults"} changes other profiles`);
             }
             if (environmentOf(this).agent)
-                refuseAuthorityKey(setting, action === "set" ? String(given) : undefined);
+                refuseGuardedKey(setting, action === "set" ? String(given) : undefined);
             if (action === "set")
                 refuseUnknownKey(this, setting, String(given), permissionKey);
             const saved = config.changeSetting(settings.configPath, {
@@ -137,10 +137,11 @@ export const refuseUnknownKey = (command, setting, value, permissionKey) => {
     }
 };
 /**
- * An agent may hold `mcp.authority` and change other settings, but never the key that let it in: on any profile, in
- * the defaults, or by replacing `permissions` whole. Only the owner, in a terminal, turns it on or off (NEED-1662).
+ * An agent may hold `mcp.authority` or `bot.api` and change other settings, but never the key that let it in: on any
+ * profile, in the defaults, or by replacing `permissions` whole. Only the owner, in a terminal, turns it on or off
+ * (NEED-1662, NEED-1679).
  */
-const refuseAuthorityKey = (setting, value) => {
+const refuseGuardedKey = (setting, value) => {
     const keys = setting.startsWith("permissions.")
         ? [setting.slice("permissions.".length)]
         : setting === "permissions"
@@ -148,9 +149,14 @@ const refuseAuthorityKey = (setting, value) => {
                 ? ["mcp"]
                 : objectKeys(value)
             : [];
-    if (!keys.some((key) => key === "mcp" || key.startsWith("mcp.")))
+    const guarded = keys.some((key) => key === BOT_API_KEY || key.startsWith(`${BOT_API_KEY}.`))
+        ? BOT_API_KEY
+        : keys.some((key) => key === "mcp" || key.startsWith("mcp."))
+            ? AUTHORITY_KEY
+            : undefined;
+    if (!guarded)
         return;
-    throw new CliError("permission_error", `an agent cannot change permissions.${AUTHORITY_KEY} — the owner sets it in a terminal`, { permission: AUTHORITY_KEY });
+    throw new CliError("permission_error", `an agent cannot change permissions.${guarded} — the owner sets it in a terminal`, { permission: guarded });
 };
 /** The keys of a `permissions` object given whole; anything else is left to the schema to refuse. */
 const objectKeys = (value) => {

package/dist/cli/context.d.ts

@@ -87,6 +87,8 @@ export interface AgentRun {
     overrides?: readonly string[];
     /** The server's levels allow `mcp.authority`: a command that changes what a later run may do may run. */
     authority?: boolean;
+    /** The server's levels allow `bot.api`: a raw Bot API call, past the send guard, may run. */
+    botApi?: boolean;
 }
 export interface RelayedRun {
     /** The profile serve holds; a command for another is refused before it touches the connection. */

package/dist/cli/program.js

@@ -11,7 +11,7 @@ import { failureContext } from "../errors/reasons.js";
 import { envName, readOnlyLockOf, readOnlyRefusal } from "../ports/app.js";
 import { recorded, wasSettled } from "../runs/recording.js";
 import { processRun, useAsProcessRun } from "../runs/scope.js";
-import { AUTHORITY_KEY, keyForCommand } from "../sends/permissions.js";
+import { AUTHORITY_KEY, BOT_API_KEY, isBotApi, keyForCommand } from "../sends/permissions.js";
 import { logParsedArgv, logVersion } from "./argv-log.js";
 import { commandPathOf } from "./command-contract.js";
 import { outputFor, provide } from "./context.js";
@@ -258,6 +258,10 @@ const runOnce = async (argv, definition, options) => {
             throw new CliError("permission_error", `\`${command} ${path.join(" ")}\` changes what a later run may do, and this profile keeps that from agents ` +
                 `(${AUTHORITY_KEY}) — the owner turns it on in a terminal: ` +
                 `\`${command} <profile> config set${path[0] === "bot" ? " --bot" : ""} permissions.${AUTHORITY_KEY} allow\``, { permission: AUTHORITY_KEY, sent: false });
+        if (options.agent && options.agent.botApi !== true && isBotApi(path))
+            throw new CliError("permission_error", `\`${command} ${path.join(" ")}\` calls the Bot API directly, past the send guard and the recipient list, ` +
+                `and this profile keeps that from agents (${BOT_API_KEY}) — the owner turns it on in a terminal: ` +
+                `\`${command} <profile> config set --bot permissions.${BOT_API_KEY} allow\``, { permission: BOT_API_KEY, sent: false });
         const { lifetime, cooperative: stopsAtItsPace } = metaOf(action);
         const persistent = lifetime === "persistent";
         listens = persistent;

package/dist/mcp/agent.js

@@ -6,7 +6,7 @@ import { VOCABULARY } from "@wirecat/cli-base/standards/tables";
 import * as v from "valibot";
 import { changesMessenger } from "../cli/effects.js";
 import { lentConnection } from "../cli/messenger/serve-relay.js";
-import { AUTHORITY_KEY, authorityAllowed, keyForCommand, levelFor, readKeysForCommand, } from "../sends/permissions.js";
+import { AUTHORITY_KEY, authorityAllowed, botApiAllowed, isBotApi, keyForCommand, levelFor, readKeysForCommand, } from "../sends/permissions.js";
 const TYPES = new Map(VOCABULARY.flags.map((flag) => [flag.name, flag.type]));
 // `<name|id>` is one argument: its field is `name_or_id`.
 const snake = (name) => name.replaceAll("|", "_or_").replace(/[^a-z0-9]+/gi, "_");
@@ -150,7 +150,8 @@ export const toolsFromCommands = (commands, options = {}) => {
         info.mcp !== false &&
         info.lifetime === undefined &&
         !(readOnly && (changesMessenger(info) || authority?.(info.path))) &&
-        (levels === undefined || refusal(info, levels, keyOf, authority) === undefined))
+        (levels === undefined ||
+            (refusal(info, levels, keyOf, authority) === undefined && (!isBotApi(info.path) || botApiAllowed(levels)))))
         .map((info) => ({
         command: info.path.slice(root.length).join(" "),
         path: info.path,
@@ -230,6 +231,7 @@ export const runCommandForAgent = async (program, path, input, ctx) => {
                 },
                 ...(ctx.overrides?.length ? { overrides: ctx.overrides } : {}),
                 authority: levels !== undefined && authorityAllowed(levels),
+                botApi: levels !== undefined && botApiAllowed(levels),
             },
             // Opened only when the command asks: a read the store answers never connects.
             ...(lend

package/dist/search/dictionary.d.ts

@@ -0,0 +1,20 @@
+/** The Hunspell dictionary that tells a real word from a garbled one, for each language the store stems. */
+export declare const DICTIONARIES: {
+    readonly russian: "dictionary-ru";
+    readonly english: "dictionary-en";
+    readonly spanish: "dictionary-es";
+};
+export type DictionaryLanguage = keyof typeof DICTIONARIES;
+/**
+ * `known`: whether a folded word the index stores is real in one of `languages` that write in its alphabet.
+ * `covers`: whether any of them does; without one, a garbled spelling cannot be told from a real word.
+ */
+export declare const knownWord: (languages: readonly DictionaryLanguage[]) => {
+    covers: (word: string) => boolean;
+    known: (word: string) => boolean;
+};
+/** The dictionaries of the store's stemmers: Russian for Cyrillic, each named Latin stemmer for Latin. */
+export declare const dictionaryLanguages: (stemmers: {
+    cyrillic: string;
+    latin: string;
+}) => DictionaryLanguage[];

package/dist/search/dictionary.js

@@ -0,0 +1,106 @@
+import { readFileSync } from "node:fs";
+import { fold } from "../store/normalize.js";
+/** The Hunspell dictionary that tells a real word from a garbled one, for each language the store stems. */
+export const DICTIONARIES = { russian: "dictionary-ru", english: "dictionary-en", spanish: "dictionary-es" };
+/** `fold`, without Unicode normalisation for plain Russian letters: it would double the time Russian loads in. */
+const folded = (word) => /^[а-яё'-]*$/.test(word) ? word.replaceAll("ё", "е").replaceAll("й", "и") : fold(word);
+const loaded = new Map();
+/**
+ * Hunspell's own check, an affix at a time, instead of nspell's: nspell expands Russian's 146,269 entries into
+ * 1.44 million forms (1.4 s, 172 MB) where this loads in about 0.2 s. The index stores words folded as `normalize`
+ * folds them, so entries, affixes and conditions are folded too; a condition such as `[^ейоь]` then refuses и as
+ * well, which changed none of 12,769 sample words. Continuation classes and compounds are not followed: a word
+ * only they make counts as unknown and may widen.
+ */
+const dictionary = (language) => {
+    const cached = loaded.get(language);
+    if (cached)
+        return cached;
+    const file = (name) => readFileSync(new URL(name, import.meta.resolve(DICTIONARIES[language])), "utf8");
+    const words = new Map();
+    for (const line of file("index.dic").split("\n").slice(1)) {
+        const [entry, flags = ""] = line.trim().split("/");
+        if (!entry)
+            continue;
+        // Names and abbreviations are capitalised in the dictionary; the index is lower case.
+        const spelled = entry.toLowerCase();
+        const key = folded(spelled);
+        words.set(key, (words.get(key) ?? "") + flags);
+    }
+    const suffixes = new Map();
+    const prefixes = new Map();
+    const crosses = new Set();
+    let longest = 0;
+    for (const line of file("index.aff").split("\n")) {
+        const [kind, flag, strip, add, condition] = line.trim().split(/\s+/);
+        if ((kind !== "SFX" && kind !== "PFX") || flag === undefined || strip === undefined || add === undefined)
+            continue;
+        if (!condition) {
+            if (strip === "Y")
+                crosses.add(`${kind}${flag}`);
+            continue;
+        }
+        const affix = folded(add.split("/")[0].replace(/^0$/, ""));
+        const pattern = condition === "." ? "" : folded(condition);
+        const into = kind === "SFX" ? suffixes : prefixes;
+        const rules = into.get(affix) ?? [];
+        rules.push({
+            flag,
+            strip: strip === "0" ? "" : folded(strip),
+            condition: new RegExp(kind === "SFX" ? `${pattern}$` : `^${pattern}`),
+            cross: crosses.has(`${kind}${flag}`),
+        });
+        into.set(affix, rules);
+        longest = Math.max(longest, affix.length);
+    }
+    const made = { words, suffixes, prefixes, longest };
+    loaded.set(language, made);
+    return made;
+};
+const entry = ({ words }, key, rule, also) => {
+    const flags = words.get(key) ?? "";
+    return flags.includes(rule.flag) && (also === undefined || flags.includes(also)) && rule.condition.test(key);
+};
+/** A suffix on a dictionary word; `prefix` is the flag of a prefix already taken off, which both must allow. */
+const suffixed = (found, word, prefix) => {
+    for (let cut = 0; cut <= Math.min(word.length - 1, found.longest); cut++)
+        for (const rule of found.suffixes.get(word.slice(word.length - cut)) ?? [])
+            if ((prefix === undefined || rule.cross) &&
+                entry(found, word.slice(0, word.length - cut) + rule.strip, rule, prefix))
+                return true;
+    return false;
+};
+const spelled = (language, word) => {
+    const found = dictionary(language);
+    if (found.words.has(word) || suffixed(found, word))
+        return true;
+    for (let cut = 1; cut <= Math.min(word.length - 1, found.longest); cut++)
+        for (const rule of found.prefixes.get(word.slice(0, cut)) ?? []) {
+            const rest = rule.strip + word.slice(cut);
+            if (entry(found, rest, rule) || (rule.cross && suffixed(found, rest, rule.flag)))
+                return true;
+        }
+    return false;
+};
+const CYRILLIC = /\p{Script=Cyrillic}/u;
+const SCRIPT_OF = {
+    russian: "cyrillic",
+    english: "latin",
+    spanish: "latin",
+};
+/**
+ * `known`: whether a folded word the index stores is real in one of `languages` that write in its alphabet.
+ * `covers`: whether any of them does; without one, a garbled spelling cannot be told from a real word.
+ */
+export const knownWord = (languages) => {
+    const byScript = (word) => {
+        const script = CYRILLIC.test(word) ? "cyrillic" : "latin";
+        return languages.filter((language) => SCRIPT_OF[language] === script);
+    };
+    return {
+        covers: (word) => byScript(word).length > 0,
+        known: (word) => byScript(word).some((language) => spelled(language, word)),
+    };
+};
+/** The dictionaries of the store's stemmers: Russian for Cyrillic, each named Latin stemmer for Latin. */
+export const dictionaryLanguages = (stemmers) => [stemmers.cyrillic, ...stemmers.latin.split(",")].filter((name) => Object.hasOwn(DICTIONARIES, name));

package/dist/sends/permissions.d.ts

@@ -21,6 +21,15 @@ export declare const DEFAULT_PERMISSIONS: Readonly<Record<PermissionKey, Level>>
 export declare const AUTHORITY_KEY: PermissionKey;
 /** Whether these levels let an agent run a command that changes what a later run may do; `ask` does, as for any write. */
 export declare const authorityAllowed: (levels: Readonly<Record<PermissionKey, Level>>) => boolean;
+/** Lets an MCP server offer `bot api`, whose calls skip the send guard and the bot's recipient list (NEED-1679). */
+export declare const BOT_API_KEY: PermissionKey;
+export declare const isBotApi: (path: readonly string[]) => boolean;
+/**
+ * Deny by default for an MCP server only: the key stays out of `DEFAULT_PERMISSIONS` because the command line's
+ * `bot api` is checked per operation (`bot.api.<operation>`), and a default there would deny it for the owner too.
+ * A broader `bot: allow` does not lift it; `ask` goes ahead over MCP, as for any write.
+ */
+export declare const botApiAllowed: (levels: Readonly<Record<PermissionKey, Level>>) => boolean;
 /** The resources at the top of the command tree, which `readOnly` and `allow` turn read-only as a whole. */
 export declare const RESOURCES: readonly ["messages", "reactions", "polls", "topics", "chats", "contacts", "account", "bot", "conversations", "tags", "mentions", "search", "searches", "tasks", "replies", "attachments", "stats", "store", "metadata", "mcp", "server", "models", "schedule", "doctor", "images"];
 /** The command path an old `allow` word stood for, as one key — what an MCP tool's `permission` is checked against. */

package/dist/sends/permissions.js

@@ -107,6 +107,18 @@ export const authorityAllowed = (levels) => {
     const { level } = levelFor(levels, AUTHORITY_KEY);
     return level === "allow" || level === "ask";
 };
+/** Lets an MCP server offer `bot api`, whose calls skip the send guard and the bot's recipient list (NEED-1679). */
+export const BOT_API_KEY = "bot.api";
+export const isBotApi = (path) => path[0] === "bot" && path[1] === "api";
+/**
+ * Deny by default for an MCP server only: the key stays out of `DEFAULT_PERMISSIONS` because the command line's
+ * `bot api` is checked per operation (`bot.api.<operation>`), and a default there would deny it for the owner too.
+ * A broader `bot: allow` does not lift it; `ask` goes ahead over MCP, as for any write.
+ */
+export const botApiAllowed = (levels) => {
+    const { level } = levelFor(levels, BOT_API_KEY, { ...DEFAULT_PERMISSIONS, [BOT_API_KEY]: "deny" });
+    return level === "allow" || level === "ask";
+};
 /** The resources at the top of the command tree, which `readOnly` and `allow` turn read-only as a whole. */
 export const RESOURCES = [
     "messages",

package/dist/store/sqlite/transcript-query.js

@@ -1,5 +1,5 @@
+import { dictionaryLanguages, knownWord } from "../../search/dictionary.js";
 import { isNumberWord, widenWords } from "../../search/garbled.js";
-import { knownRussianWord } from "../../search/russian-dictionary.js";
 import { createStemmer, DEFAULT_STEMMERS, STEM_SEPARATOR } from "../../search/stem.js";
 import { normalize } from "../normalize.js";
 import { ftsMatch, quoted, SPEECH, stemMatch } from "./lucene-fields.js";
@@ -9,6 +9,13 @@ const predicates = (node) => node.kind === "predicate" ? [node] : node.clauses.f
 const readsTranscripts = (node) => (node.operator === "term" || node.operator === "phrase") &&
     /[\p{L}\p{N}]/u.test(normalize(node.value)) &&
     (node.field === "transcript" || (node.implicit === true && (node.field === "text" || node.field === "exact")));
+/** `isNumberWord` knows Russian numbers only; a widened number is a wrong fact in any language. */
+const LATIN_NUMBERS = new Set(`zero one two three four five six seven eight nine ten eleven twelve twenty thirty forty fifty sixty seventy
+  eighty ninety hundred thousand million billion first second third fourth fifth sixth seventh eighth ninth tenth
+  half quarter cero uno una dos tres cuatro cinco seis siete ocho nueve diez once doce veinte treinta cuarenta
+  cincuenta sesenta setenta ochenta noventa cien ciento mil millon primero segundo tercero cuarto quinto medio`.split(/\s+/));
+/** A word widens when its alphabet has a dictionary to tell a garbled spelling from another real word. */
+const widens = (word, covered) => covered(word) && !isNumberWord(word) && !LATIN_NUMBERS.has(word);
 /**
  * Each leaf that reads transcripts, with what it matches there. A transcript always widens, not only when nothing
  * matched as typed text does: a correct and a garbled spelling sit in one chat. Only a single word widens —
@@ -20,7 +27,9 @@ export const transcriptTerms = (database, root, item) => {
     const saved = savedStemmers(database);
     if (item !== "message" || !leaves.length || saved === null)
         return terms;
-    const stemmer = createStemmer(saved ?? DEFAULT_STEMMERS);
+    const stemmers = saved ?? DEFAULT_STEMMERS;
+    const stemmer = createStemmer(stemmers);
+    const dictionary = knownWord(dictionaryLanguages(stemmers));
     const stemsOf = (word) => [...new Set(stemmer.explain(word).map((part) => part.stem))];
     const widening = [];
     for (const [node, one] of terms) {
@@ -31,8 +40,9 @@ export const transcriptTerms = (database, root, item) => {
         if (stems)
             Object.assign(one, { stems: node.slop === undefined ? stems : `(${stems}) NOT ${quoted(STEM_SEPARATOR)}` });
         const words = normalize(node.value).match(/[\p{L}\p{N}]+/gu) ?? [];
-        if (node.operator === "term" && words.length === 1 && !isNumberWord(words[0]))
-            widening.push({ node, literal: words[0], stems: stemsOf(node.value) });
+        const [word] = words;
+        if (node.operator === "term" && word !== undefined && words.length === 1 && widens(word, dictionary.covers))
+            widening.push({ node, literal: word, stems: stemsOf(node.value) });
     }
     if (!widening.length)
         return terms;
@@ -40,7 +50,7 @@ export const transcriptTerms = (database, root, item) => {
         .prepare("SELECT term, doc FROM transcript_words_vocab WHERE col = 'normalized_text'")
         .all()
         .map((row) => ({ term: String(row.term), docs: Number(row.doc) }));
-    widenWords(widening, vocabulary, stemsOf, knownRussianWord).forEach((words, at) => {
+    widenWords(widening, vocabulary, stemsOf, dictionary.known).forEach((words, at) => {
         const leaf = widening[at];
         if (leaf)
             Object.assign(terms.get(leaf.node), { widened: words });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.401.0",
+  "version": "0.402.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -173,6 +173,8 @@
     "@xmldom/xmldom": "0.9.12",
     "chardet": "2.2.0",
     "defuddle": "0.19.5",
+    "dictionary-en": "4.0.0",
+    "dictionary-es": "4.0.0",
     "dictionary-ru": "3.0.0",
     "echarts": "6.1.0",
     "fflate": "0.8.3",