@wirecat/cli-core 0.398.0 → 0.400.0

package/dist/cli/messenger/conversations-command.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 { analysisConsents } from "../../analysis/consents.js";
 import { openAnalysis, providerIdentity } from "../../analysis/provider.js";
 import { runAnalysis } from "../../analysis/runner.js";
@@ -18,6 +18,7 @@ import { listQuery, pagedList, pageOf, typedQuery, withQuery } from "../list-que
 import { positiveCount } from "../paging.js";
 import { readsStdin } from "../stdin-field.js";
 import { nextStep, rootOf, runnable, stepLine } from "../steps.js";
+import { ANALYSIS_CONSENTS_QUERY, analysisConsentFilter } from "./analysis-consents-query.js";
 import { answerOf as askOwner } from "./ask.js";
 import { messengerContext, refuseLocalWrite } from "./context.js";
 import { conversationShown, foundConversations, readinessList, refreshedAnswer } from "./conversation-answers.js";
@@ -33,13 +34,16 @@ export const conversationsCommand = (messenger) => {
     const conversations = new Command("conversations")
         .summary("group stored messages into conversations")
         .description("the conversations inside a chat, found in the stored messages by replies, mentions and who wrote next");
-    boundOptions(reachesOtherService(annotate(conversations.command("build"), { effects: REMOTE_WRITE }))
+    boundOptions(reachesOtherService(annotate(conversations.command("build"), { output: { entity: "conversation_build" }, effects: REMOTE_WRITE }))
         .summary("build conversation links from stored messages")
         .description("find a chat's conversations in what the store holds, replacing the last build; without --chat, every " +
         "chat that changed since its build and every group never built; never asks the messenger")
         .option("--chat <chat>", messenger.chatArgument)
         .option("--analyze", "link batches using the configured analysis provider; requires --chat and remembers consent for this chat/provider")
-        .option("--provider <provider>", "analysis: agent, openai or anthropic")
+        .addOption(new Option("--analysis-provider <provider>", "analysis: agent, openai or anthropic").conflicts("provider"))
+        .addOption(new Option("--provider <provider>", "compatibility alias for --analysis-provider")
+        .hideHelp()
+        .conflicts("analysisProvider"))
         .option("--model <model>", "analysis model; overrides analysis_model")
         .option("--base-url <url>", "analysis API endpoint; overrides analysis_base_url")
         .option("--size <n>", "analysis answer messages per batch, 10–200; default 50", positiveCount("--size"))
@@ -95,7 +99,8 @@ export const conversationsCommand = (messenger) => {
             renderAnswer(this, context, itemOf(snakeKeys(result)));
             return;
         }
-        if (options.provider !== undefined ||
+        if (options.analysisProvider !== undefined ||
+            options.provider !== undefined ||
             options.model !== undefined ||
             options.baseUrl !== undefined ||
             options.size !== undefined ||
@@ -126,7 +131,7 @@ export const conversationsCommand = (messenger) => {
         if (found.items.length === 0 && context.format === "pretty")
             context.renderer.note("no conversations match");
     });
-    annotate(conversations.command("show"), { effects: LOCAL_READ })
+    annotate(conversations.command("show"), { output: { entity: "conversation", view: "details" }, effects: LOCAL_READ })
         .summary("one conversation and its messages")
         .description("one conversation's messages, oldest first — by its id, or the one a message is in")
         .argument("<conversation>", `a conversation id from \`conversations list\`; or ${messenger.chatArgument}, with a message`)
@@ -155,7 +160,7 @@ export const conversationsCommand = (messenger) => {
         else
             renderAnswer(this, context, conversationShown(account, { summary, messages }));
     });
-    withModelOptions(annotate(conversations.command("related"), { effects: LOCAL_READ })
+    withModelOptions(annotate(conversations.command("related"), { output: { entity: "conversation_hit" }, effects: LOCAL_READ })
         .summary("conversations nearest in meaning to a message's conversation")
         .description("the conversations nearest in meaning to the one a message is in, in every built chat, best first — " +
         "from the vectors `conversations embed` stored; runs no model")
@@ -171,7 +176,7 @@ export const conversationsCommand = (messenger) => {
         if (found.hits.length === 0 && context.format === "pretty")
             context.renderer.note(`no other conversation has vectors of ${found.model}`);
     });
-    withModelOptions(annotate(conversations.command("status"), { effects: LOCAL_READ })
+    withModelOptions(annotate(conversations.command("status"), { output: { entity: "conversation_readiness" }, effects: LOCAL_READ })
         .summary("which chats are ready for conversation search")
         .description("how fresh each built chat's conversations and vectors are: messages the build has not seen, chunks " +
         "with a current, stale or missing vector")
@@ -189,7 +194,7 @@ export const conversationsCommand = (messenger) => {
         .summary("batches waiting for an agent's conversation links")
         .description("windows of a chat for your own AI agent to link: which earlier message each one answers");
     const sizeOption = (command) => command.option("--size <n>", `messages to answer per batch, ${BATCH_SIZE.min}–${BATCH_SIZE.max}; ${BATCH_SIZE.default} by default`, positiveCount("--size"));
-    sizeOption(annotate(batches.command("status"), { effects: LOCAL_READ })
+    sizeOption(annotate(batches.command("status"), { output: { entity: "conversation_batch_status" }, effects: LOCAL_READ })
         .summary("progress of conversation-link batches")
         .description("how many messages still wait for an answer, in how many batches, and how much text")
         .requiredOption("--chat <chat>", messenger.chatArgument)).action(async function () {
@@ -199,7 +204,7 @@ export const conversationsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(status)), () => `${status.messages} messages to answer, about ${status.batches} batches, ` +
             `${status.characters} characters (about ${status.tokensEstimate} tokens)\n`);
     });
-    sizeOption(annotate(batches.command("next"), { effects: LOCAL_READ })
+    sizeOption(annotate(batches.command("next"), { output: { entity: "conversation_batch" }, effects: LOCAL_READ })
         .summary("get the next batch of messages to link")
         .description("the next window to answer, with the messages before it; message text goes to stdout only")
         .requiredOption("--chat <chat>", messenger.chatArgument)).action(async function () {
@@ -226,7 +231,7 @@ export const conversationsCommand = (messenger) => {
     const links = conversations
         .command("links")
         .description("your agent's answers: which earlier message each message of a batch answers");
-    readsStdin(annotate(links.command("add"), { effects: LOCAL_WRITE }), {
+    readsStdin(annotate(links.command("add"), { output: { entity: "conversation_change" }, effects: LOCAL_WRITE }), {
         name: "answer",
         description: '{ "model", "skill"?, "answers": [{ "message", "parent", "confidence" }] }',
         json: true,
@@ -243,22 +248,23 @@ export const conversationsCommand = (messenger) => {
         const stored = await context.withServices((services) => services.conversations.addAnswers(batch, answer));
         renderAnswer(this, context, itemOf(stored, { next: [nextStep("conversations.build", { args: { chat: stored.chat } })] }), () => `${stored.stored} answers stored\n`);
     });
-    annotate(links.command("clear"), { effects: LOCAL_WRITE })
+    annotate(links.command("clear"), { output: { entity: "conversation_change" }, effects: LOCAL_WRITE })
         .summary("remove an agent's saved conversation-link answers")
         .description("drop your agent's answers for a chat, or only one model's; messages are never touched")
         .requiredOption("--chat <chat>", messenger.chatArgument)
-        .option("--model <model>", "only the answers this model gave")
+        .addOption(new Option("--answer-model <model>", "only the stored answers this model gave").conflicts("model"))
+        .addOption(new Option("--model <model>", "compatibility alias for --answer-model").hideHelp().conflicts("answerModel"))
         .action(async function () {
-        const { chat, model } = this.opts();
+        const { chat, model, answerModel } = this.opts();
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, LINKS_KEY);
-        const cleared = await context.withServices((services) => services.conversations.clearAnswers(chat, model));
+        const cleared = await context.withServices((services) => services.conversations.clearAnswers(chat, answerModel ?? model));
         renderAnswer(this, context, itemOf(cleared), () => `${cleared.cleared} answers dropped\n`);
     });
-    const embed = withModelOptions(reachesOtherService(annotate(new Command("embed"), { effects: REMOTE_WRITE }))
+    const embed = withModelOptions(reachesOtherService(annotate(new Command("embed"), { output: { entity: "conversation_embedding" }, effects: REMOTE_WRITE }))
         .summary("prepare conversation vectors for meaning search")
         .description("compute a vector for each chunk of a chat's conversations for search by meaning — on this machine, or " +
-        "with --provider through a service and your key; resumes where it stopped; without --chat, every " +
+        "with --embedding-provider through a service and your key; resumes where it stopped; without --chat, every " +
         "built chat with chunks left, on this machine only")
         .option("--chat <chat>", messenger.chatArgument))
         .option("--threads <n>", "local: threads in all (default: min(8, cores))", positiveCount("--threads"))
@@ -302,7 +308,7 @@ export const conversationsCommand = (messenger) => {
             next: done.skipped ? [nextStep("conversations.build", { args: { chat } })] : [],
         }), () => `${done.embedded} chunks embedded with ${done.model}${done.skipped ? `, ${done.skipped} changed since the build` : ""}\n`);
     });
-    withModelOptions(annotate(embed.command("status"), { effects: LOCAL_READ })
+    withModelOptions(annotate(embed.command("status"), { output: { entity: "conversation_embedding_status" }, effects: LOCAL_READ })
         .summary("which conversation vectors are ready or stale")
         .description("how many chunks of a chat have a vector of the model, how many are left, and what is left costs")
         .option("--chat <chat>", messenger.chatArgument)).action(async function () {
@@ -316,7 +322,7 @@ export const conversationsCommand = (messenger) => {
             (status.priceAtMost ? `, at most ${dollars(status.priceAtMost.usd)}` : "") +
             "\n");
     });
-    withModelOptions(destroysNothing(annotate(embed.command("clear"), { effects: LOCAL_WRITE }))
+    withModelOptions(destroysNothing(annotate(embed.command("clear"), { output: { entity: "conversation_change" }, effects: LOCAL_WRITE }))
         .summary("remove stored conversation vectors")
         .description("drop a chat's vectors, or only one model's; messages and conversations are never touched")
         .option("--chat <chat>", messenger.chatArgument)).action(async function () {
@@ -324,12 +330,16 @@ export const conversationsCommand = (messenger) => {
         const chat = chatOf(options);
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, EMBED_KEY);
-        const given = options.model !== undefined || options.provider !== undefined || options.baseUrl !== undefined;
+        const given = options.model !== undefined ||
+            options.embeddingProvider !== undefined ||
+            options.provider !== undefined ||
+            options.baseUrl !== undefined;
         const model = given ? choiceOf(options, messenger, context, { needKey: false }) : undefined;
         const cleared = await context.withServices((services) => services.embeddings.clear(chat, model));
         renderAnswer(this, context, itemOf(cleared), () => `${cleared.cleared} vectors dropped\n`);
     });
     boundOptions(destroysNothing(annotate(conversations.command("rebuild"), {
+        output: { entity: "conversation_preparation" },
         effects: LOCAL_WRITE,
         examples: [`${messenger.app.command} conversations rebuild --max-chats 5`],
     }))
@@ -351,30 +361,34 @@ export const conversationsCommand = (messenger) => {
     const consents = conversations
         .command("consents")
         .description("remembered analysis permissions for this account's chats and provider endpoints");
-    annotate(consents.command("list"), { effects: LOCAL_READ })
+    withQuery(annotate(consents.command("list"), { effects: LOCAL_READ }), ANALYSIS_CONSENTS_QUERY)
         .description("which chats and provider endpoints you allowed to analyse, and when")
-        .action(async function () {
+        .action(async function (words) {
+        const filter = analysisConsentFilter(words);
         const context = messengerContext(this, messenger);
-        const items = await context.withStore((store, account) => analysisConsents(store, account).list());
+        const items = await context.withStore((store, account) => analysisConsents(store, account).list(filter));
         renderAnswer(this, context, listOf("conversations consents list", {
             items: items.map(snakeKeys),
             limit: Math.max(1, items.length),
             has_more: false,
         }));
     });
-    annotate(consents.command("revoke"), { effects: LOCAL_WRITE })
+    annotate(consents.command("revoke"), { effects: LOCAL_WRITE, output: { entity: "analysis_consent_revocation" } })
         .description("forget analysis permissions so the next analysis asks again")
         .option("--chat <chat>", "revoke only this chat's consents; defaults to every chat")
-        .option("--provider <identity>", "exact provider identity from consents list; defaults to every provider")
+        .addOption(new Option("--consent-provider <identity>", "exact provider identity from consents list; defaults to every provider").conflicts("provider"))
+        .addOption(new Option("--provider <identity>", "compatibility alias for --consent-provider")
+        .hideHelp()
+        .conflicts("consentProvider"))
         .action(async function () {
-        const { chat, provider } = this.opts();
+        const { chat, provider, consentProvider } = this.opts();
         const context = messengerContext(this, messenger);
         refuseLocalWrite(context, messenger.app.command, LINKS_KEY);
         await context.withStore(async (store, account) => {
             const chatId = chat === undefined
                 ? undefined
                 : (await servicesFor(storedDeps(messenger, store, account, context.guard)).conversations.batchStatus(chat, BATCH_SIZE.default)).chat;
-            await analysisConsents(store, account).revoke(chatId, provider);
+            await analysisConsents(store, account).revoke(chatId, consentProvider ?? provider);
         });
         renderAnswer(this, context, itemOf({ revoked: true }));
     });
@@ -393,7 +407,10 @@ const chatOf = ({ chat }) => {
 };
 const withModelOptions = (command) => command
     .option("--model <model>", "local: a model id from `models text list` (default: e5-small); remote: the provider's model")
-    .option("--provider <provider>", "embedding provider: local or openai; flags override profile settings")
+    .addOption(new Option("--embedding-provider <provider>", "embedding provider: local or openai; flags override profile settings").conflicts("provider"))
+    .addOption(new Option("--provider <provider>", "compatibility alias for --embedding-provider")
+    .hideHelp()
+    .conflicts("embeddingProvider"))
     .option("--base-url <url>", "a server with OpenAI's /v1/embeddings: Gemini, Jina, or Ollama and LM Studio on this machine")
     .option("--dims <n>", "remote: the vector size — needed with --base-url; shortens an OpenAI model's", positiveCount("--dims"));
 /** How much one run over many chats may do: the owner's machine, not a background job, pays for it. */
@@ -412,7 +429,7 @@ const bounds = ({ maxChats, maxChunks }) => ({
 /** Work nobody named chat by chat never sends chat text off the machine. */
 const localOnly = (model, what) => {
     if (typeof model !== "string") {
-        throw new CliError("validation_error", `${what} uses the model on this machine only — drop --provider and --base-url, or embed one chat with --chat`);
+        throw new CliError("validation_error", `${what} uses the model on this machine only — drop --embedding-provider and --base-url, or embed one chat with --chat`);
     }
 };
 const renderRefreshed = (command, context, refreshed) => {
@@ -491,6 +508,7 @@ const answerOf = (text) => {
 };
 /** `messages links`: why a message sits where it does in its conversation. */
 export const linksCommand = (messenger) => annotate(new Command("links"), {
+    output: { entity: "message_links" },
     examples: [`${messenger.app.command} personal messages links "Book club" 101`],
     effects: LOCAL_READ,
 })
@@ -526,7 +544,7 @@ const readinessLine = ({ chat, state, graph, pending, vectors }, model) => graph
         `${pending.deleted} deleted · ${model}: ${vectors.current} current, ${vectors.stale} stale, ` +
         `${vectors.missing} missing of ${vectors.chunks} chunks`;
 /** `search conversations`: the conversations nearest to a query, in meaning and in words. */
-export const conversationsSearchCommand = (messenger) => syncOptions(boundOptions(withModelOptions(reachesOtherService(annotate(new Command("conversations"), { effects: REMOTE_READ })))), messenger)
+export const conversationsSearchCommand = (messenger) => syncOptions(boundOptions(withModelOptions(reachesOtherService(annotate(new Command("conversations"), { output: { entity: "conversation_hit" }, effects: REMOTE_READ })))), messenger)
     .summary("find conversations by words and meaning")
     .description("the conversations nearest to a query in meaning and in words, best first, in one chat or every one — " +
     "meaning after `conversations embed`; runs on this machine")

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

@@ -74,7 +74,11 @@ const reportCommand = (messenger) => {
             `About a given run:   ${create} --run <id>   (ids: ${lineOf(this, "runs list")})`,
         ].join("\n"));
     });
-    destroysNothing(annotate(report.command("create"), { effects: LOCAL_WRITE, mcp: false }))
+    destroysNothing(annotate(report.command("create"), {
+        effects: LOCAL_WRITE,
+        mcp: false,
+        examples: [`${app.command} personal doctor report create --output ./problem-report.json`],
+    }))
         .description("write a problem report to a file, and say where to send it")
         .option("--run <id>", "the run the report is about; the newest failed one if not given")
         .option("--output <file>", "where to write it; a new file in this directory if not given")

package/dist/cli/messenger/document-links-query.d.ts

@@ -0,0 +1,2 @@
+import { type QueryRegistry } from "@wirecat/cli-base/query";
+export declare const DOCUMENT_LINKS_QUERY: QueryRegistry;

package/dist/cli/messenger/document-links-query.js

@@ -0,0 +1,9 @@
+import { queryFieldsOf } from "@wirecat/cli-base/query";
+import { documentLink } from "../../entities/index.js";
+export const DOCUMENT_LINKS_QUERY = {
+    entity: "document_link",
+    backend: "native",
+    fields: queryFieldsOf(documentLink, { native: ["ref"], examples: { ref: 'ref:"msg:chat/500/7/1"' } }).map((field) => field.native
+        ? { ...field, operators: field.operators.filter((operator) => operator === "term" || operator === "phrase") }
+        : field),
+};

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

@@ -18,6 +18,7 @@ import { messengerContext, refuseLocalWrite } from "./context.js";
 import { stopOnSignal } from "./patience.js";
 /** `messages download`: every file of one message, or with `--all` of a whole chat, never over a file already there. */
 export const downloadSubcommand = (messages, messenger) => annotate(messages.command("download"), {
+    output: { entity: "message_download" },
     examples: [`${messenger.app.command} personal messages download "Book club" 101 --output-dir ./downloads`],
     effects: FETCH,
 })

package/dist/cli/messenger/flood-command.d.ts

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import { type Messenger } 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 declare const floodCommand: (messenger: Messenger) => Command;

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/hearing-command.d.ts

@@ -2,7 +2,7 @@ import type { Message } from "../../domain/models.js";
 import { type Hearing } from "../../speech/hearing.js";
 import type { Messenger, MessengerContext, ReadConnection } from "./context.js";
 export declare const TRANSCRIBE_OPTION: readonly ["--transcribe", "turn voice messages not heard yet into text — by the messenger where it can, else by a model on this machine; can take minutes"];
-export declare const MODEL_OPTION: readonly ["--model <id>", "which downloaded speech model hears them, with --transcribe; `models audio list` shows them"];
+export declare const MODEL_OPTION: readonly ["--model <model>", "which downloaded speech model hears them, with --transcribe; `models audio list` shows them"];
 /**
  * Kept transcripts on every read; new ones with `--transcribe`, using the read's connection when
  * supplied. It is released before local recognition. `undefined` when there is no voice message, and then no file is opened.

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

@@ -5,7 +5,7 @@ export const TRANSCRIBE_OPTION = [
     "turn voice messages not heard yet into text — by the messenger where it can, else by a model on this machine; can take minutes",
 ];
 export const MODEL_OPTION = [
-    "--model <id>",
+    "--model <model>",
     "which downloaded speech model hears them, with --transcribe; `models audio list` shows them",
 ];
 /**

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/inbox.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 { renderMessages } from "../../render/messages.js";
 import { CHAT_KINDS } from "../../services/chats.js";
 import { kindsOf } from "../../services/inbox.js";
@@ -41,7 +41,7 @@ export const inboxCommand = (messenger) => annotate(new Command("inbox"), {
     .option("--new", "what arrived since the last check, each message once — for scheduled runs")
     .option("--limit <n>", "at most this many per chat, the newest", positiveCount("--limit"))
     .option("--all", "muted and archived chats too — left out unless they mention you or reply to you")
-    .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(...TRANSCRIBE_OPTION)
     .option(...MODEL_OPTION)
     .addHelpText("after", "To mark a chat read, use `chats mark-read <chat>`. The other side sees it.")
@@ -51,8 +51,10 @@ export const inboxCommand = (messenger) => annotate(new Command("inbox"), {
     const context = messengerContext(this, messenger);
     const { app } = messenger;
     const { settings, renderer, format, env } = context;
-    const kinds = kind === undefined ? undefined : kindsOf(kind);
-    const { since, meta } = catchUpQuery(query, INBOX_QUERY, "inbox");
+    const { since, meta, kinds: queriedKinds } = catchUpQuery(query, INBOX_QUERY, "inbox");
+    if (kind !== undefined && queriedKinds !== undefined)
+        throw new CliError("validation_error", "give kind: or its legacy --kind spelling, not both");
+    const kinds = queriedKinds ?? (kind === undefined ? undefined : kindsOf(kind));
     if (fresh && since !== undefined)
         throw new CliError("validation_error", "--new keeps its own point — not with a date in the query");
     const saved = fresh && since === undefined

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)