@wirecat/cli-core 0.398.0 → 0.400.0

package/dist/cli/messenger/messages-edit-command.js

@@ -11,6 +11,7 @@ export const editCommand = (messenger) => {
     const edit = annotate(new Command("edit"), {
         examples: [`${messenger.app.command} personal messages edit "Book club" 101 "The meeting starts at 11."`],
         effects: REMOTE_WRITE,
+        output: { entity: "message_write" },
     })
         .description("change the text of your own message; the other side may have read it already")
         .argument("<chat>", messenger.chatArgument)

package/dist/cli/messenger/messages-evidence-command.js

@@ -7,10 +7,12 @@ import { positiveCount } from "../paging.js";
 import { messengerContext } from "./context.js";
 import { evidenceAnswer } from "./message-answers.js";
 export const evidenceCommand = (messenger) => annotate(new Command("evidence"), {
+    output: { entity: "evidence_packet" },
     examples: [`${messenger.app.command} personal messages evidence "Book club" --limit 10`],
     effects: LOCAL_READ,
 })
-    .description("a bounded evidence packet from stored messages, newest first")
+    .summary("a recent-chat evidence packet from stored messages")
+    .description("general chat context, newest first, with references, coverage and fingerprints for verification")
     .argument("<chat>", messenger.chatArgument)
     .option("--limit <n>", "how many, 1–100", positiveCount("--limit"))
     .option("--cursor <cursor>", "go on from where page.next says the last packet stopped")

package/dist/cli/messenger/messages-forward-command.js

@@ -9,6 +9,7 @@ export const forwardCommand = (messenger) => {
     const forward = annotate(new Command("forward"), {
         examples: [`${messenger.app.command} personal messages forward "Book club" 101 --to "Project room"`],
         effects: REMOTE_WRITE,
+        output: { entity: "message_write" },
     })
         .description("forward one message to another chat")
         .argument("<chat>", `the chat the message is in: ${messenger.chatArgument}`)

package/dist/cli/messenger/messages-pin-command.js

@@ -10,6 +10,7 @@ export const pinCommand = (messenger) => {
     const durations = messenger.pinDurations?.length ? messenger.pinDurations : undefined;
     const command = annotate(new Command("pin"), {
         effects: REMOTE_WRITE,
+        output: { entity: "message_pin" },
         examples: [
             `${tool} messages pin <chat> <message>`,
             ...(quiet ? [`${tool} messages pin <chat> <message> --notify`] : []),
@@ -38,6 +39,7 @@ export const pinCommand = (messenger) => {
 };
 export const unpinCommand = (messenger) => annotate(new Command("unpin"), {
     effects: REMOTE_WRITE,
+    output: { entity: "message_pin" },
     examples: [`${messenger.app.command} messages unpin <chat> <message>`],
 })
     .description("unpin a message in a chat")
@@ -53,6 +55,7 @@ export const starCommands = (messenger) => [true, false].map((starred) => {
     const name = starred ? "star" : "unstar";
     return annotate(new Command(name), {
         effects: REMOTE_WRITE,
+        output: { entity: "message_star" },
         examples: [`${messenger.app.command} messages ${name} <chat> <message>`],
     })
         .description(starred ? "star a message, so it is easy to find again; only you see the star" : "take the star off a message")

package/dist/cli/messenger/messages-send-command.js

@@ -19,6 +19,7 @@ export const sendCommand = (messenger) => {
     const send = annotate(new Command("send"), {
         examples: [`${messenger.app.command} personal messages send "Book club" "The meeting starts at 10."`],
         effects: REMOTE_WRITE,
+        output: { entity: "message_write" },
     })
         .description("send a text message; without [text], the text is read from stdin")
         .argument("<chat>", messenger.chatArgument)

package/dist/cli/messenger/messages-stats-command.js

@@ -12,7 +12,7 @@ export const messagesStatsCommand = (messenger) => syncOptions(annotate(new Comm
     .summary("count stored messages by chat, sender, day or hour")
     .description(`how many stored messages match, by chat, sender, day or hour — the local store only${syncsFirst(messenger) ? "; optionally fetches new messages with --sync-first" : ""}`)
     .argument("[query...]", "a strict Lucene query, as for search messages; none counts every stored message; with --saved, more words AND-ed to it")
-    .option("--by <chat|sender|day|hour>", "what to count by (default: chat)", groupingOf)
+    .option("--by <group>", "count by chat, sender, day or hour (default: chat)", groupingOf)
     .option("--chat <chat>", `only this chat — the same as chat: in the query; ${messenger.chatArgument}`)
     .option("--source <accounts>", "every account of this messenger held in the store; personal, bots or all — the same as in: in the query")
     .option("--limit <n>", "how many rows", positiveCount("--limit"))

package/dist/cli/messenger/metadata-command.js

@@ -8,7 +8,11 @@ import { messengerContext, refuseLocalWrite } from "./context.js";
 export const metadataCommand = (messenger) => {
     const tool = messenger.app.command;
     const command = new Command("metadata").description("cached group/channel descriptions for local automatic tags");
-    annotate(command.command("get"), { effects: LOCAL_READ, examples: [`${tool} metadata get --chat 7`] })
+    annotate(command.command("get"), {
+        output: { entity: "chat_metadata" },
+        effects: LOCAL_READ,
+        examples: [`${tool} metadata get --chat 7`],
+    })
         .description("a stored chat's cached description, as automatic tags read it")
         .requiredOption("--chat <chat>", "a stored chat")
         .action(async function () {
@@ -17,13 +21,14 @@ export const metadataCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(await context.withServices((services) => services.metadata.get(chat)))));
     });
     annotate(command.command("refresh"), {
+        output: { entity: "chat_metadata_refresh" },
         effects: FETCH,
         examples: [`${tool} metadata refresh --chat 7 --chat 8`, `${tool} metadata refresh --only-missing --limit 20`],
     })
         .description("fetch group and channel descriptions again and cache them")
         .option("--chat <chat>", "stored group/channel; repeat for several", (value, previous) => [...previous, value], [])
         .option("--only-missing", "only chats with no metadata yet; without --chat, every stored group/channel")
-        .option("--limit <number>", "process at most 1–500 chats", positiveCount("--limit"), 50)
+        .option("--limit <n>", "process at most 1–500 chats", positiveCount("--limit"), 50)
         .action(async function () {
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, "metadata.refresh");

package/dist/cli/messenger/models-command.js

@@ -145,7 +145,11 @@ export const modelsCommand = (messenger) => {
         }, { unbounded: true });
     });
     const key = text.command("key").description("API keys for embedding and analysis providers");
-    grantsAuthority(annotate(key.command("set"), { effects: LOCAL_WRITE, examples: [`${tool} models text key set openai`] }))
+    grantsAuthority(annotate(key.command("set"), {
+        effects: LOCAL_WRITE,
+        output: { entity: "model_key", view: "stored" },
+        examples: [`${tool} models text key set openai`],
+    }))
         .argument("<provider>", "openai, anthropic, or the host of a --base-url server that wants a key")
         .description("store a key, typed at a hidden prompt or piped on stdin — never as an argument")
         .action(async function (provider) {
@@ -159,7 +163,11 @@ export const modelsCommand = (messenger) => {
             renderAnswer(this, context, itemOf({ provider, stored: source }));
         });
     });
-    grantsAuthority(annotate(key.command("remove"), { effects: LOCAL_WRITE, examples: [`${tool} models text key remove openai`] }))
+    grantsAuthority(annotate(key.command("remove"), {
+        effects: LOCAL_WRITE,
+        output: { entity: "model_key", view: "removed" },
+        examples: [`${tool} models text key remove openai`],
+    }))
         .argument("<provider>", "openai, anthropic, or a server's host")
         .description("forget a stored key")
         .action(async function (provider) {

package/dist/cli/messenger/polls-command.js

@@ -23,6 +23,7 @@ export const pollsCommand = (messenger) => {
         ? "read a poll, vote in it, create one"
         : "read a poll, vote in it, close your own, create one");
     annotate(polls.command("show"), {
+        output: { entity: "poll" },
         effects: REMOTE_READ,
         examples: [`${messenger.app.command} personal polls show "Book club" 101`],
     })
@@ -67,6 +68,7 @@ export const pollsCommand = (messenger) => {
             }), lines(({ voted_at, person_id, name, answers }) => [voted_at, name ?? person_id, answers.join(",")].join("  ")));
         }));
     annotate(polls.command("vote"), {
+        output: { entity: "poll_change" },
         effects: REMOTE_WRITE,
         examples: [`${messenger.app.command} personal polls vote "Book club" 101 0`],
     })
@@ -95,6 +97,7 @@ export const pollsCommand = (messenger) => {
     });
     if (messenger.pollClose !== false)
         annotate(polls.command("close"), {
+            output: { entity: "poll_change" },
             effects: REMOTE_WRITE,
             examples: [`${messenger.app.command} personal polls close "Book club" 101`],
         })
@@ -107,6 +110,7 @@ export const pollsCommand = (messenger) => {
             renderAnswer(this, context, itemOf(snakeKeys(closed)));
         });
     const create = annotate(polls.command("create"), {
+        output: { entity: "message_write" },
         effects: REMOTE_WRITE,
         examples: [`${messenger.app.command} personal polls create "Book club" "Which day?" Monday Tuesday`],
     })

package/dist/cli/messenger/private-people-command.js

@@ -14,7 +14,7 @@ const NOTES_QUERY = unfilteredQuery("contact_note", contactNote);
 const everyNote = (command, items) => listOf(command, { items, limit: Math.max(1, items.length), has_more: false });
 export const privatePeopleCommands = (messenger) => {
     const alias = new Command("alias").description("a private local display name in the selected account");
-    annotate(alias.command("set"), { effects: LOCAL_WRITE })
+    annotate(alias.command("set"), { effects: LOCAL_WRITE, output: { entity: "contact_alias" } })
         .description("your own name for a person in this account; kept on this machine, never sent")
         .argument("<person>", "the person's id, reference or known name")
         .argument("<alias>", "the private name to use for this person")
@@ -23,7 +23,7 @@ export const privatePeopleCommands = (messenger) => {
         refuseLocalWrite(context, messenger.app.command, "contacts.alias.set");
         renderAnswer(this, context, itemOf(snakeKeys(await context.withServices((services) => services.privatePeople.alias(person, value)))));
     });
-    annotate(alias.command("rm"), { effects: LOCAL_WRITE })
+    annotate(alias.command("rm"), { effects: LOCAL_WRITE, output: { entity: "contact_alias" } })
         .description("drop your local name for a person; their own name shows again")
         .argument("<person>", "the person's id, reference or known name")
         .action(async function (person) {
@@ -54,10 +54,11 @@ export const privatePeopleCommands = (messenger) => {
             output: { entity: "contact_note" },
         }), { name: "text", description: "the note's text" })
             .description(name === "add"
-            ? "add a private note on a person from stdin or --file; never sent"
+            ? "add a private note on a person from stdin or --text-file; never sent"
             : "replace a note's text; --revision must match the one you read")
             .argument("<person>", "the person's id, reference or known name")
-            .addOption(ownerOnlyOption("--file <path>", "read note text from a file; omitted or - reads stdin"));
+            .addOption(ownerOnlyOption("--text-file <path>", "read note text from a file; omitted or - reads stdin").conflicts("file"))
+            .addOption(ownerOnlyOption("--file <path>", "compatibility alias for --text-file").hideHelp().conflicts("textFile"));
         if (name === "edit")
             command
                 .argument("<id>", "the note id from contacts notes list")
@@ -65,7 +66,8 @@ export const privatePeopleCommands = (messenger) => {
         command.action(async function (person, id) {
             const context = messengerContext(this, messenger);
             refuseLocalWrite(context, messenger.app.command, `contacts.notes.${name}`);
-            const { file, revision } = this.opts();
+            const { textFile, file: legacyFile, revision, } = this.opts();
+            const file = textFile ?? legacyFile;
             const text = file === undefined || file === "-" ? await readAll(context.stdin) : await readFile(file, "utf8");
             const version = Number(revision);
             if (name === "edit" && (!Number.isSafeInteger(version) || version < 1))
@@ -76,7 +78,7 @@ export const privatePeopleCommands = (messenger) => {
             renderAnswer(this, context, itemOf(saved));
         });
     }
-    annotate(notes.command("remove"), { effects: LOCAL_WRITE })
+    annotate(notes.command("remove"), { effects: LOCAL_WRITE, output: { entity: "contact_note_removal" } })
         .description("delete one private note on a person")
         .argument("<person>", "the person's id, reference or known name")
         .argument("<id>", "the note id from contacts notes list")

package/dist/cli/messenger/rankings-command.js

@@ -12,6 +12,7 @@ import { renderAnswer } from "../envelope.js";
 import { positiveCount } from "../paging.js";
 import { messengerContext } from "./context.js";
 import { syncOptions, syncRequest } from "./search-sync-options.js";
+import { statisticsQuery, withStatisticsQuery } from "./statistics-query.js";
 import { evidenceAnswer, rankingAnswer, refuseJsonl } from "./stats-answers.js";
 const selectionOf = (value) => {
     if (Buffer.byteLength(value) > RANKING_SELECTION_BYTES)
@@ -35,28 +36,22 @@ export const rankingsTopCommand = (messenger, target) => {
         "engaging",
     ]))
         .option("--weights <json>", "the complete component weights; replaces preset weights")
-        .addOption(new Option("--message-kind <kind>", "select proven all, posts or comments before ranking").choices([
-        "all",
-        "posts",
-        "comments",
-    ]))
-        .option("--chat <chat>", `only this chat; ${messenger.chatArgument}`)
         .option("--source <accounts>", "every held account of this messenger; personal, bots or all")
         .option("--timezone <zone>", "the IANA timezone for dates and active days")
-        .option("--exact", "bare words match exact forms rather than stems")
         .option("--limit <n>", "ranked rows, 1–100", positiveCount("--limit"))
         .option("--saved <name|id>", "run a saved query or ranking run; typed options replace stored options");
-    if (target === "contacts")
-        command.option("--min-messages <n>", "minimum selected messages per author; 1, or 5 for engaging", positiveCount("--min-messages"));
+    const report = target === "contacts" ? "contacts-top" : "messages-top";
+    withStatisticsQuery(command, report);
     command.action(async function (words) {
+        const filters = statisticsQuery(words, report);
         const context = messengerContext(this, messenger);
         refuseJsonl(context.format);
         const options = this.opts();
         const { saved, ...typed } = options;
-        let params = { ...typed, ...(words.length ? { text: words.join(" ") } : {}) };
+        let params = { ...typed, ...filters };
         const found = await context.withServices(async (services) => {
             if (saved !== undefined)
-                params = (await services.searches.resolve(saved, { ...params, text: words.join(" ") })).params;
+                params = (await services.searches.resolve(saved, { ...params, text: filters.text ?? "" })).params;
             if (params.target !== undefined && params.target !== target)
                 throw new CliError("validation_error", "saved ranking belongs to a different target");
             if (params.newest || params.context)

package/dist/cli/messenger/reactions-command.js

@@ -8,6 +8,7 @@ export const reactionsCommand = (messenger) => {
     const reactions = new Command("reactions").description("react to messages");
     annotate(reactions.command("add"), {
         effects: REMOTE_WRITE,
+        output: { entity: "reaction_change" },
         examples: [`${messenger.app.command} personal reactions add "Book club" 101 👍`],
     })
         .description("put your reaction on a message; it replaces the one you had")
@@ -21,6 +22,7 @@ export const reactionsCommand = (messenger) => {
     });
     annotate(reactions.command("remove"), {
         effects: REMOTE_WRITE,
+        output: { entity: "reaction_change" },
         examples: [`${messenger.app.command} personal reactions remove "Book club" 101`],
     })
         .description("take your reaction off a message")

package/dist/cli/messenger/recipients-query.d.ts

@@ -0,0 +1,5 @@
+import { type QueryRegistry } from "@wirecat/cli-base/query";
+import type { RecipientFilter } from "../../sends/recipients.js";
+import { type QueryWords } from "../list-query.js";
+export declare const RECIPIENTS_QUERY: QueryRegistry;
+export declare const recipientFilter: (words: QueryWords) => RecipientFilter;

package/dist/cli/messenger/recipients-query.js

@@ -0,0 +1,18 @@
+import { queryFieldsOf } from "@wirecat/cli-base/query";
+import { recipient } from "../../entities/index.js";
+import { queryTerms } from "../list-query.js";
+export const RECIPIENTS_QUERY = {
+    entity: "recipient",
+    backend: "native",
+    fields: queryFieldsOf(recipient, {
+        native: ["id", "title"],
+        examples: { id: "id:7", title: 'title:"Book club"' },
+    }).map((field) => field.native
+        ? { ...field, operators: field.operators.filter((operator) => operator === "term" || operator === "phrase") }
+        : field),
+};
+export const recipientFilter = (words) => {
+    const terms = queryTerms(words, RECIPIENTS_QUERY, "recipients list");
+    const id = terms.get("id"), title = terms.get("title");
+    return { ...(id === undefined ? {} : { id }), ...(title === undefined ? {} : { title }) };
+};

package/dist/cli/messenger/records-command.js

@@ -83,6 +83,7 @@ export const callsCommand = (messenger) => {
 /** `chats delete` and `chats clear` — for this account only; at the default level they ask first. */
 export const chatDeletionCommands = (messenger) => [
     annotate(new Command("delete"), {
+        output: { entity: "chat_removal" },
         effects: REMOTE_WRITE,
         mcp: false,
         examples: [`${messenger.app.command} personal chats delete "Book club"`],
@@ -95,6 +96,7 @@ export const chatDeletionCommands = (messenger) => [
         renderAnswer(this, context, itemOf(snakeKeys(await context.withServices((services) => services.admin.deleteChat(chat)))));
     }),
     annotate(new Command("clear"), {
+        output: { entity: "chat_removal" },
         effects: REMOTE_WRITE,
         mcp: false,
         examples: [`${messenger.app.command} personal chats clear "Book club"`],
@@ -110,6 +112,7 @@ export const chatDeletionCommands = (messenger) => [
 /** `chats mute` and `unmute` — the owner's own notifications for one chat; nobody in it is told. */
 export const muteCommands = (messenger) => [
     annotate(new Command("mute"), {
+        output: { entity: "chat_muting" },
         effects: REMOTE_WRITE,
         examples: [
             `${messenger.app.command} chats mute "Book club"`,
@@ -126,6 +129,7 @@ export const muteCommands = (messenger) => [
         renderAnswer(this, context, itemOf(snakeKeys(await context.withServices((services) => services.account.mute(chat, when)))));
     }),
     annotate(new Command("unmute"), {
+        output: { entity: "chat_muting" },
         effects: REMOTE_WRITE,
         examples: [`${messenger.app.command} chats unmute "Book club"`],
     })
@@ -136,7 +140,8 @@ export const muteCommands = (messenger) => [
         renderAnswer(this, context, itemOf(snakeKeys(await context.withServices((services) => services.account.mute(chat, null)))));
     }),
 ];
-const onChatCommand = (messenger, name, description, change) => annotate(new Command(name), {
+const onChatCommand = (messenger, name, description, entity, change) => annotate(new Command(name), {
+    output: { entity },
     effects: REMOTE_WRITE,
     examples: [`${messenger.app.command} chats ${name} 123456789`],
 })
@@ -148,16 +153,16 @@ const onChatCommand = (messenger, name, description, change) => annotate(new Com
 });
 /** `chats archive` and `unarchive` — the messenger's archive of chats, not the local store. */
 export const archiveCommands = (messenger) => [
-    onChatCommand(messenger, "archive", "move a chat into the archive; nobody in it is told", (services, chat) => services.account.archive(chat, true)),
-    onChatCommand(messenger, "unarchive", "bring an archived chat back to the chat list", (services, chat) => services.account.archive(chat, false)),
+    onChatCommand(messenger, "archive", "move a chat into the archive; nobody in it is told", "chat_archive", (services, chat) => services.account.archive(chat, true)),
+    onChatCommand(messenger, "unarchive", "bring an archived chat back to the chat list", "chat_archive", (services, chat) => services.account.archive(chat, false)),
 ];
 /** `chats pin` and `unpin` — where the chat sits in the owner's list; `messages pin` pins a message for everyone. */
 export const chatPinCommands = (messenger) => [
-    onChatCommand(messenger, "pin", "keep a chat at the top of your chat list; nobody in it is told", (services, chat) => services.account.pinChat(chat, true)),
-    onChatCommand(messenger, "unpin", "let a pinned chat move down the chat list again", (services, chat) => services.account.pinChat(chat, false)),
+    onChatCommand(messenger, "pin", "keep a chat at the top of your chat list; nobody in it is told", "chat_pin", (services, chat) => services.account.pinChat(chat, true)),
+    onChatCommand(messenger, "unpin", "let a pinned chat move down the chat list again", "chat_pin", (services, chat) => services.account.pinChat(chat, false)),
 ];
 /** `chats mark-unread` — undone by `chats mark-read`, which the other side does see. */
-export const markUnreadCommand = (messenger) => onChatCommand(messenger, "mark-unread", "mark a chat unread on your own devices; nobody in it is told", (services, chat) => services.account.markUnread(chat));
+export const markUnreadCommand = (messenger) => onChatCommand(messenger, "mark-unread", "mark a chat unread on your own devices; nobody in it is told", "chat_unread", (services, chat) => services.account.markUnread(chat));
 const AUDIENCES = ["everyone", "contacts", "nobody"];
 const audienceOf = (flag, value) => {
     if (!AUDIENCES.includes(value))
@@ -202,6 +207,7 @@ export const privacyCommand = (messenger) => {
     const keys = messenger.privacySettings ?? PRIVACY_SETTINGS;
     const privacy = new Command("privacy").description("who may find, call or add the account");
     annotate(privacy.command("show"), {
+        output: { entity: "account_privacy" },
         effects: REMOTE_READ,
         examples: [`${tool} account privacy show`, `${tool} account privacy show --json`],
     })
@@ -214,6 +220,7 @@ export const privacyCommand = (messenger) => {
     const audience = keys.find((key) => !SWITCHES.has(key));
     const toggle = keys.find((key) => SWITCHES.has(key));
     const set = annotate(new Command("set"), {
+        output: { entity: "account_privacy_change" },
         effects: REMOTE_WRITE,
         examples: [audience, toggle].flatMap((key) => (key === undefined ? [] : [exampleOf(tool, key)])),
     }).description("change who may find, call or add the account; the settings not named stay");

package/dist/cli/messenger/replies-edit-command.d.ts

@@ -1,5 +1,5 @@
 import { Command } from "commander";
 import { type Messenger } from "./context.js";
-export declare const REPLY_EDIT_OPTIONS: readonly [readonly ["--do <actions>", "actions: reply, task, or both, comma-separated"], readonly ["--kinds <kinds>", "chat kinds: dialog, group; comma-separated, empty for any"], readonly ["--allow-chats <ids>", "only these chat ids, comma-separated; empty for any"], readonly ["--deny-chats <ids>", "leave these chat ids out, comma-separated; empty clears"], readonly ["--words <words>", "match any of these whole words, comma-separated; empty clears"], readonly ["--question", "match only questions"], readonly ["--no-question", "do not require a question"], readonly ["--mentions-me", "require a mention of you or a reply to you"], readonly ["--no-mentions-me", "do not require a mention of you or a reply to you"], readonly ["--allow-people <ids>", "only these sender ids, comma-separated; empty for any"], readonly ["--deny-people <ids>", "leave these sender ids out, comma-separated; empty clears"], readonly ["--contacts-only", "match only contacts"], readonly ["--no-contacts-only", "do not require a contact"], readonly ["--template <text>", "the reply template"], readonly ["--model <mode>", "legacy template mode: fill-only or may-reword; use ai blocks instead"], readonly ["--as-reply", "send as a reply to the matched message"], readonly ["--no-as-reply", "send without linking to the matched message"], readonly ["--per-chat <limit>", "at most this many per chat, such as 1/12h"], readonly ["--per-person <limit>", "at most this many per person, such as 1/1d"], readonly ["--outside <hours>", "answer outside this 24-hour window, such as 09:00-19:00"], readonly ["--days <days>", "days of the working window, such as mon-fri or sat,sun"], readonly ["--timezone <zone>", "the IANA timezone for the working window"], readonly ["--no-hours", "clear the working window"]];
+export declare const REPLY_EDIT_OPTIONS: readonly [readonly ["--do <actions>", "actions: reply, task, or both, comma-separated"], readonly ["--kinds <kinds>", "chat kinds: dialog, group; comma-separated, empty for any"], readonly ["--allow-chats <ids>", "only these chat ids, comma-separated; empty for any"], readonly ["--deny-chats <ids>", "leave these chat ids out, comma-separated; empty clears"], readonly ["--words <words>", "match any of these whole words, comma-separated; empty clears"], readonly ["--question", "match only questions"], readonly ["--no-question", "do not require a question"], readonly ["--mentions-me", "require a mention of you or a reply to you"], readonly ["--no-mentions-me", "do not require a mention of you or a reply to you"], readonly ["--allow-people <ids>", "only these sender ids, comma-separated; empty for any"], readonly ["--deny-people <ids>", "leave these sender ids out, comma-separated; empty clears"], readonly ["--contacts-only", "match only contacts"], readonly ["--no-contacts-only", "do not require a contact"], readonly ["--template <text>", "the reply template"], readonly ["--template-mode <mode>", "legacy template mode: fill-only or may-reword; use ai blocks instead"], readonly ["--as-reply", "send as a reply to the matched message"], readonly ["--no-as-reply", "send without linking to the matched message"], readonly ["--per-chat <limit>", "at most this many per chat, such as 1/12h"], readonly ["--per-person <limit>", "at most this many per person, such as 1/1d"], readonly ["--outside <hours>", "answer outside this 24-hour window, such as 09:00-19:00"], readonly ["--days <days>", "days of the working window, such as mon-fri or sat,sun"], readonly ["--timezone <zone>", "the IANA timezone for the working window"], readonly ["--no-hours", "clear the working window"]];
 export declare const REPLY_AUDIENCE_OPTIONS: readonly [readonly ["--reply <mode>", "answer all or only listed senders and chats: all, listed"], readonly ["--allow-people <ids>", "replace allowed sender ids, comma-separated; empty clears"], readonly ["--allow-chats <ids>", "replace allowed chat ids, comma-separated; empty clears"], readonly ["--deny-people <ids>", "replace denied sender ids, comma-separated; empty clears; deny wins"], readonly ["--deny-chats <ids>", "replace denied chat ids, comma-separated; empty clears; deny wins"]];
 export declare const addReplyEditors: (replies: Command, messenger: Messenger) => void;

package/dist/cli/messenger/replies-edit-command.js

@@ -1,5 +1,5 @@
 import { annotate } from "@wirecat/cli-base/commands";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { addRule, editAudience, editRule, switchRule } from "../../replies/edit.js";
 import { audienceWarnings, repliesPathFor } from "../../replies/rules.js";
 import { grantsAuthority, LOCAL_WRITE } from "../effects.js";
@@ -20,7 +20,7 @@ export const REPLY_EDIT_OPTIONS = [
     ["--contacts-only", "match only contacts"],
     ["--no-contacts-only", "do not require a contact"],
     ["--template <text>", "the reply template"],
-    ["--model <mode>", "legacy template mode: fill-only or may-reword; use ai blocks instead"],
+    ["--template-mode <mode>", "legacy template mode: fill-only or may-reword; use ai blocks instead"],
     ["--as-reply", "send as a reply to the matched message"],
     ["--no-as-reply", "send without linking to the matched message"],
     ["--per-chat <limit>", "at most this many per chat, such as 1/12h"],
@@ -59,8 +59,13 @@ export const addReplyEditors = (replies, messenger) => {
     const edit = grantsAuthority(annotate(new Command("edit"), { effects: LOCAL_WRITE }))
         .description("change only the named fields of a reply rule; lists replace the whole list")
         .argument("<id>", "the rule's id");
-    for (const [flag, help] of REPLY_EDIT_OPTIONS)
-        edit.option(flag, help);
+    for (const [flag, help] of REPLY_EDIT_OPTIONS) {
+        const option = new Option(flag, help);
+        if (flag === "--template-mode <mode>")
+            option.conflicts("model");
+        edit.addOption(option);
+    }
+    edit.addOption(new Option("--model <mode>", "compatibility alias for --template-mode").hideHelp().conflicts("templateMode"));
     // Commander gives negated-only flags a true default; omission must preserve the saved field.
     edit.action(function (id) {
         const options = this.opts();
@@ -68,7 +73,10 @@ export const addReplyEditors = (replies, messenger) => {
             delete options.hours;
         const context = messengerContext(this, messenger);
         const { settings, env } = context;
-        renderItem(this, context, editRule(repliesPathFor(messenger.app, settings.profile, env), messenger.provider, id, options));
+        renderItem(this, context, editRule(repliesPathFor(messenger.app, settings.profile, env), messenger.provider, id, {
+            ...options,
+            model: options.templateMode ?? options.model,
+        }));
     });
     replies.addCommand(edit);
     const audience = grantsAuthority(annotate(new Command("audience"), { effects: LOCAL_WRITE })).description("show the reply audience, who the rules may answer, or replace its named fields; a new file answers everyone a rule matches");

package/dist/cli/messenger/retention-command.js

@@ -13,7 +13,7 @@ export const retentionCommand = (messenger) => annotate(new Command("retention")
     .option("--until-time <time>", "joining period ends at this time; now by default")
     .option("--checkpoints <durations>", "up to 10 increasing joining ages, comma separated; 1d,7d,30d by default")
     .option("--within <duration>", "activity and early departure window after joining; 7d by default")
-    .addOption(new Option("--by <day|week>", "group joining dates by calendar day or Monday week").choices(["day", "week"]))
+    .addOption(new Option("--by <group>", "group joining dates by calendar day or Monday week").choices(["day", "week"]))
     .option("--timezone <zone>", "IANA timezone for joining cohorts")
     .option("--limit <n>", "cohorts and member evidence, 1–100", positiveCount("--limit"))
     .action(async function (chat) {

package/dist/cli/messenger/review.js

@@ -1,6 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { parseDuration } from "../../domain/duration.js";
 import { renderMessages } from "../../render/messages.js";
 import { CHAT_KINDS } from "../../services/chats.js";
@@ -34,7 +34,7 @@ export const reviewCommand = (messenger) => annotate(new Command("review"), {
     .description("every message, yours too, in chats that changed since a point — for reviewing who owes what")
     .addHelpText("after", queryHelp(REVIEW_QUERY))
     .argument("[query...]", `where the last review ended and which chat: date>2h, chat:"Book club"; ${REVIEW_DAYS} days ago if no date`)
-    .option("--kind <kinds>", `only chats of these kinds, comma-separated: ${CHAT_KINDS.join(", ")}`)
+    .addOption(new Option("--kind <kinds>", `compatibility spelling for kind:; ${CHAT_KINDS.join(", ")}`).hideHelp())
     .option("--unanswered [duration]", `only questions to you or a group's admins that nobody answered, asked at least this long ago — 4h, 1d; ${UNANSWERED_HOURS}h if not given`)
     .option("--all", "muted and archived chats too — left out unless they mention you or reply to you")
     .option(...TRANSCRIBE_OPTION)
@@ -47,7 +47,9 @@ export const reviewCommand = (messenger) => annotate(new Command("review"), {
     const hearWith = modelWith(options.transcribe, options.model);
     const context = messengerContext(this, messenger);
     const { settings, renderer, format, env } = context;
-    const { since: from, chat, meta } = catchUpQuery(query, REVIEW_QUERY, "review");
+    const { since: from, chat, meta, kinds: queriedKinds } = catchUpQuery(query, REVIEW_QUERY, "review");
+    if (options.kind !== undefined && queriedKinds !== undefined)
+        throw new CliError("validation_error", "give kind: or its legacy --kind spelling, not both");
     if (options.new && (from !== undefined || options.unanswered !== undefined)) {
         // An open question stays open: moving past it would drop it from the next review.
         throw new CliError("validation_error", "--new keeps its own point — not with a date or --unanswered");
@@ -62,7 +64,7 @@ export const reviewCommand = (messenger) => annotate(new Command("review"), {
         : undefined;
     const since = from ?? saved?.first ?? reviewStart();
     const hours = options.unanswered === undefined ? undefined : unansweredHours(options.unanswered);
-    const kinds = options.kind === undefined ? undefined : kindsOf(options.kind);
+    const kinds = queriedKinds ?? (options.kind === undefined ? undefined : kindsOf(options.kind));
     let hearing;
     const transcribe = options.transcribe === true;
     const { found, reader } = await context.withServices(async (services, connect) => {

package/dist/cli/messenger/search-command.js

@@ -6,6 +6,7 @@ import { searchNotesOf } from "../../services/notes-search.js";
 import { LOCAL_READ, REMOTE_READ } from "../effects.js";
 import { renderAnswer } from "../envelope.js";
 import { positiveCount } from "../paging.js";
+import { runsSearchCommand } from "../runs/search-command.js";
 import { commandAt } from "../steps.js";
 import { messengerContext } from "./context.js";
 import { conversationsSearchCommand } from "./conversations-command.js";
@@ -159,7 +160,8 @@ export const searchCommand = (messenger, { topics = false } = {}) => {
         .addCommand(allCommand(messenger))
         .addCommand(messagesSearchCommand(messenger))
         .addCommand(notesCommand(messenger))
-        .addCommand(conversationsSearchCommand(messenger));
+        .addCommand(conversationsSearchCommand(messenger))
+        .addCommand(runsSearchCommand(messenger.app));
     if (topics)
         search.addCommand(topicsSearchCommand(messenger));
     for (const [path, args] of Object.entries({

package/dist/cli/messenger/searches-command.js

@@ -45,7 +45,7 @@ export const searchesCommand = (messenger) => {
         .option("--exact", "bare words and quotes match their exact form only, as exact:word does; text: still matches every form")
         .option("--context <n>", "messages before and after each hit", wholeCount)
         .option("--timezone <zone>", "the IANA timezone for calendar date boundaries")
-        .option("--by <chat|sender|day|hour>", "what stats messages show --saved counts by", groupingOf)
+        .option("--by <group>", "count by chat, sender, day or hour for stats messages show --saved", groupingOf)
         .option("--selection <json>", "save the resolved parent ranking query and options from a drilldown")
         .option("--replace", "overwrite a saved search of the same name")
         .action(async function (name, words) {
@@ -124,7 +124,11 @@ export const searchesCommand = (messenger) => {
         const deleted = await context.withServices((services) => services.searches.delete(reference));
         renderAnswer(this, context, itemOf(savedSearchItem(deleted)), () => `deleted ${deleted.name ?? `run ${deleted.id}`}\n`);
     });
-    annotate(searches.command("clear"), { effects: LOCAL_WRITE, examples: [`${tool} searches clear`] })
+    annotate(searches.command("clear"), {
+        output: { entity: "search_history_clear" },
+        effects: LOCAL_WRITE,
+        examples: [`${tool} searches clear`],
+    })
         .description("empty the history; saved searches stay")
         .action(async function () {
         const context = messengerContext(this, messenger);

package/dist/cli/messenger/sends-query.d.ts

@@ -0,0 +1,5 @@
+import { type QueryRegistry } from "@wirecat/cli-base/query";
+import type { SendFilter } from "../../sends/journal.js";
+import { type QueryWords } from "../list-query.js";
+export declare const SENDS_QUERY: QueryRegistry;
+export declare const sendFilter: (words: QueryWords) => SendFilter | undefined;

package/dist/cli/messenger/sends-query.js

@@ -0,0 +1,33 @@
+import { queryFieldsOf } from "@wirecat/cli-base/query";
+import { sendAttempt } from "../../entities/index.js";
+import { queryTerms } from "../list-query.js";
+export const SENDS_QUERY = {
+    entity: "send_attempt",
+    backend: "native",
+    fields: queryFieldsOf(sendAttempt, {
+        native: ["outcome", "chat_id", "operation_id", "error_code", "key"],
+        examples: {
+            outcome: "outcome:failed",
+            chat_id: "chat_id:7",
+            operation_id: "operation_id:op-1",
+            error_code: "error_code:timeout",
+            key: "key:messages.send",
+        },
+    }).map((field) => field.native
+        ? { ...field, operators: field.operators.filter((operator) => operator === "term" || operator === "phrase") }
+        : field),
+};
+export const sendFilter = (words) => {
+    const terms = queryTerms(words, SENDS_QUERY, "sends list");
+    if (terms.size === 0)
+        return undefined;
+    const outcome = sendAttempt.entries.outcome.options.find((value) => value === terms.get("outcome"));
+    const chatId = terms.get("chat_id"), operationId = terms.get("operation_id"), errorCode = terms.get("error_code"), key = terms.get("key");
+    return {
+        ...(outcome === undefined ? {} : { outcome }),
+        ...(chatId === undefined ? {} : { chatId }),
+        ...(operationId === undefined ? {} : { operationId }),
+        ...(errorCode === undefined ? {} : { errorCode }),
+        ...(key === undefined ? {} : { key }),
+    };
+};

package/dist/cli/messenger/serve-command.js

@@ -31,6 +31,7 @@ export { lockPath, readLock, servingProfiles } from "../../background/lock.js";
  */
 export const serveCommand = (messenger) => {
     const command = annotate(new Command("serve"), {
+        output: { entity: "serve_summary" },
         effects: REMOTE_WRITE,
         lifetime: "persistent",
         examples: [`${messenger.app.command} personal serve`],

package/dist/cli/messenger/serve-relay.d.ts

@@ -78,6 +78,7 @@ export declare const serveRelay: (command: Command, messenger: Messenger) => {
         inviteLinkRevoke?: boolean;
         inviteLinkUpdate?: boolean;
         joinRequestsAll?: boolean;
+        joinRequestsByLink?: boolean;
         channelComments?: boolean;
         addsWithHistory?: boolean;
         adminRights?: readonly import("../../domain/models.js").AdminRight[];

package/dist/cli/messenger/statistics-query.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from "commander";
+import { type QueryWords } from "../list-query.js";
+export type StatisticsQuery = "contacts-top" | "messages-top" | "discussion" | "unanswered" | "responses";
+export declare const withStatisticsQuery: (command: Command, report: StatisticsQuery) => Command;
+/** Report predicates become the existing source/aggregate parameters; the message query keeps its syntax. */
+export interface StatisticsFilters {
+    text?: string;
+    messageKind?: string;
+    minMessages?: number;
+    minViews?: number;
+    maxReplies?: number;
+    olderThan?: string;
+}
+export declare const statisticsQuery: (words: QueryWords, report: StatisticsQuery) => StatisticsFilters;