@wirecat/cli-core 0.399.0 → 0.400.0

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

@@ -6,13 +6,13 @@ import { grantsAuthority, LOCAL_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { messengerContext } from "./context.js";
 /**
- * The owner's way out of a remembered wait or a hold on writes, once they know it is over. No MCP
- * tool on purpose: an agent that could lift a hold would send straight into a spam limit again.
+ * The owner's way out of a remembered wait or a hold on writes, once they know it is over. An agent gets it only
+ * under `mcp.authority`: one that could lift a hold would send straight into a spam limit again.
  */
 export const floodCommand = (messenger) => {
     const { app } = messenger;
     const name = messenger.name ?? app.command;
-    return annotate(new Command("flood"), { mcp: false })
+    return new Command("flood")
         .description(`the waits ${name} asked this profile to keep, and a hold on its writes`)
         .addCommand(grantsAuthority(annotate(new Command("clear"), { effects: LOCAL_WRITE, examples: [`${app.command} personal flood clear`] }))
         .summary("clear a profile's stored rate-limit hold")

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

@@ -21,7 +21,7 @@ const count = (value) => {
 };
 export const gapsCommand = (messenger) => {
     const group = new Command("gaps").description("inspect recorded interior coverage gaps and explicitly fetch them");
-    annotate(group.command("plan"), { effects: LOCAL_READ })
+    annotate(group.command("plan"), { output: { entity: "store_gap_plan" }, effects: LOCAL_READ })
         .description("local coverage plan; missing message ids alone do not imply missing history")
         .argument("<chat>", messenger.chatArgument)
         .action(async function (chat) {
@@ -29,7 +29,7 @@ export const gapsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(await context.withServices((services) => services.gaps.plan(chat)))));
     });
     const fetching = messenger.fetching ?? FETCHING;
-    annotate(group.command("repair"), { effects: FETCH })
+    annotate(group.command("repair"), { output: { entity: "store_gap_repair" }, effects: FETCH })
         .description("fetch bounded interior gaps and recheck coverage; never delete unseen messages")
         .argument("<chat>", messenger.chatArgument)
         .option("--limit <n>", "total messages in this repair, 500 by default", count)

package/dist/cli/messenger/guard-commands.js

@@ -5,10 +5,12 @@ import { SendJournal, sendsPathFor } from "../../sends/journal.js";
 import { RecipientList, recipientsPathFor } from "../../sends/recipients.js";
 import { FETCH, grantsAuthority, LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
-import { pagedList } from "../list-query.js";
+import { pagedList, typedQuery, withQuery } from "../list-query.js";
 import { withPaging } from "../paging.js";
 import { wholeList } from "./chat-answers.js";
 import { messengerContext } from "./context.js";
+import { RECIPIENTS_QUERY, recipientFilter } from "./recipients-query.js";
+import { SENDS_QUERY, sendFilter } from "./sends-query.js";
 /**
  * The chats this profile may send to. Off until the first `add`; `clear` deletes it, which turns it off again. It stops
  * a model that a message talked into writing somewhere, not an agent set on getting around it.
@@ -17,19 +19,26 @@ export const recipientsCommand = (messenger) => {
     const tool = `${messenger.app.command} personal`;
     const listFor = (profile, env) => new RecipientList(recipientsPathFor(messenger.app, profile, env), messenger.app.command);
     const command = new Command("recipients").description("the chats this profile may send to, when the list is on");
-    annotate(command.command("list"), { effects: LOCAL_READ, examples: [`${tool} recipients list`] })
+    withQuery(annotate(command.command("list"), { examples: [`${tool} recipients list`], effects: LOCAL_READ }), RECIPIENTS_QUERY)
         .description("the chats on the list; empty and off until the first add")
-        .action(async function () {
+        .action(async function (words) {
+        const filter = recipientFilter(words);
         const context = messengerContext(this, messenger);
         const { settings, renderer, env } = context;
-        const chats = listFor(settings.profile, env).read();
-        renderAnswer(this, context, wholeList("recipients list", (chats ?? []).map(snakeKeys)));
-        if (!chats)
+        const found = listFor(settings.profile, env).list(filter);
+        renderAnswer(this, context, wholeList("recipients list", found.items.map(snakeKeys)));
+        if (found.state === "off")
             renderer.note("the recipient list is off — this profile may send to any chat");
-        else if (chats.length === 0)
+        else if (found.state === "empty")
             renderer.note("the recipient list is on and empty — this profile may send nowhere");
+        else if (found.items.length === 0)
+            renderer.note("no recipients match the query");
     });
-    grantsAuthority(annotate(command.command("add"), { effects: FETCH, examples: [`${tool} recipients add "Book club"`] }))
+    grantsAuthority(annotate(command.command("add"), {
+        examples: [`${tool} recipients add "Book club"`],
+        effects: FETCH,
+        output: { entity: "recipient_change", view: "added" },
+    }))
         .argument("<chat>", messenger.chatArgument)
         .description("allow sending to this chat; the first add turns the list on")
         .action(async function (chat) {
@@ -44,7 +53,11 @@ export const recipientsCommand = (messenger) => {
         });
         renderAnswer(this, context, itemOf({ id: found.id, title: found.title, added }));
     });
-    grantsAuthority(annotate(command.command("remove"), { effects: LOCAL_WRITE, examples: [`${tool} recipients remove "Book club"`] }))
+    grantsAuthority(annotate(command.command("remove"), {
+        examples: [`${tool} recipients remove "Book club"`],
+        effects: LOCAL_WRITE,
+        output: { entity: "recipient_change", view: "removed" },
+    }))
         .argument("<chat>", "chat id, or the title as the list shows it")
         .description("stop allowing this chat; the list stays on")
         .action(async function (chat) {
@@ -55,7 +68,11 @@ export const recipientsCommand = (messenger) => {
             throw new CliError("not_found", `${chat.trim()} is not on the recipient list of ${settings.profile}`);
         renderAnswer(this, context, itemOf({ id: gone.id, title: gone.title, removed: true }));
     });
-    grantsAuthority(annotate(command.command("clear"), { effects: LOCAL_WRITE, examples: [`${tool} recipients clear`] }))
+    grantsAuthority(annotate(command.command("clear"), {
+        examples: [`${tool} recipients clear`],
+        effects: LOCAL_WRITE,
+        output: { entity: "recipient_change", view: "off" },
+    }))
         .description("delete the list, which turns it off: this profile may send to any chat again")
         .action(async function () {
         const context = messengerContext(this, messenger);
@@ -65,16 +82,21 @@ export const recipientsCommand = (messenger) => {
     return command;
 };
 /** Every attempt to send from this profile, kept whatever `--record` says. Never the text. */
-export const sendsCommand = (messenger) => new Command("sends").description("every attempt to send from this profile — never the text").addCommand(withPaging(annotate(new Command("list"), { effects: LOCAL_READ }).description("attempts to send, newest first: sent, refused, failed, or not known")).action(async function () {
+export const sendsCommand = (messenger) => new Command("sends").description("every attempt to send from this profile — never the text").addCommand(withQuery(withPaging(annotate(new Command("list"), {
+    effects: LOCAL_READ,
+    examples: [`${messenger.app.command} personal sends list --limit 10`],
+}).description("attempts to send, newest first: sent, refused, failed, or not known")), SENDS_QUERY).action(async function (words) {
+    const filter = sendFilter(words);
     const context = messengerContext(this, messenger);
     const { settings, renderer, env } = context;
-    const entries = new SendJournal(sendsPathFor(messenger.app, settings.profile, env)).entries().reverse();
+    const entries = new SendJournal(sendsPathFor(messenger.app, settings.profile, env)).entries(filter).reverse();
     const from = settings.all ? 0 : (settings.page - 1) * settings.limit;
     const shown = settings.all ? entries : entries.slice(from, from + settings.limit);
     renderAnswer(this, context, pagedList("sends list", settings, {
         items: shown.map(snakeKeys),
+        args: words.length ? { query: typedQuery(words) } : {},
         has_more: from + shown.length < entries.length,
     }));
     if (entries.length === 0)
-        renderer.note(`profile ${settings.profile} has not tried to send anything`);
+        renderer.note(filter ? "no send attempts match the query" : `profile ${settings.profile} has not tried to send anything`);
 }));

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

@@ -13,6 +13,7 @@ const DEFAULT_LIMIT = 100;
 export const imagesCommand = (messenger) => {
     const images = new Command("images").description("search pictures by what they show, with a model on this machine");
     annotate(images.command("embed"), {
+        output: { entity: "image_embedding" },
         effects: FETCH,
         offline: false,
         examples: [`${messenger.app.command} images embed`, `${messenger.app.command} images embed --limit 500`],

package/dist/cli/messenger/media-archive-command.js

@@ -13,6 +13,7 @@ import { addMediaArchiveTimers } from "./media-archive-timer-command.js";
 import { stopOnSignal } from "./patience.js";
 export const addMediaArchiveCommands = (archive, messenger) => {
     annotate(archive.command("download"), {
+        output: { entity: "media_archive" },
         effects: FETCH,
         examples: [`${messenger.app.command} attachments download ./media-archive`],
     })
@@ -54,6 +55,7 @@ export const addMediaArchiveCommands = (archive, messenger) => {
         }
     });
     annotate(archive.command("check"), {
+        output: { entity: "media_archive_check" },
         effects: LOCAL_READ,
         examples: [`${messenger.app.command} attachments check ./media-archive`],
     })

package/dist/cli/messenger/media-archive-move-command.js

@@ -8,6 +8,7 @@ import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { messengerContext, refuseLocalWrite } from "./context.js";
 export const addMediaArchiveMove = (attachments, messenger) => {
     annotate(attachments.command("move"), {
+        output: { entity: "media_archive_move" },
         effects: LOCAL_WRITE,
         examples: [
             `${messenger.app.command} attachments move ./media-archive ./older-images --before-time 2026-10-01T00:00:00Z --dry-run`,

package/dist/cli/messenger/media-archive-timer-command.js

@@ -14,8 +14,8 @@ export const addMediaArchiveTimers = (attachments, messenger) => {
     const archive = attachments.command("jobs").description("daily media archive timers for this profile");
     for (const action of ["install", "start", "stop", "status", "uninstall"]) {
         const command = annotate(archive.command(action), {
+            output: { entity: "media_archive_timer" },
             effects: action === "status" ? LOCAL_READ : LOCAL_WRITE,
-            ...(action === "status" ? {} : { mcp: false }),
             examples: [`${messenger.app.command} attachments jobs ${action} ./media-archive`],
         })
             .description({

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

@@ -16,6 +16,7 @@ export const mentionsCommand = (messenger) => {
     const tool = messenger.app.command;
     const mentions = new Command("mentions").description("phones, e-mail, links, documents, names and addresses in stored messages");
     annotate(mentions.command("list"), {
+        output: { entity: "mention" },
         effects: LOCAL_READ,
         query: MENTION_QUERY,
         examples: [
@@ -55,6 +56,7 @@ export const mentionsCommand = (messenger) => {
             context.renderer.note("more remain — a larger --limit shows them all and moves the --new point");
     });
     annotate(mentions.command("domains"), {
+        output: { entity: "mention_domain" },
         effects: LOCAL_READ,
         query: MENTION_QUERY,
         examples: [`${tool} mentions domains`, `${tool} mentions domains status:found`],
@@ -77,7 +79,11 @@ export const mentionsCommand = (messenger) => {
             `${firstAt.slice(0, 10)}…${lastAt.slice(0, 10)}\n`)
             .join(""));
     });
-    annotate(mentions.command("places"), { effects: LOCAL_READ, examples: [`${tool} mentions places`] })
+    annotate(mentions.command("places"), {
+        output: { entity: "place" },
+        effects: LOCAL_READ,
+        examples: [`${tool} mentions places`],
+    })
         .summary("confirmed street addresses, most mentioned first")
         .description("confirmed addresses, in every account, most mentioned first; `mentions confirm <id>` adds one")
         .option("--limit <n>", "how many to show", positiveCount("--limit"))
@@ -90,7 +96,11 @@ export const mentionsCommand = (messenger) => {
             has_more: places.hasMore,
         }), () => places.items.map(({ id, address, mentions }) => `${id}  ${address}  ${mentions} mentioned\n`).join(""));
     });
-    annotate(mentions.command("show"), { effects: LOCAL_READ, examples: [`${tool} mentions show 12`] })
+    annotate(mentions.command("show"), {
+        output: { entity: "mention", view: "details" },
+        effects: LOCAL_READ,
+        examples: [`${tool} mentions show 12`],
+    })
         .description("one mention, the text around it, and how many other places hold its value")
         .argument("<id>", "the mention's id, from mentions list", positiveCount("<id>"))
         .action(async function (id) {
@@ -101,6 +111,7 @@ export const mentionsCommand = (messenger) => {
             (found.candidates.length > 0 ? `may be ${found.candidates.join(", ")}\n` : ""));
     });
     annotate(mentions.command("confirm"), {
+        output: { entity: "mention_decision" },
         effects: LOCAL_WRITE,
         examples: [
             `${tool} mentions confirm 12 person:7`,
@@ -123,6 +134,7 @@ export const mentionsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(decided)));
     });
     annotate(mentions.command("reject"), {
+        output: { entity: "mention_decision" },
         effects: LOCAL_WRITE,
         examples: [`${tool} mentions reject 12`],
     })
@@ -140,6 +152,7 @@ export const mentionsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(decided)));
     });
     destroysNothing(annotate(mentions.command("rebuild"), {
+        output: { entity: "mention_rebuild" },
         effects: LOCAL_WRITE,
         examples: [`${tool} mentions rebuild`, `${tool} mentions rebuild person-name`],
     }))

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

@@ -110,6 +110,7 @@ export const messagesCommand = (messenger) => {
     };
     messages.addCommand(sendCommand(messenger));
     annotate(messages.command("show"), {
+        output: { entity: "message" },
         examples: [`${messenger.app.command} personal messages show "Book club" 101`],
         effects: REMOTE_READ,
     })
@@ -122,6 +123,7 @@ export const messagesCommand = (messenger) => {
         await readWindow(this, chat, message, { before: 0, after: 0 });
     });
     threadOptions(annotate(messages.command("context"), {
+        output: { entity: "message_context" },
         examples: [`${messenger.app.command} personal messages context "Book club" 101 --before-n 3 --after-n 3`],
         effects: REMOTE_READ,
     }))

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

@@ -14,6 +14,7 @@ import { messengerContext } from "./context.js";
 export const deleteCommand = (messenger) => annotate(new Command("delete"), {
     examples: [`${messenger.app.command} personal messages delete "Book club" 101`],
     effects: REMOTE_WRITE,
+    output: { entity: "message_deletion" },
 })
     .description("delete messages for you only; with --for-everyone, for everyone in the chat")
     .argument("<chat>", messenger.chatArgument)

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/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,6 +21,7 @@ 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`],
     })

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) {
@@ -78,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");