@wirecat/cli-core 0.399.0 → 0.400.0

package/dist/cli/messenger/admin-statistics-command.js

@@ -5,6 +5,7 @@ import { REMOTE_READ } from "../effects.js";
 import { renderAnswer } from "../envelope.js";
 import { positiveCount } from "../paging.js";
 import { messengerContext } from "./context.js";
+import { statisticsQuery, withStatisticsQuery } from "./statistics-query.js";
 import { adminAnswer, refuseJsonl } from "./stats-answers.js";
 const collect = (value, previous = []) => [...previous, value];
 export const adminStatisticsCommand = (messenger, report) => {
@@ -27,22 +28,17 @@ export const adminStatisticsCommand = (messenger, report) => {
     else
         command
             .argument("[query...]", "a strict Lucene query; none selects every stored message")
-            .option("--chat <chat>", `only this chat; ${messenger.chatArgument}`)
-            .option("--source <accounts>", "every held account of this messenger; personal, bots or all")
-            .option("--exact", "bare words match exact forms rather than stems");
+            .option("--source <accounts>", "every held account of this messenger; personal, bots or all");
     command.option("--saved <name|id>", "run a saved report of this kind; typed report options replace stored options");
     command
         .option("--timezone <zone>", "the IANA timezone for calendar date boundaries")
         .option("--limit <n>", "report rows, 1–100; 20 if not given", positiveCount("--limit"));
     if (report !== "discussion")
         command.option("--answerer <person>", "stored name, alias, @username, ID or person:provider/account/id; ambiguous names require a choice; repeat for more", collect);
-    if (report === "unanswered")
-        command.option("--older-than <duration>", "minimum age of a question without an observed qualifying answer");
-    if (report === "discussion")
-        command
-            .option("--min-views <n>", "minimum known cumulative views", Number)
-            .option("--max-replies <n>", "maximum observed discussion replies", Number);
+    if (report !== "newcomers")
+        withStatisticsQuery(command, report);
     command.action(async function (argument) {
+        const filters = report === "newcomers" ? {} : statisticsQuery(argument, report);
         const context = messengerContext(this, messenger);
         refuseJsonl(context.format);
         const { answerer, ...options } = this.opts();
@@ -50,11 +46,7 @@ export const adminStatisticsCommand = (messenger, report) => {
             ...options,
             limit: options.limit ?? 20,
             ...(answerer ? { answerers: answerer } : {}),
-            ...(report === "newcomers"
-                ? { chat: argument }
-                : argument.length
-                    ? { text: argument.join(" ") }
-                    : {}),
+            ...(report === "newcomers" ? { chat: argument } : filters),
             signal: environmentOf(this).commandSignal ?? environmentOf(this).signal,
         }));
         renderAnswer(this, context, adminAnswer(found));

package/dist/cli/messenger/analysis-consents-query.d.ts

@@ -0,0 +1,5 @@
+import { type QueryRegistry } from "@wirecat/cli-base/query";
+import type { AnalysisConsentFilter } from "../../analysis/consents.js";
+import { type QueryWords } from "../list-query.js";
+export declare const ANALYSIS_CONSENTS_QUERY: QueryRegistry;
+export declare const analysisConsentFilter: (words: QueryWords) => AnalysisConsentFilter | undefined;

package/dist/cli/messenger/analysis-consents-query.js

@@ -0,0 +1,20 @@
+import { queryFieldsOf } from "@wirecat/cli-base/query";
+import { analysisConsent } from "../../entities/index.js";
+import { queryTerms } from "../list-query.js";
+export const ANALYSIS_CONSENTS_QUERY = {
+    entity: "analysis_consent",
+    backend: "native",
+    fields: queryFieldsOf(analysisConsent, {
+        native: ["chat", "provider"],
+        examples: { chat: "chat:7", provider: 'provider:"openai:https://example.test/v1"' },
+    }).map((field) => field.native
+        ? { ...field, operators: field.operators.filter((operator) => operator === "term" || operator === "phrase") }
+        : field),
+};
+export const analysisConsentFilter = (words) => {
+    const terms = queryTerms(words, ANALYSIS_CONSENTS_QUERY, "conversations consents list");
+    if (terms.size === 0)
+        return undefined;
+    const chat = terms.get("chat"), provider = terms.get("provider");
+    return { ...(chat === undefined ? {} : { chat }), ...(provider === undefined ? {} : { provider }) };
+};

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

@@ -64,7 +64,7 @@ export const storeCommand = (messenger) => {
  * What the local store holds, per chat — read from the store alone. Whether a fetch reached a
  * chat's very first message is not recorded, so it is not claimed: the stretches held are shown.
  */
-const statusCommand = (messenger) => annotate(new Command("status"), { effects: LOCAL_READ })
+const statusCommand = (messenger) => annotate(new Command("status"), { output: { entity: "store_chat_status" }, effects: LOCAL_READ })
     .summary("what the local archive holds and what is missing")
     .description("per chat: messages stored, the oldest and newest, and the stretches held completely")
     .argument("[chat]", messenger.chatArgument)
@@ -93,7 +93,7 @@ const leftLines = (left) => {
  * store is not offered. The refusal names the chats to a person but keeps them out of its message,
  * which a scheduled run's `last.json` keeps.
  */
-const clearCommand = (messenger) => annotate(new Command("clear"), { effects: LOCAL_WRITE, mcp: false })
+const clearCommand = (messenger) => annotate(new Command("clear"), { output: { entity: "store_clear" }, effects: LOCAL_WRITE, mcp: false })
     .description("delete from the store the chats this account has left, with their messages")
     .option("--left", "the chats this account has left — the only thing this clears")
     .option("--allow-dangerous", "yes, delete — it cannot be undone, and a chat you left cannot be fetched again")
@@ -132,7 +132,7 @@ const clearCommand = (messenger) => annotate(new Command("clear"), { effects: LO
  * `--format markdown` for a transcript a person reads. With `--output-dir`, any number of chats into a
  * folder, and each later run into the same folder adds only what changed.
  */
-const exportCommand = (messenger) => destroysNothing(annotate(new Command("export"), { effects: LOCAL_WRITE }))
+const exportCommand = (messenger) => destroysNothing(annotate(new Command("export"), { output: { entity: "store_export" }, effects: LOCAL_WRITE }))
     .summary("export stored messages to files")
     .description("a chat's stored messages, oldest first: --jsonl one message per line, --json the list envelope of messages; never asks the messenger")
     .argument("[chat...]", `${messenger.chatArgument}; several with --output-dir`)

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

@@ -36,6 +36,7 @@ const summary = (run) => [
     .filter(Boolean)
     .join(", ");
 const extractCommand = (messenger) => annotate(new Command("extract"), {
+    output: { entity: "attachment_extraction" },
     effects: FETCH,
     examples: [`${messenger.app.command} personal attachments extract --chat "Book club" --limit 10`],
 })
@@ -138,6 +139,7 @@ const listCommand = (messenger) => withQuery(withPaging(annotate(new Command("li
     renderAnswer(this, context, pagedList("attachments list", context.settings, found), () => found.items.length === 0 ? "" : `${found.items.map(row).join("\n")}\n`);
 });
 const showCommand = (messenger) => annotate(new Command("show"), {
+    output: { entity: "attachment_bytes" },
     effects: REMOTE_READ,
     examples: [`${messenger.app.command} personal attachments show "Book club" 101 --attachment 1`],
 })
@@ -173,6 +175,7 @@ const showCommand = (messenger) => annotate(new Command("show"), {
 const textCommand = (messenger) => {
     const text = new Command("text").description("the text of one file, as an agent read it");
     readsStdin(annotate(text.command("set"), {
+        output: { entity: "attachment_text_change" },
         effects: LOCAL_WRITE,
         examples: [`${messenger.app.command} personal attachments text set "Book club" 101 --text-file ./transcript.txt`],
     }), {

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

@@ -35,6 +35,7 @@ const ALL_CHATS = "--all";
 export const syncCommand = (messenger) => {
     const fetching = messenger.fetching ?? FETCHING;
     return annotate(new Command("sync"), {
+        output: { entity: "message_sync" },
         examples: [`${messenger.app.command} personal messages sync "Book club" --last 100`],
         effects: FETCH,
         cooperative: true,
@@ -224,7 +225,7 @@ export const jobsCommand = (messenger) => {
         if (jobs.length === 0 && context.format === "pretty")
             context.renderer.note(`no ${query ? "matching " : ""}background sync jobs for this profile`);
     });
-    annotate(command.command("show"), { effects: LOCAL_READ })
+    annotate(command.command("show"), { output: { entity: "store_job_details" }, effects: LOCAL_READ })
         .summary("one archive job's status and log")
         .description("one background job — the newest when none is named — and what the store now holds of its chat")
         .argument("[job]", "the job id `messages sync --background` printed")
@@ -237,7 +238,7 @@ export const jobsCommand = (messenger) => {
             : await context.withServices((services) => services.archive.held(chatId)).catch(() => undefined);
         renderAnswer(this, context, itemOf(snakeKeys({ ...jobDetails(job), ...(held ? { held } : {}), log: job.log })));
     });
-    destroysNothing(annotate(command.command("cancel"), { effects: LOCAL_WRITE }))
+    destroysNothing(annotate(command.command("cancel"), { output: { entity: "store_job_cancel" }, effects: LOCAL_WRITE }))
         .summary("cancel a queued or running archive job")
         .description("stop a running background job after its current page; a later sync resumes where it stopped")
         .argument("<job>", "the job id")
@@ -251,7 +252,7 @@ export const jobsCommand = (messenger) => {
         process.kill(job.pid, "SIGTERM");
         renderAnswer(this, context, itemOf({ job: job.id, cancelled: true }));
     });
-    destroysNothing(annotate(command.command("retry"), { effects: LOCAL_WRITE }))
+    destroysNothing(annotate(command.command("retry"), { output: { entity: "store_job_retry" }, effects: LOCAL_WRITE }))
         .summary("retry an archive job")
         .description("start a partial, failed or died job again, as a new job; the sync resumes where the store stopped")
         .argument("[job]", "the job id")
@@ -292,7 +293,7 @@ export const jobsCommand = (messenger) => {
         if (items.length === 0 && context.format === "pretty")
             context.renderer.note("no partial, failed or died jobs to retry");
     });
-    destroysNothing(annotate(command.command("clear"), { effects: LOCAL_WRITE }))
+    destroysNothing(annotate(command.command("clear"), { output: { entity: "store_job_clear" }, effects: LOCAL_WRITE }))
         .description("forget finished jobs and remove their logs; a running job is kept")
         .action(function () {
         const context = messengerContext(this, messenger);

package/dist/cli/messenger/chat-queries.d.ts

@@ -4,6 +4,7 @@ import { type QueryRegistry } from "@wirecat/cli-base/query";
  * there; `--offline`, or a messenger whose history is the store, answers them.
  */
 export declare const CHATS_QUERY: QueryRegistry;
+export declare const TRACKING_QUERY: QueryRegistry;
 /** The messenger reads a chat's events back to a time; it cannot pick them by type. */
 export declare const EVENTS_QUERY: QueryRegistry;
 /** The store's member history is read back to a time. */

package/dist/cli/messenger/chat-queries.js

@@ -1,8 +1,8 @@
 import { CliError } from "@wirecat/cli-base";
 import { queryError, queryFieldsOf } from "@wirecat/cli-base/query";
-import { chat, chatEvent, inviteLink, joinRequest, member } from "../../entities/index.js";
+import { chat, chatEvent, ENTITIES, inviteLink, joinRequest, member } from "../../entities/index.js";
 import { AUDIT_MIN_SCORE } from "../../services/members-audit.js";
-import { CHAT_COLUMNS, titlePart } from "../../store/store.js";
+import { CHAT_COLUMNS, TRACKED_CHAT_COLUMNS, titlePart } from "../../store/store.js";
 import { unfilteredQuery } from "../list-query.js";
 const titleWords = (node) => {
     const part = titlePart(node.value);
@@ -25,6 +25,16 @@ export const CHATS_QUERY = {
         validate: { title: titleWords },
     }),
 };
+export const TRACKING_QUERY = {
+    entity: "tracked_chat",
+    backend: "sql",
+    fields: queryFieldsOf(ENTITIES.tracked_chat, {
+        exclude: Object.keys(ENTITIES.tracked_chat.entries).filter((name) => !(name in TRACKED_CHAT_COLUMNS)),
+        text: ["title"],
+        examples: { chat_id: "chat_id:7", title: "title:book" },
+        validate: { title: titleWords },
+    }),
+};
 /** The messenger reads a chat's events back to a time; it cannot pick them by type. */
 export const EVENTS_QUERY = {
     entity: "chat_event",

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

@@ -48,7 +48,7 @@ export const chatsCommand = (messenger) => {
         if (body.meta?.truncated)
             context.renderer.note("more history than one run reads; a later time bound reads less");
     }));
-    annotate(chats.command("inspect"), { effects: REMOTE_READ, offline: false })
+    annotate(chats.command("inspect"), { output: { entity: "chat_inspection" }, effects: REMOTE_READ, offline: false })
         .description("what an invite or public link leads to, without joining it")
         .argument("<link>", "an invite link or a public one")
         .action(async function (link) {
@@ -69,7 +69,7 @@ export const chatsCommand = (messenger) => {
             context.renderer.note(`you left this chat; its stored messages are kept — \`${typedCommand(messenger.app.command, "store clear --left --dry-run", context.settings.profile)}\` lists the chats you left and deletes nothing`);
     }));
     if (messenger.sendAs !== false)
-        annotate(chats.command("send-as"), { effects: REMOTE_READ, offline: false })
+        annotate(chats.command("send-as"), { output: { entity: "chat_sender" }, effects: REMOTE_READ, offline: false })
             .description("who this account may post as in a chat; changes no saved choice")
             .argument("<chat>", messenger.chatArgument)
             .action(async function (chat) {

package/dist/cli/messenger/chats-documents-command.js

@@ -2,26 +2,28 @@ import { annotate } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
 import { REMOTE_READ } from "../effects.js";
 import { listOf, renderAnswer } from "../envelope.js";
+import { queryTerms, typedQuery, withQuery } from "../list-query.js";
 import { positiveCount, window } from "../paging.js";
 import { nextStep } from "../steps.js";
 import { documentLinkAnswer, lines, pageOf } from "./chat-answers.js";
 import { messengerContext } from "./context.js";
+import { DOCUMENT_LINKS_QUERY } from "./document-links-query.js";
 import { syncsFirst } from "./search-sync-options.js";
 /** `chats documents …`: the Google documents linked in a chat's stored messages. */
 export const documentsCommand = (messenger) => {
     const documents = new Command("documents").description("the Google Docs and Drive documents linked in a chat's stored messages");
-    documents.addCommand(annotate(new Command("list"), { effects: REMOTE_READ })
+    documents.addCommand(withQuery(annotate(new Command("list"), { effects: REMOTE_READ })
         .description("every document link in the chat, newest first, and whether the store has it")
         .argument("<chat>", messenger.chatArgument)
         .option("--limit <n>", "how many to show", positiveCount("--limit"))
-        .option("--page <n>", "which page, starting at 1", positiveCount("--page"))
-        .action(async function (chat) {
+        .option("--page <n>", "which page, starting at 1", positiveCount("--page")), DOCUMENT_LINKS_QUERY).action(async function (chat, words) {
+        const ref = queryTerms(words, DOCUMENT_LINKS_QUERY, "chats documents list").get("ref");
         const context = messengerContext(this, messenger);
-        const found = await context.withServices((services) => services.chatDocuments.list(chat, window(context.settings)));
+        const found = await context.withServices((services) => services.chatDocuments.list(chat, { ...window(context.settings), ...(ref === undefined ? {} : { ref }) }));
         renderAnswer(this, context, listOf("chats documents list", {
             items: found.items.map(documentLinkAnswer),
             ...pageOf(context.settings, found),
-            args: { chat },
+            args: { chat, ...(words.length ? { query: typedQuery(words) } : {}) },
             ...(found.empty && syncsFirst(messenger)
                 ? { next: [nextStep("messages.sync", { args: { chat: found.chatId } })] }
                 : {}),

package/dist/cli/messenger/chats-members-command.js

@@ -71,7 +71,11 @@ export const membersCommand = (messenger) => {
             before ? [before.name, before.username ? `@${before.username}` : null].filter(Boolean).join(" ") : "",
         ].join("  ")));
     }));
-    const fetch = annotate(new Command("fetch"), { effects: FETCH, offline: false })
+    const fetch = annotate(new Command("fetch"), {
+        output: { entity: "chat_members_fetch" },
+        effects: FETCH,
+        offline: false,
+    })
         .summary("save the group's current membership")
         .description("read a group's whole member list into the local store's member history: who joined, who left, daily " +
         "counts and profile changes; someone is recorded as gone only when every member was read")
@@ -96,7 +100,7 @@ export const membersCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(fetched)), () => `${fetched.read} members read; ${fetched.joined.length} new, ${fetched.gone.length} gone, ` +
             `${fetched.changed.length} changed their profile${fetched.tracked ? "; tracked daily" : ""}\n`);
     }));
-    const add = annotate(new Command("add"), { effects: REMOTE_WRITE })
+    const add = annotate(new Command("add"), { output: { entity: "chat_members_change" }, effects: REMOTE_WRITE })
         .description("add people; they are told")
         .argument("<chat>", messenger.chatArgument)
         .argument("<person...>", "an id, or part of a name");
@@ -109,7 +113,7 @@ export const membersCommand = (messenger) => {
         const added = await context.withServices((services) => services.admin.addMembers(chat, people, history ? { history } : {}));
         renderAnswer(this, context, itemOf(snakeKeys(added)));
     }));
-    members.addCommand(annotate(new Command("remove"), { effects: REMOTE_WRITE })
+    members.addCommand(annotate(new Command("remove"), { output: { entity: "chat_members_change" }, effects: REMOTE_WRITE })
         .description("remove people; their messages stay")
         .argument("<chat>", messenger.chatArgument)
         .argument("<person...>", "an id, or part of a name")

package/dist/cli/messenger/chats-read-command.js

@@ -4,7 +4,7 @@ import { REMOTE_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { messengerContext } from "./context.js";
 export const markReadCommand = (messenger) => {
-    const read = annotate(new Command("mark-read"), { effects: REMOTE_WRITE })
+    const read = annotate(new Command("mark-read"), { output: { entity: "chat_read" }, effects: REMOTE_WRITE })
         .description("mark a chat read; the other side sees that you read it")
         .argument("<chat>", messenger.chatArgument)
         .option("--until-id <id>", "only up to this message id; the newest by default");

package/dist/cli/messenger/chats-tracking-command.js

@@ -3,19 +3,27 @@ import { Command } from "commander";
 import { TRACKED_DAYS } from "../../services/chats.js";
 import { LOCAL_READ, LOCAL_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
+import { listQuery, typedQuery, withQuery } from "../list-query.js";
 import { lines, wholeList } from "./chat-answers.js";
+import { TRACKING_QUERY } from "./chat-queries.js";
 import { messengerContext, refuseLocalWrite } from "./context.js";
 /** The chats whose member lists `serve` fetches daily; kept in the local store, never sent. */
 export const trackingCommand = (messenger) => {
     const tracking = new Command("tracking")
         .summary("chats whose member lists are fetched daily")
         .description("the chats whose member lists serve fetches daily into the local store — chats members fetch --track adds one");
-    annotate(tracking.command("list"), { effects: LOCAL_READ })
+    withQuery(annotate(tracking.command("list"), { effects: LOCAL_READ }), TRACKING_QUERY)
         .description("every tracked chat: since when, and its last member count")
-        .action(async function () {
+        .action(async function (words) {
+        const query = listQuery(typedQuery(words), TRACKING_QUERY, "chats tracking list");
         const context = messengerContext(this, messenger);
-        const found = await context.withServices((services) => services.chats.tracked());
-        renderAnswer(this, context, wholeList("chats tracking list", found.map((one) => snakeKeys(one))), lines(({ chat_id, title, tracked_at, last_count }) => [
+        const found = await context.withServices((services) => services.chats.tracked(query));
+        renderAnswer(this, context, wholeList("chats tracking list", found.map(({ chatId, title, trackedAt, lastCount }) => ({
+            chat_id: chatId,
+            title,
+            tracked_at: trackedAt,
+            last_count: lastCount,
+        }))), lines(({ chat_id, title, tracked_at, last_count }) => [
             title ? `${title} (${chat_id})` : chat_id,
             tracked_at.slice(0, 10),
             last_count
@@ -23,7 +31,7 @@ export const trackingCommand = (messenger) => {
                 : "",
         ].join("  ")));
     });
-    annotate(tracking.command("show"), { effects: LOCAL_READ })
+    annotate(tracking.command("show"), { effects: LOCAL_READ, output: { entity: "tracked_chat_history" } })
         .summary("one chat's member tracking and daily counts")
         .description(`one chat: whether it is tracked, and its member count per day for the last ${TRACKED_DAYS} days`)
         .argument("<chat>", messenger.chatArgument)
@@ -35,7 +43,7 @@ export const trackingCommand = (messenger) => {
         ["add", true, "fetch this chat's member list daily while serve runs, from its next run"],
         ["remove", false, "stop fetching it daily; the history already kept stays"],
     ]) {
-        annotate(tracking.command(verb), { effects: LOCAL_WRITE })
+        annotate(tracking.command(verb), { effects: LOCAL_WRITE, output: { entity: "chat_tracking" } })
             .description(description)
             .argument("<chat>", messenger.chatArgument)
             .action(async function (chat) {

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

@@ -87,7 +87,10 @@ export const contactsCommand = (messenger) => {
                 : [],
         }));
     });
-    const contextCommand = annotate(contacts.command("context"), { effects: REMOTE_READ })
+    const contextCommand = annotate(contacts.command("context"), {
+        effects: REMOTE_READ,
+        output: { entity: "contact_context" },
+    })
         .summary("what the local archive knows about a person")
         .description("what the store holds about one person, in every messenger linked to them: shared chats, the last " +
         "messages each way, their recent messages, where others mentioned them — never connects")
@@ -142,6 +145,7 @@ export const contactsCommand = (messenger) => {
     });
     annotate(contacts.command("prepare"), {
         effects: REMOTE_READ,
+        output: { entity: "contact_preparation" },
         examples: [`${messenger.app.command} contacts prepare Ana`],
     })
         .summary("what to know before you talk to someone, each item with its reference")
@@ -169,7 +173,7 @@ export const contactsCommand = (messenger) => {
             meta: { ...window.meta, ...(hasMore ? { truncated: true } : {}) },
         }));
     });
-    annotate(contacts.command("timeline"), { effects: REMOTE_READ })
+    annotate(contacts.command("timeline"), { effects: REMOTE_READ, output: { entity: "contact_activity" } })
         .summary("one person's activity across their linked identities")
         .description("everything one person took part in, in every messenger linked to them — messages they wrote or were " +
         "mentioned in, chats, mail, meetings, tasks — newest first, from the store; never connects")
@@ -211,7 +215,7 @@ export const contactsCommand = (messenger) => {
             meta: { ...window.meta, ...(pending > 0 ? { truncated: true } : {}) },
         }));
     });
-    annotate(contacts.command("check"), { effects: REMOTE_READ })
+    annotate(contacts.command("check"), { effects: REMOTE_READ, output: { entity: "contact_check" } })
         .summary("check a person's profile and messages for signs of abuse")
         .description(registriesCover(messenger.provider)
         ? "whether one person looks like a bot, a fake or a spammer: their profile, what they wrote in the store, " +
@@ -239,7 +243,7 @@ export const contactsCommand = (messenger) => {
         const { notes: _, ...answer } = checked;
         renderAnswer(this, context, itemOf(snakeKeys(answer)));
     });
-    annotate(contacts.command("link"), { effects: LOCAL_WRITE })
+    annotate(contacts.command("link"), { effects: LOCAL_WRITE, output: { entity: "linked_person" } })
         .summary("link identities that belong to one person")
         .description("record that two people in the store are one person — the same name is never enough")
         .argument("<person>", "their id, @username, or part of their name")
@@ -250,7 +254,7 @@ export const contactsCommand = (messenger) => {
         renderAnswer(this, context, itemOf(snakeKeys(linked)));
         context.renderer.success(`${linked.identities.length} identities are now one person`);
     });
-    annotate(contacts.command("unlink"), { effects: LOCAL_WRITE })
+    annotate(contacts.command("unlink"), { effects: LOCAL_WRITE, output: { entity: "linked_person" } })
         .description("undo contacts link for one identity: it is a person of its own again")
         .argument("<person>", "their id, @username, or part of their name; <messenger>:<person> for another messenger")
         .action(async function (person) {

package/dist/cli/messenger/conversations-command.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,7 +34,7 @@ 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")
@@ -130,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`)
@@ -159,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")
@@ -175,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")
@@ -193,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 () {
@@ -203,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 () {
@@ -230,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,
@@ -247,7 +248,7 @@ 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)
@@ -260,7 +261,7 @@ export const conversationsCommand = (messenger) => {
         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 --embedding-provider through a service and your key; resumes where it stopped; without --chat, every " +
@@ -307,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 () {
@@ -321,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 () {
@@ -338,6 +339,7 @@ export const conversationsCommand = (messenger) => {
         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`],
     }))
@@ -359,18 +361,19 @@ 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")
         .addOption(new Option("--consent-provider <identity>", "exact provider identity from consents list; defaults to every provider").conflicts("provider"))
@@ -505,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,
 })
@@ -540,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;