@wirecat/cli-core 0.398.0 → 0.400.0

package/dist/cli/bot/people.js

@@ -11,6 +11,7 @@ import { messageItem } from "../messenger/message-items.js";
 import { positiveCount } from "../paging.js";
 import { asFirstWord } from "../profile.js";
 import { botContext } from "./context.js";
+import { botExamples } from "./examples.js";
 import { botCan } from "./messages.js";
 import { ChatRegistry, registryProfiles } from "./registry.js";
 /** What "common chats" rests on: who has written where in this copy, not who is a member. */
@@ -122,13 +123,16 @@ const cardOf = async (store, context, bot, who, across, limit) => {
 };
 /** `bot contacts show`: one person this bot has seen write, from the local copy. */
 export const botContactsCommand = (bot) => {
-    const command = new Command("contacts").description(`people this bot has seen write — from the local copy on this machine, never asking ${bot.name ?? "the messenger"} unless told to`);
-    acrossOptions(annotate(command.command("show"), { effects: REMOTE_READ }))
+    const command = new Command("contacts")
+        .description(`people this bot has seen write — from the local copy on this machine, never asking ${bot.name ?? "the messenger"} unless told to`)
+        .summary("the people this bot has seen write, from the local copy");
+    acrossOptions(annotate(command.command("show"), { effects: REMOTE_READ, examples: botExamples(bot, "contacts show @ann") }))
         .argument("<who>", "an id, @username or part of a name")
         .option("--limit <n>", "how many messages from the private chat", positiveCount("--limit"))
         .option("--sync-first", "read the private chat with them again from the messenger first — one request")
         .description("one person: the chats they wrote in (with their last message there) and the latest messages of their " +
         "private chat with the bot")
+        .summary("one person: the chats they wrote in and their chat with the bot")
         .action(async function (who, options) {
         const context = botContext(this, bot);
         const across = { allBots: options.allBots === true, bots: options.bots ?? [] };
@@ -186,7 +190,10 @@ const search = (context, bot, text, from, options) => {
 /** `bot search messages`: the messages this bot's local copy holds. */
 export const botSearchCommand = (bot) => {
     const group = new Command("search").description("find what this bot's local copy holds, by text");
-    acrossOptions(annotate(group.command("messages"), { effects: REMOTE_READ }))
+    acrossOptions(annotate(group.command("messages"), {
+        effects: REMOTE_READ,
+        examples: botExamples(bot, "search messages refund", "search messages invoice --from @ann"),
+    }))
         .argument("[query...]", "the words to find")
         .option("--limit <n>", "how many", positiveCount("--limit"))
         .option("--page <n>", "which page, starting at 1", positiveCount("--page"))
@@ -195,6 +202,7 @@ export const botSearchCommand = (bot) => {
         .description("search the messages this bot has read, sent or received on this machine — the local copy only, best " +
         'match first; a Lucene query: every word must appear; "a phrase", -word, a OR b, from: chat: date: has:; ' +
         "by text, by --from, or both")
+        .summary("search the messages this bot has seen, in the local copy, by text")
         .action(async function (query, options) {
         const context = botContext(this, bot);
         const limit = options.limit ?? context.settings.limit;
@@ -222,12 +230,16 @@ export const botSearchCommand = (bot) => {
 };
 /** `bot messages between`, over the local copy, added to the shared `messages` group. */
 export const addBotCopyReads = (messages, bot) => {
-    acrossOptions(annotate(messages.command("between"), { effects: REMOTE_READ }))
+    acrossOptions(annotate(messages.command("between"), {
+        effects: REMOTE_READ,
+        examples: botExamples(bot, "messages between @ann @bob"),
+    }))
         .argument("<people...>", "two or more people — an id, @username or part of a name each")
         .option("--limit <n>", "how many of the latest messages from each chat", positiveCount("--limit"))
         .description("what two or more people wrote in the chats they have all written in — from the local copy, grouped by " +
         "chat, oldest first; --limit counts per chat. Common chats are the ones this copy saw each of them " +
         `write in, not a member list from ${bot.name ?? "the messenger"}`)
+        .summary("what two or more people wrote in the chats they share, from the local copy")
         .action(async function (references, options) {
         const context = botContext(this, bot);
         if (references.length < 2)

package/dist/cli/bot/setup.js

@@ -7,6 +7,7 @@ import { REMOTE_READ, REMOTE_WRITE } from "../effects.js";
 import { itemOf, renderAnswer, snakeKeys } from "../envelope.js";
 import { wholeList } from "../messenger/chat-answers.js";
 import { botContext, online } from "./context.js";
+import { botExamples } from "./examples.js";
 import { botCan } from "./messages.js";
 import { botFiles } from "./registry.js";
 import { PressLog } from "./updates.js";
@@ -30,7 +31,7 @@ const botWrite = (context, key, write) => guardedWrite(context.guard(), { operat
 /** `bot commands`: the menu people see when they type `/`. */
 export const botMenuCommand = (bot) => {
     const command = new Command("commands").description("the bot's command menu — what people see after /");
-    annotate(command.command("list"), { effects: REMOTE_READ })
+    annotate(command.command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "commands list") })
         .description("the commands in the menu now")
         .action(async function () {
         const context = online(botContext(this, bot), this);
@@ -48,13 +49,19 @@ export const botMenuCommand = (bot) => {
             renderAnswer(command, context, wholeList("bot commands list", entries));
         });
     };
-    annotate(command.command("set"), { effects: REMOTE_WRITE })
+    annotate(command.command("set"), {
+        effects: REMOTE_WRITE,
+        examples: botExamples(bot, 'commands set "start=Begin here" "help=What I can do"'),
+    })
         .description("replace the whole menu: each command as name=description, e.g. start=Begin")
         .argument("<commands...>", "name=description, one per command")
         .action(async function (typed) {
         await replace(this, typed.map(entryOf), "bot.commands.set");
     });
-    annotate(command.command("clear"), { effects: REMOTE_WRITE })
+    annotate(command.command("clear"), {
+        effects: REMOTE_WRITE,
+        examples: botExamples(bot, "commands clear"),
+    })
         .description("empty the menu")
         .action(async function () {
         await replace(this, [], "bot.commands.clear");
@@ -62,9 +69,13 @@ export const botMenuCommand = (bot) => {
     return command;
 };
 /** `bot callbacks`: answers to the buttons people press under the bot's messages. */
-export const botCallbacksCommand = (bot) => new Command("callbacks").description("answers to the buttons people press under the bot's messages").addCommand(annotate(new Command("answer"), { effects: REMOTE_WRITE })
+export const botCallbacksCommand = (bot) => new Command("callbacks").description("answers to the buttons people press under the bot's messages").addCommand(annotate(new Command("answer"), {
+    effects: REMOTE_WRITE,
+    examples: botExamples(bot, 'callbacks answer 4385 --notification "Saved"'),
+})
     .description("answer a pressed button by its callback id: --notification shows the person a one-time note, " +
     "--text replaces the message the button was on")
+    .summary("answer a pressed button: a note to that person, or new message text")
     .argument("<callback>", "the callback id `bot watch` printed")
     .option("--text <text>", "the message's new text")
     .option("--notification <text>", "a note only the person who pressed sees")
@@ -97,8 +108,10 @@ export const botCallbacksCommand = (bot) => new Command("callbacks").description
 }));
 /** `bot webhooks`: where the messenger pushes this bot's updates instead of being polled. */
 export const botWebhooksCommand = (bot) => {
-    const command = new Command("webhooks").description("where the messenger pushes this bot's updates — while one is set, `bot watch` gets nothing");
-    annotate(command.command("list"), { effects: REMOTE_READ })
+    const command = new Command("webhooks")
+        .description("where the messenger pushes this bot's updates — while one is set, `bot watch` gets nothing")
+        .summary("where the messenger pushes this bot's updates");
+    annotate(command.command("list"), { effects: REMOTE_READ, examples: botExamples(bot, "webhooks list") })
         .description("the webhooks this bot has")
         .action(async function () {
         const context = online(botContext(this, bot), this);
@@ -107,7 +120,10 @@ export const botWebhooksCommand = (bot) => {
             renderAnswer(this, context, wholeList("bot webhooks list", (await botCan(adapter, "webhooks", bot, "list its webhooks")()).map(snakeKeys)));
         });
     });
-    const set = annotate(command.command("set"), { effects: REMOTE_WRITE })
+    const set = annotate(command.command("set"), {
+        effects: REMOTE_WRITE,
+        examples: botExamples(bot, "webhooks set https://bot.example.ts.net/"),
+    })
         .description("send this bot's updates to an HTTPS address; refused while another is set")
         .argument("<url>", "the HTTPS address")
         .option("--types <types>", "only these update types, comma-separated, in the messenger's words")
@@ -138,7 +154,10 @@ export const botWebhooksCommand = (bot) => {
             renderAnswer(this, context, wholeList("bot webhooks list", (await list()).map(snakeKeys)));
         });
     });
-    annotate(command.command("delete"), { effects: REMOTE_WRITE })
+    annotate(command.command("delete"), {
+        effects: REMOTE_WRITE,
+        examples: botExamples(bot, "webhooks delete https://bot.example.ts.net/"),
+    })
         .description("stop sending updates to this address; with none left, `bot watch` works again")
         .argument("<url>", "the address")
         .action(async function (url) {

package/dist/cli/bot/watch.js

@@ -7,6 +7,7 @@ import { environmentOf } from "../context.js";
 import { REMOTE_WRITE } from "../effects.js";
 import { withoutProviderRefs } from "../provider-refs.js";
 import { botContext, online } from "./context.js";
+import { botExamples } from "./examples.js";
 import { botCan, botIdOf } from "./messages.js";
 import { botFiles } from "./registry.js";
 import { PressLog, UpdatesCursor } from "./updates.js";
@@ -83,8 +84,13 @@ const keep = async (command, context, bot, botId, events, senders) => {
  * With `--public-url` the messenger pushes each batch to a local receiver behind the owner's tunnel
  * instead, and a batch is acknowledged only once kept, so the messenger sends again what was not.
  */
-export const botWatchCommand = (bot) => annotate(new Command("watch"), { effects: REMOTE_WRITE, lifetime: "persistent" })
+export const botWatchCommand = (bot) => annotate(new Command("watch"), {
+    effects: REMOTE_WRITE,
+    lifetime: "persistent",
+    examples: botExamples(bot, "watch --jsonl", "watch --events"),
+})
     .description("print new messages as they arrive and keep them, until Ctrl-C or --timeout (either ends it normally)")
+    .summary("print new messages as they arrive and keep them, until Ctrl-C")
     .option("--events", "also edits, deletions, buttons pressed and people coming and going; every line names its event")
     .option("--types <types>", "only these update types, comma-separated, in the messenger's words")
     .option("--public-url <url>", "receive by webhook at your tunnel's https address instead of polling, e.g. https://<name>.ts.net")

package/dist/cli/config-command.js

@@ -2,8 +2,9 @@ import { CliError, pathsAreOverridden } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
 import { envName } from "../ports/app.js";
+import { AUTHORITY_KEY } from "../sends/permissions.js";
 import { loadSnakeCaseConfig } from "./config-keys.js";
-import { baseContext } from "./context.js";
+import { baseContext, environmentOf } from "./context.js";
 import { grantsAuthority, LOCAL_READ, LOCAL_WRITE } from "./effects.js";
 import { itemOf, renderAnswer } from "./envelope.js";
 import { knownBeside, knownPermissionKeys } from "./permission-keys.js";
@@ -94,6 +95,8 @@ export const configCommand = (app, config, { permissionKey } = {}) => {
                 // The defaults are every other profile's settings too, and default_profile picks one of them.
                 throw new CliError("permission_error", `this process is locked to profile ${settings.profile} (${lock}) — ${setting === "default_profile" ? setting : "--defaults"} changes other profiles`);
             }
+            if (environmentOf(this).agent)
+                refuseAuthorityKey(setting, action === "set" ? String(given) : undefined);
             if (action === "set")
                 refuseUnknownKey(this, setting, String(given), permissionKey);
             const saved = config.changeSetting(settings.configPath, {
@@ -133,6 +136,22 @@ export const refuseUnknownKey = (command, setting, value, permissionKey) => {
             (beside.length > 0 ? ` — the known ones there are ${beside.join(", ")}` : ""));
     }
 };
+/**
+ * An agent may hold `mcp.authority` and change other settings, but never the key that let it in: on any profile, in
+ * the defaults, or by replacing `permissions` whole. Only the owner, in a terminal, turns it on or off (NEED-1662).
+ */
+const refuseAuthorityKey = (setting, value) => {
+    const keys = setting.startsWith("permissions.")
+        ? [setting.slice("permissions.".length)]
+        : setting === "permissions"
+            ? value === undefined
+                ? ["mcp"]
+                : objectKeys(value)
+            : [];
+    if (!keys.some((key) => key === "mcp" || key.startsWith("mcp.")))
+        return;
+    throw new CliError("permission_error", `an agent cannot change permissions.${AUTHORITY_KEY} — the owner sets it in a terminal`, { permission: AUTHORITY_KEY });
+};
 /** The keys of a `permissions` object given whole; anything else is left to the schema to refuse. */
 const objectKeys = (value) => {
     try {

package/dist/cli/context.d.ts

@@ -85,6 +85,8 @@ export interface AgentRun {
     failure: (error: ErrorObject) => void;
     /** The server's own stricter levels, `key=level`, as `mcp --permission` takes them; they never loosen. */
     overrides?: readonly string[];
+    /** The server's levels allow `mcp.authority`: a command that changes what a later run may do may run. */
+    authority?: boolean;
 }
 export interface RelayedRun {
     /** The profile serve holds; a command for another is refused before it touches the connection. */

package/dist/cli/context.js

@@ -72,7 +72,7 @@ export const baseContext = (command, resolveSettings) => {
         run: (body, { unbounded = false, name } = {}) => environment.app
             ? recorded({
                 app: environment.app,
-                // An agent's run is named `mcp <command>`, so `runs search` and `sends list` tell it from the owner's.
+                // An agent's run is named `mcp <command>`, so `search runs` and `sends list` tell it from the owner's.
                 command: name ?? `${environment.agent ? "mcp " : ""}${commandPath(command)}`,
                 profile: settings.profile,
                 record: settings.record,

package/dist/cli/effects.d.ts

@@ -14,13 +14,16 @@ export declare const NO_EFFECTS: Effects;
 /**
  * Marks a local write that changes what a later run may do: a schedule, a setting, the recipient list, an
  * auto-reply, an agent's setup. `<PREFIX>_READ_ONLY` refuses it, or an agent under the lock could hand an
- * unlocked run the send it may not make itself (SEC-47). For the same reason no MCP server offers it (`mcp: false`).
+ * unlocked run the send it may not make itself (SEC-47). For the same reason an MCP server offers it only where the
+ * profile allows `mcp.authority`, which is off until the owner turns it on (NEED-1662).
  * `unless` names a flag that makes the run only look (`upgrade --check`), which the lock lets through.
  */
 export declare const grantsAuthority: <T extends Command>(command: T, { unless }?: {
     unless?: string;
 }) => T;
 export declare const changesAuthority: (command: Command) => boolean;
+/** `changesAuthority` by command path under `root`, as an MCP catalogue asks it; an unknown path is not one. */
+export declare const changesAuthorityAt: (root: Command) => (path: readonly string[]) => boolean;
 export declare const changesAuthorityNow: (command: Command) => boolean;
 /**
  * Marks a command that links or unlinks the account — `session start`, `session end`, a setup that logs in. It never

package/dist/cli/effects.js

@@ -16,14 +16,22 @@ const AUTHORITY = new WeakMap();
 /**
  * Marks a local write that changes what a later run may do: a schedule, a setting, the recipient list, an
  * auto-reply, an agent's setup. `<PREFIX>_READ_ONLY` refuses it, or an agent under the lock could hand an
- * unlocked run the send it may not make itself (SEC-47). For the same reason no MCP server offers it (`mcp: false`).
+ * unlocked run the send it may not make itself (SEC-47). For the same reason an MCP server offers it only where the
+ * profile allows `mcp.authority`, which is off until the owner turns it on (NEED-1662).
  * `unless` names a flag that makes the run only look (`upgrade --check`), which the lock lets through.
  */
 export const grantsAuthority = (command, { unless } = {}) => {
     AUTHORITY.set(command, unless);
-    return annotate(command, { mcp: false });
+    return command;
 };
 export const changesAuthority = (command) => AUTHORITY.has(command);
+/** `changesAuthority` by command path under `root`, as an MCP catalogue asks it; an unknown path is not one. */
+export const changesAuthorityAt = (root) => (path) => {
+    let at = root;
+    for (const word of path)
+        at = at?.commands.find((one) => one.name() === word);
+    return at !== undefined && changesAuthority(at);
+};
 export const changesAuthorityNow = (command) => {
     if (!AUTHORITY.has(command))
         return false;

package/dist/cli/embedding-choice.d.ts

@@ -3,6 +3,7 @@ import { type AISettings } from "../analysis/settings.js";
 import { type AppIdentity } from "../ports/app.js";
 import type { ModelChoice } from "../services/embeddings.js";
 export interface ModelOptions {
+    embeddingProvider?: string;
     model?: string;
     provider?: string;
     baseUrl?: string;
@@ -10,7 +11,7 @@ export interface ModelOptions {
     concurrency?: number;
 }
 /** A local model id, or a remote model with its key from `models text key set`. */
-export declare const embeddingChoice: ({ model, provider, baseUrl, dims, concurrency }: ModelOptions, app: AppIdentity, settings: AISettings, env: NodeJS.ProcessEnv, { needKey, keyring }?: {
+export declare const embeddingChoice: ({ model, provider, embeddingProvider, baseUrl, dims, concurrency }: ModelOptions, app: AppIdentity, settings: AISettings, env: NodeJS.ProcessEnv, { needKey, keyring }?: {
     needKey?: boolean;
     keyring?: KeyringStore | undefined;
 }) => ModelChoice;

package/dist/cli/embedding-choice.js

@@ -6,7 +6,10 @@ import { isLocal, remoteModel } from "../embeddings/remote.js";
 import { readOnlyLockOf, readOnlyRefusal } from "../ports/app.js";
 import { typedCommand } from "../runs/scope.js";
 /** A local model id, or a remote model with its key from `models text key set`. */
-export const embeddingChoice = ({ model, provider, baseUrl, dims, concurrency }, app, settings, env, { needKey = true, keyring } = {}) => {
+export const embeddingChoice = ({ model, provider, embeddingProvider, baseUrl, dims, concurrency }, app, settings, env, { needKey = true, keyring } = {}) => {
+    if (embeddingProvider !== undefined && provider !== undefined)
+        throw new CliError("validation_error", "give --embedding-provider or its legacy --provider spelling, not both");
+    provider = embeddingProvider ?? provider;
     const flagsChooseProvider = (provider !== undefined && provider !== (settings.embeddingProvider ?? "local")) ||
         (baseUrl !== undefined && baseUrl.replace(/\/+$/, "") !== settings.embeddingBaseUrl?.replace(/\/+$/, ""));
     provider ??= flagsChooseProvider ? "openai" : (settings.embeddingProvider ?? "local");

package/dist/cli/index.d.ts

@@ -53,7 +53,7 @@ export { loadSnakeCaseConfig } from "./config-keys.js";
 export { type AgentRun, type BaseContext, type BaseEnvironment, baseContext, environmentOf, outputFor, provide, secretInputOf, } from "./context.js";
 export { type Closeable, withDeadline } from "./deadline.js";
 export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
-export { changesAuthority, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
+export { changesAuthority, changesAuthorityAt, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
 export { type AnswerOutput, answerSchema, type Body, type ItemBody, itemAnswer, itemOf, jsonlRecords, judgedAnswer, type ListBody, type ListInput, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
 export { checkGuide, checkStep, type GuideOptions, type GuideReference, type GuideStep, guideCommand, loadScenarios, MEMO_SCENARIOS, type Scenario, shellProblems, } from "./guide.js";

package/dist/cli/index.js

@@ -48,7 +48,7 @@ export { loadSnakeCaseConfig } from "./config-keys.js";
 export { baseContext, environmentOf, outputFor, provide, secretInputOf, } from "./context.js";
 export { withDeadline } from "./deadline.js";
 export { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
-export { changesAuthority, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
+export { changesAuthority, changesAuthorityAt, destroysNothing, FETCH, grantsAuthority, isLogin, isOtherServiceCall, isStoreChange, judgedEffects, judgedTargets, LOCAL_READ, LOCAL_WRITE, logsInOrOut, NO_EFFECTS, ownerOnlyOption, REMOTE_READ, REMOTE_WRITE, reachesOtherService, refuseUnderReadOnly, } from "./effects.js";
 export { answerSchema, itemAnswer, itemOf, jsonlRecords, judgedAnswer, listOf, metaNow, printItem, renderAnswer, sealed, snakeKeys, snakeKeysKeeping, } from "./envelope.js";
 export { withAbort } from "./execution.js";
 export { checkGuide, checkStep, guideCommand, loadScenarios, MEMO_SCENARIOS, shellProblems, } from "./guide.js";

package/dist/cli/json-fields.js

@@ -21,6 +21,17 @@ export const entityFields = (table) => {
         return name !== undefined && Object.hasOwn(table, name) ? namesOf(table[name]) : undefined;
     };
 };
+const schemaFields = (schema) => {
+    if (typeof schema !== "object" || schema === null)
+        return undefined;
+    if ("entries" in schema && typeof schema.entries === "object" && schema.entries !== null)
+        return Object.keys(schema.entries);
+    if ("type" in schema && schema.type === "union" && "options" in schema && Array.isArray(schema.options)) {
+        const branches = schema.options.map(schemaFields);
+        return branches.every((fields) => fields !== undefined) ? [...new Set(branches.flat())] : undefined;
+    }
+    return undefined;
+};
 /** The fields of the answer a command declares (`annotate(…, { output })`); nothing until it declares one. */
 export const answerFields = (command, resolve) => {
     const own = resolve?.(command);
@@ -28,7 +39,7 @@ export const answerFields = (command, resolve) => {
         return [...own];
     const name = declaredEntity(command);
     const schema = name === undefined ? undefined : ENTITIES[name];
-    return schema && "entries" in schema ? namesOf(schema) : undefined;
+    return schemaFields(schema);
 };
 const PATHS = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*(,[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*)*$/;
 const topOf = (fields, known) => fields.split(",").map((path) => {

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

@@ -6,7 +6,9 @@ import { storePath } from "../../store/path.js";
 import { openStore } from "../../store/store.js";
 import { REMOTE_READ, REMOTE_WRITE } from "../effects.js";
 import { itemOf, renderAnswer } from "../envelope.js";
+import { queryTerms, withQuery } from "../list-query.js";
 import { NONE_NAMED } from "../settings.js";
+import { ACCOUNT_PROFILES_QUERY } from "./account-profile-query.js";
 import { accountSessionsCommand } from "./account-sessions-command.js";
 import { recalledAccount } from "./accounts.js";
 import { photoHelp, readProfilePhoto } from "./admin-commands.js";
@@ -18,16 +20,19 @@ export const accountCommand = (messenger) => {
     const tool = `${messenger.app.command} personal`;
     const account = new Command("account")
         .description("the logged-in account")
-        .addCommand(annotate(new Command("list"), { effects: REMOTE_READ, examples: [`${tool} account list`] })
+        .addCommand(withQuery(annotate(new Command("list"), { effects: REMOTE_READ, examples: [`${tool} account list`] }), ACCOUNT_PROFILES_QUERY)
         .summary("profiles on this computer and their signed-in accounts")
         .description("every profile on this computer, and the account each is logged in as; asks the messenger nothing")
-        .action(async function () {
+        .action(async function (words) {
+        const terms = queryTerms(words, ACCOUNT_PROFILES_QUERY, "account list");
         const context = messengerContext(this, messenger, { needsProfile: false });
         const { app, provider } = messenger;
         const current = context.settings.sources.profile === NONE_NAMED ? undefined : context.settings.profile;
-        const profiles = [
-            ...new Set([...(current === undefined ? [] : [current]), ...context.settings.profilesHere]),
-        ].sort();
+        const profiles = [...new Set([...(current === undefined ? [] : [current]), ...context.settings.profilesHere])]
+            .filter((profile) => terms.get("profile") === undefined || profile === terms.get("profile"))
+            .filter((profile) => terms.get("current") === undefined ||
+            (profile === current) === (terms.get("current")?.toLowerCase() === "true"))
+            .sort();
         const store = existsSync(storePath(context.env))
             ? await openStore({ env: context.env }).catch(() => undefined)
             : undefined;
@@ -61,7 +66,11 @@ export const accountCommand = (messenger) => {
         const account = await context.withMessenger((connection) => connection.me());
         renderAnswer(this, context, itemOf(accountAnswer(messenger.provider, whole ? account : maskedAccount(account))));
     }))
-        .addCommand(annotate(new Command("update"), { effects: REMOTE_WRITE, examples: [`${tool} account update --first-name Alex`] })
+        .addCommand(annotate(new Command("update"), {
+        effects: REMOTE_WRITE,
+        output: { entity: "account_change" },
+        examples: [`${tool} account update --first-name Alex`],
+    })
         .description("change the name, the description or the photo everyone sees on your profile")
         .option("--first-name <name>", "your first name")
         .option("--last-name <name>", "your last name")

package/dist/cli/messenger/account-profile-query.d.ts

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

package/dist/cli/messenger/account-profile-query.js

@@ -0,0 +1,13 @@
+import { queryFieldsOf } from "@wirecat/cli-base/query";
+import { accountProfile } from "../../entities/index.js";
+export const ACCOUNT_PROFILES_QUERY = {
+    entity: "account_profile",
+    backend: "native",
+    fields: queryFieldsOf(accountProfile, {
+        native: ["profile", "current"],
+        examples: { profile: "profile:work", current: "current:true" },
+    }).map((field) => ({
+        ...field,
+        operators: field.operators.filter((operator) => operator === "term" || operator === "phrase"),
+    })),
+};

package/dist/cli/messenger/account-sessions-command.js

@@ -26,6 +26,7 @@ export const accountSessionsCommand = (messenger) => {
     // No MCP tool, at any permission level: it logs the owner out of the phone.
     sessions.addCommand(annotate(new Command("end"), {
         effects: REMOTE_WRITE,
+        output: { entity: "ended_account_sessions" },
         mcp: false,
         examples: [`${tool} account sessions end --others`],
     })

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

@@ -1,6 +1,6 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
-import { Command } from "commander";
+import { Command, Option } from "commander";
 import { parseDuration } from "../../domain/duration.js";
 import { ADMIN_RIGHTS, GROUP_SETTINGS, } from "../../domain/models.js";
 import { readUpload, typesText } from "../../sends/upload.js";
@@ -22,19 +22,19 @@ const SETTING_FLAGS = {
     onlyAdminsSend: ["only-admins-send <on|off>", "only admins may send messages"],
     onlyAdminsEditInfo: ["only-admins-edit-info <on|off>", "only admins may change the name, photo and description"],
     disappearingSeconds: [
-        "disappear-time <duration|off>",
+        "disappear-after <duration|off>",
         "new messages disappear this long after sending: 24h, 7d, 90d; off keeps them",
     ],
 };
 const flagOf = (key) => `--${SETTING_FLAGS[key][0].split(" ")[0]}`;
-/** Where commander puts the flag's value: `--disappear-time` is `disappearTime`, not the setting's own name. */
+/** Where commander puts the flag's value: `--disappear-after` is `disappearAfter`, not the setting's own name. */
 const optionKey = (key) => flagOf(key)
     .slice(2)
     .replace(/-(\w)/g, (_, letter) => letter.toUpperCase());
 const settingsOf = (keys, options) => {
     const changes = {};
     for (const key of keys) {
-        const value = options[optionKey(key)];
+        const value = options[optionKey(key)] ?? (key === "disappearingSeconds" ? options.disappearTime : undefined);
         if (value === undefined)
             continue;
         if (key === "disappearingSeconds") {
@@ -57,7 +57,7 @@ export const readProfilePhoto = (messenger, path, env) => readUpload("photo", pa
 });
 const updateCommand = (messenger) => {
     const keys = messenger.groupSettings ?? GROUP_SETTINGS;
-    const update = annotate(new Command("update"), { effects: REMOTE_WRITE })
+    const update = annotate(new Command("update"), { output: { entity: "chat_group_change" }, effects: REMOTE_WRITE })
         .summary("change a group or channel's profile and settings")
         .description("rename a group or channel, change its description, or turn one of its settings on or off")
         .argument("<chat>", messenger.chatArgument)
@@ -67,8 +67,16 @@ const updateCommand = (messenger) => {
         update.option("--photo <file>", `a new photo for it — ${photoHelp(messenger)}`);
     if (messenger.groupPhotoRemoval === true)
         update.option("--remove-photo", "take its photo away; not with --photo");
-    for (const key of keys)
-        update.option(`--${SETTING_FLAGS[key][0]}`, SETTING_FLAGS[key][1]);
+    for (const key of keys) {
+        const option = new Option(`--${SETTING_FLAGS[key][0]}`, SETTING_FLAGS[key][1]);
+        if (key === "disappearingSeconds")
+            option.conflicts("disappearTime");
+        update.addOption(option);
+    }
+    if (keys.includes("disappearingSeconds"))
+        update.addOption(new Option("--disappear-time <duration|off>", "compatibility alias for --disappear-after")
+            .hideHelp()
+            .conflicts("disappearAfter"));
     return update.action(async function (chat) {
         const context = messengerContext(this, messenger);
         const { title, description, photo, removePhoto, ...rest } = this.opts();
@@ -85,7 +93,7 @@ const updateCommand = (messenger) => {
 };
 const linkCommand = (messenger) => {
     const link = new Command("link").description("a group's invite link");
-    annotate(link.command("show"), { effects: REMOTE_READ })
+    annotate(link.command("show"), { output: { entity: "chat_invite" }, effects: REMOTE_READ })
         .description("the invite link, if you may see it")
         .argument("<chat>", messenger.chatArgument)
         .action(async function (chat) {
@@ -93,7 +101,7 @@ const linkCommand = (messenger) => {
         renderItem(this, context, await context.withServices((services) => services.admin.link(chat)));
     });
     if (messenger.inviteLinkCreate !== false)
-        link.addCommand(annotate(new Command("create"), { effects: REMOTE_WRITE })
+        link.addCommand(annotate(new Command("create"), { output: { entity: "chat_invite_change" }, effects: REMOTE_WRITE })
             .description("make another invite link; nobody is told until you share it")
             .argument("<chat>", messenger.chatArgument)
             .option("--approval", "who joins by it asks first, and an admin lets them in; it then has no use limit")
@@ -124,7 +132,7 @@ const linkCommand = (messenger) => {
             ].join("  ")));
         }));
     if (messenger.inviteLinkRevoke !== false)
-        link.addCommand(annotate(new Command("revoke"), { effects: REMOTE_WRITE })
+        link.addCommand(annotate(new Command("revoke"), { output: { entity: "chat_invite_change" }, effects: REMOTE_WRITE })
             .description("stop one link; for the group's own link, the answer is the new one")
             .argument("<chat>", messenger.chatArgument)
             .argument("<link>", "the link, as `chats link list` shows it")
@@ -133,7 +141,7 @@ const linkCommand = (messenger) => {
             renderItem(this, context, await context.withServices((services) => services.admin.revokeLink(chat, link)));
         }));
     if (messenger.inviteLinkUpdate === true)
-        link.addCommand(annotate(new Command("update"), { effects: REMOTE_WRITE })
+        link.addCommand(annotate(new Command("update"), { output: { entity: "chat_invite_change" }, effects: REMOTE_WRITE })
             .description("change one of your invite links, the group's own one too")
             .argument("<chat>", messenger.chatArgument)
             .argument("<link>", "the link, as `chats link list` shows it")
@@ -150,7 +158,7 @@ const linkCommand = (messenger) => {
                 ...(maxUses === undefined ? {} : { maxUses }),
             })));
         }));
-    link.addCommand(annotate(new Command("reset"), { effects: REMOTE_WRITE })
+    link.addCommand(annotate(new Command("reset"), { output: { entity: "chat_group_change" }, effects: REMOTE_WRITE })
         .description("replace the invite link; the old one stops working")
         .argument("<chat>", messenger.chatArgument)
         .action(async function (chat) {
@@ -163,7 +171,7 @@ const adminsCommand = (messenger) => {
     const offered = messenger.adminRights ?? ADMIN_RIGHTS;
     const admins = new Command("admins").description("give or take back a member's admin rights");
     const picks = messenger.pickAdminRights !== false;
-    const add = annotate(new Command("add"), { effects: REMOTE_WRITE })
+    const add = annotate(new Command("add"), { output: { entity: "chat_admin_change" }, effects: REMOTE_WRITE })
         .summary(picks ? "make a member an admin with these rights" : "make a member an admin, with every right")
         .description(picks
         ? "make a member an admin with these rights"
@@ -177,7 +185,7 @@ const adminsCommand = (messenger) => {
         const rights = picks ? rightsOf(offered, this.opts().can) : [...offered];
         renderItem(this, context, await context.withServices((services) => services.admin.addAdmin(chat, person, rights)));
     }));
-    admins.addCommand(annotate(new Command("remove"), { effects: REMOTE_WRITE })
+    admins.addCommand(annotate(new Command("remove"), { output: { entity: "chat_admin_change" }, effects: REMOTE_WRITE })
         .description("take an admin's rights back; they stay a member")
         .argument("<chat>", messenger.chatArgument)
         .argument("<person>", "an id, or part of a name")
@@ -210,18 +218,19 @@ const requestsCommand = (messenger) => {
         renderAnswer(this, context, body, lines(({ person_id, name, username, requested_at }) => [person_id, name ?? "", username ? `@${username}` : "", requested_at ?? ""].join("  ")));
     }));
     const everyone = messenger.joinRequestsAll !== false;
+    const byLink = everyone && messenger.joinRequestsByLink !== false;
     for (const [verb, accept, help] of [
         ["accept", true, "let them in; the group sees them join"],
         ["decline", false, "turn the request away"],
     ]) {
-        const answer = annotate(new Command(verb), { effects: REMOTE_WRITE })
+        const answer = annotate(new Command(verb), { output: { entity: "chat_request_change" }, effects: REMOTE_WRITE })
             .description(help)
             .argument("<chat>", messenger.chatArgument)
             .argument(everyone ? "[person]" : "<person>", "who asked: an id from `chats requests list`");
         if (everyone)
-            answer
-                .option("--all", "every pending request, counted against the hourly limit first")
-                .option("--link <link>", "with --all: only the requests made by this invite link");
+            answer.option("--all", "every pending request, counted against the hourly limit first");
+        if (byLink)
+            answer.option("--link <link>", "with --all: only the requests made by this invite link");
         requests.addCommand(answer.action(async function (chat, person) {
             const context = messengerContext(this, messenger);
             const { all, link } = this.opts();
@@ -238,7 +247,7 @@ const requestsCommand = (messenger) => {
 };
 /** `chats create`, `join`, `leave`, `update` and `link`: the help text is max-cli's, the one both tools say (standard, help rule 2). */
 export const groupCommands = (messenger) => [
-    annotate(new Command("create"), { effects: REMOTE_WRITE })
+    annotate(new Command("create"), { output: { entity: "chat_group_change" }, effects: REMOTE_WRITE })
         .description("create a group or a channel; the people added are told")
         .argument("<title>", "the group's name")
         .argument("[person...]", "people to add: an id, or part of a name")
@@ -248,14 +257,14 @@ export const groupCommands = (messenger) => [
         const { channel } = this.opts();
         renderItem(this, context, await context.withServices((services) => services.admin.create({ title, people, channel: channel === true })));
     }),
-    annotate(new Command("join"), { effects: REMOTE_WRITE })
+    annotate(new Command("join"), { output: { entity: "chat_group_change" }, effects: REMOTE_WRITE })
         .description("join a group or channel by its link; the others in it see that you joined")
         .argument("<link>", `an invite link, or a public one`)
         .action(async function (link) {
         const context = messengerContext(this, messenger);
         renderItem(this, context, await context.withServices((services) => services.admin.join(link)));
     }),
-    annotate(new Command("leave"), { effects: REMOTE_WRITE })
+    annotate(new Command("leave"), { output: { entity: "chat_removal" }, effects: REMOTE_WRITE })
         .description("leave a group or channel; the others in it see that you left")
         .argument("<chat>", messenger.chatArgument)
         .action(async function (chat) {