@wirecat/cli-core 0.391.0 → 0.392.0

package/CHANGELOG.md

@@ -5,7 +5,16 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
-## Unreleased
+## 0.392.0 — 23.10.2026
+
+### Added
+
+- Message commands include concrete examples in help and command discovery.
+
+### Fixed
+
+- **Agents are no longer offered channel comments for a messenger that cannot read them.** Direct calls
+  fail before connecting when the messenger declares comments unsupported.
 
 ## 0.391.0 — 23.10.2026
 
@@ -18,6 +27,18 @@ shape of this file.
 
 ### Added
 
+- **`bot watch --public-url <url> [--port <n>]` receives a bot's updates by webhook.** For a messenger that pushes and
+  cannot be polled — WhatsApp's Cloud API — the command listens on 127.0.0.1 (port 8766 by default) behind the owner's
+  tunnel, answers the subscription handshake, refuses a delivery whose signature does not match (401) or that comes
+  for another host (403), and answers 200 only after the batch is kept, so the messenger sends again what was not.
+  The same copy, redelivery check and `keepUpdates` run as for polling. A messenger opts in with the new
+  `BotWebhookIntake` port piece (`webhookHandshake`, `webhookAuthentic`, `webhookEvents`); one without it refuses.
+- **`BotMessenger.secrets` and `bot auth set --secret <name>`** keep a secret beside the bot token, the same way
+  (keyring account `bot:<profile>:<name>`, `<PREFIX>_BOT_<NAME>`, then a 0600 file) — a webhook's signing key.
+  `BotTokenStore` gains `readSecret`, `writeSecret` and `removeSecret`; `bot auth show` says where each comes from and
+  `bot auth remove` forgets them too. Without `secrets` nothing changes.
+- **`--source` knows `whatsapp` (`wa`) and `whatsapp-bot` (`wa-bot`).**
+
 - `readMeetingReview` (`@wirecat/cli-core/services`) and `MeetingStore.meetingReview`: the newest meetings of a
   selection, each with its newest summary (overview, next steps), transcript lines and words, the three who talked
   longest and its confirmed projects. No transcript text is read out.
@@ -37,6 +58,13 @@ shape of this file.
   forms. Unlike Lucene, order costs nothing: `"a b"~0` finds "b a" too. `word~1` stays an error. A saved search may
   now hold `~N`. `QUERY_OPERATORS` splits the `fuzzy / proximity` row into `proximity` and `fuzzy`.
 
+### Fixed
+
+- **An agent's text on a voice note is its transcript.** `transcript:`, the transcripts-first ranking, `matched_in`
+  and a mention's `transcript` field counted only text speech recognition wrote (`speech:<model>`), so a voice note
+  an agent transcribed was found as file text. A transcript is now the text of a voice attachment (`voice`,
+  `video_note` or `audio/ogg`), whoever wrote it.
+
 ## 0.389.0 — 22.10.2026
 
 ### Added

package/dist/cli/bot/command.js

@@ -19,11 +19,35 @@ import { botCallbacksCommand, botMenuCommand, botWebhooksCommand } from "./setup
 import { botStoreCommand } from "./store.js";
 import { BotTokenStore } from "./token.js";
 import { botWatchCommand } from "./watch.js";
+/** Where each of the messenger's other secrets comes from, `null` when it is not set; never the value. */
+const secretSources = (bot, tokens) => bot.secrets?.length
+    ? { secrets: Object.fromEntries(bot.secrets.map((one) => [one.name, tokens.readSecret(one.name)?.source ?? null])) }
+    : {};
 const authCommand = (bot, tokenVariable) => {
     const auth = annotate(new Command("auth"), { mcp: false }).description("the bot token this profile uses");
-    grantsAuthority(annotate(auth.command("set"), { effects: LOCAL_WRITE }))
-        .description(`check a bot token with ${bot.name ?? "the messenger"}, then keep it — typed at a hidden prompt or piped on stdin`)
-        .action(async function () {
+    const set = grantsAuthority(annotate(auth.command("set"), { effects: LOCAL_WRITE })).description(`check a bot token with ${bot.name ?? "the messenger"}, then keep it — typed at a hidden prompt or piped on stdin`);
+    const secrets = bot.secrets ?? [];
+    if (secrets.length > 0)
+        set.option("--secret <name>", `keep this secret instead of the token, the same way: ${secrets.map((one) => `${one.name} (${one.description})`).join("; ")}`);
+    set.action(async function () {
+        const { secret: named } = this.opts();
+        if (named !== undefined) {
+            const secret = secrets.find((one) => one.name === named);
+            if (!secret)
+                throw new CliError("validation_error", `no secret called "${named}" — one of: ${secrets.map((one) => one.name).join(", ")}`);
+            const context = botContext(this, bot);
+            await context.run(async () => {
+                const value = (await context.readSecret(`${secret.description}: `)).trim();
+                if (!value)
+                    throw new CliError("validation_error", "no secret given");
+                renderItem(this, context, {
+                    profile: context.profile,
+                    secret: secret.name,
+                    stored: context.tokens.writeSecret(secret.name, value),
+                });
+            });
+            return;
+        }
         const context = online(botContext(this, bot), this);
         await context.run(async (events) => {
             const token = (await context.readSecret("Bot token: ")).trim();
@@ -57,6 +81,7 @@ const authCommand = (bot, tokenVariable) => {
                 bot: account.name,
                 id: account.id,
                 username: account.username,
+                ...secretSources(bot, context.tokens),
             });
         });
     });
@@ -64,7 +89,11 @@ const authCommand = (bot, tokenVariable) => {
         .description("forget this profile's bot token")
         .action(async function () {
         const context = botContext(this, bot);
-        await context.run(async () => renderAnswer(this, context, itemOf({ profile: context.profile, removed: context.tokens.remove() })));
+        await context.run(async () => {
+            const removed = context.tokens.remove();
+            const secrets = Object.fromEntries((bot.secrets ?? []).map((one) => [one.name, context.tokens.removeSecret(one.name)]));
+            renderAnswer(this, context, itemOf({ profile: context.profile, removed, ...(bot.secrets?.length ? { secrets } : {}) }));
+        });
     });
     return auth;
 };

package/dist/cli/bot/port.d.ts

@@ -183,6 +183,38 @@ export interface BotUpdateRef {
 export type BotEvent = (MessageEvent | BotNotice) & {
     update?: BotUpdateRef;
 };
+/** One request as it reached `bot watch --public-url`: the body exactly as sent, never parsed and written again. */
+export interface BotWebhookRequest {
+    method: string;
+    /** Path and query, against the local listener. */
+    url: URL;
+    headers: Headers;
+    body: Uint8Array;
+}
+/** What the receiver answers a request that is not a delivery. */
+export interface BotWebhookAnswer {
+    status: number;
+    body?: string;
+}
+/**
+ * Receiving the bot's updates on a public address the owner's tunnel forwards to this machine, for a
+ * messenger that pushes and cannot be polled.
+ */
+export interface BotWebhookIntake {
+    /** A request that is not a delivery — a subscription handshake — answered here; `undefined` for a delivery. */
+    webhookHandshake(request: BotWebhookRequest): BotWebhookAnswer | undefined;
+    /** Whether a delivery comes from the messenger: its signature over the raw body, compared in constant time. */
+    webhookAuthentic(request: BotWebhookRequest): boolean;
+    /** The delivery's events, each with the update it came in, so a redelivery is recognised. Throws on a body it cannot read. */
+    webhookEvents(request: BotWebhookRequest): BotEvent[];
+}
+/** A secret beside the token that the messenger's bot needs, kept the same way — a webhook's signing key. */
+export interface BotSecret {
+    /** In `--secret <name>` and the keyring account, lowercase with hyphens. */
+    name: string;
+    /** What it is and where the owner finds it, for the help and the prompt. */
+    description: string;
+}
 export interface BotUpdatesPage {
     events: BotEvent[];
     /** Where the next call starts; the same as given when nothing came. Opaque to the caller. */
@@ -200,7 +232,7 @@ export interface BotUpdates {
  * The part of the personal core a bot can do, and the groups its Bot API has. A bot never gets
  * `chats` from this type: neither Bot API lists a bot's chats.
  */
-export type BotAdapter = Pick<MessengerCore, "me" | "close"> & Partial<MarkdownFormatting> & Partial<BotNativeApi> & Partial<BotMessaging> & Partial<BotHistory> & Partial<MessagePins> & Partial<BotChatTools> & Partial<BotChatAdmins> & Partial<BotChatMembers> & Partial<BotMenu> & Partial<BotCallbacks> & Partial<BotWebhooks> & Partial<BotUpdates> & Partial<BotPeople>;
+export type BotAdapter = Pick<MessengerCore, "me" | "close"> & Partial<MarkdownFormatting> & Partial<BotNativeApi> & Partial<BotMessaging> & Partial<BotHistory> & Partial<MessagePins> & Partial<BotChatTools> & Partial<BotChatAdmins> & Partial<BotChatMembers> & Partial<BotMenu> & Partial<BotCallbacks> & Partial<BotWebhooks> & Partial<BotUpdates> & Partial<BotWebhookIntake> & Partial<BotPeople>;
 export interface BotNativeApi {
     api(method: string, input: {
         body?: string;
@@ -237,6 +269,8 @@ export interface BotMessenger {
     adminRights?: readonly AdminRight[];
     /** Whether `bot webhooks set --add` keeps the other addresses; a messenger with one address has no `--add`. */
     manyWebhooks?: boolean;
+    /** Secrets beside the token, each set with `bot auth set --secret <name>`; none when unset. */
+    secrets?: readonly BotSecret[];
     /** Mount shared bot me; consumers with an existing response migrate explicitly. */
     identity?: boolean;
     /**

package/dist/cli/bot/token.d.ts

@@ -9,7 +9,8 @@ export interface BotTokenStoreOptions {
 }
 /**
  * A bot token per profile, beside — never inside — the personal session: keyring account
- * `bot:<profile>` under the app's own service, `<PREFIX>_BOT_TOKEN`, then a 0600 file.
+ * `bot:<profile>` under the app's own service, `<PREFIX>_BOT_TOKEN`, then a 0600 file. A secret the
+ * messenger's bot needs beside it lives the same way: `bot:<profile>:<name>`, `<PREFIX>_BOT_<NAME>`.
  */
 export declare class BotTokenStore {
     #private;
@@ -27,4 +28,10 @@ export declare class BotTokenStore {
     } | undefined;
     writeKeyring(token: string): void;
     remove(): CredentialSource[];
+    readSecret(name: string): {
+        secret: string;
+        source: CredentialSource;
+    } | undefined;
+    writeSecret(name: string, secret: string): CredentialSource;
+    removeSecret(name: string): CredentialSource[];
 }

package/dist/cli/bot/token.js

@@ -2,26 +2,30 @@ import { CliError, Credentials, pathsAreOverridden, resolvePaths, } from "@wirec
 import { envName } from "../../ports/app.js";
 /**
  * A bot token per profile, beside — never inside — the personal session: keyring account
- * `bot:<profile>` under the app's own service, `<PREFIX>_BOT_TOKEN`, then a 0600 file.
+ * `bot:<profile>` under the app's own service, `<PREFIX>_BOT_TOKEN`, then a 0600 file. A secret the
+ * messenger's bot needs beside it lives the same way: `bot:<profile>:<name>`, `<PREFIX>_BOT_<NAME>`.
  */
 export class BotTokenStore {
     profile;
     #account;
     #credentials;
     #keyringCredentials;
+    #secretOf;
     constructor({ app, profile, env = process.env, keyring, configDir }) {
         const where = { appName: app.appName, prefix: app.envPrefix, env };
         this.profile = profile;
         this.#account = `bot:${profile}`;
-        this.#credentials = new Credentials({
+        const credentialsFor = (variable) => new Credentials({
             configDir: configDir ?? resolvePaths(where).config,
             service: app.appName,
-            envVar: envName(app, "BOT_TOKEN"),
+            envVar: envName(app, variable),
             isolated: pathsAreOverridden(where),
             ...(keyring ? { keyring } : {}),
             env,
             warn: (message) => process.stderr.write(`${message}\n`),
         });
+        this.#credentials = credentialsFor("BOT_TOKEN");
+        this.#secretOf = (name) => credentialsFor(`BOT_${name.toUpperCase().replaceAll("-", "_")}`);
         this.#keyringCredentials = new Credentials({
             configDir: configDir ?? resolvePaths(where).config,
             service: app.appName,
@@ -61,4 +65,13 @@ export class BotTokenStore {
     remove() {
         return this.#credentials.remove(this.#account);
     }
+    readSecret(name) {
+        return this.#secretOf(name).read(`${this.#account}:${name}`);
+    }
+    writeSecret(name, secret) {
+        return this.#secretOf(name).write(`${this.#account}:${name}`, secret);
+    }
+    removeSecret(name) {
+        return this.#secretOf(name).remove(`${this.#account}:${name}`);
+    }
 }

package/dist/cli/bot/watch.d.ts

@@ -5,5 +5,7 @@ import type { BotMessenger } from "./port.js";
  * normal end. Each batch is kept before it is printed, and the cursor moves only after that: an end
  * at any moment never loses a batch. An update the messenger names by id is recorded and skipped when it
  * comes again after being handled; one without an id may print twice. A read: it changes nothing anyone sees.
+ * 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 declare const botWatchCommand: (bot: BotMessenger) => Command;

package/dist/cli/bot/watch.js

@@ -1,6 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import { annotate } from "@wirecat/cli-base/commands";
 import { Command } from "commander";
+import { portOf, publicUrlOf } from "../../http/public-url.js";
 import { renderMessages } from "../../render/messages.js";
 import { environmentOf } from "../context.js";
 import { REMOTE_WRITE } from "../effects.js";
@@ -9,6 +10,7 @@ import { botContext, online } from "./context.js";
 import { botCan, botIdOf } from "./messages.js";
 import { botFiles } from "./registry.js";
 import { PressLog, UpdatesCursor } from "./updates.js";
+import { receiveWebhooks, WEBHOOK_PORT } from "./webhook-receiver.js";
 /** Under Telegram's transport timeout of 30 s, so a quiet poll ends as an answer, not as a failure. */
 const WAIT_SECONDS = 25;
 const FIRST_RETRY_MS = 1_000;
@@ -78,17 +80,31 @@ const keep = async (command, context, bot, botId, events, senders) => {
  * normal end. Each batch is kept before it is printed, and the cursor moves only after that: an end
  * at any moment never loses a batch. An update the messenger names by id is recorded and skipped when it
  * comes again after being handled; one without an id may print twice. A read: it changes nothing anyone sees.
+ * 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" })
     .description("print new messages as they arrive and keep them, until Ctrl-C or --timeout (either ends it normally)")
     .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")
+    .option("--port <port>", `the local port behind the tunnel for --public-url (default ${WEBHOOK_PORT})`)
     .action(async function () {
-    const { events: everything, types: typed } = this.opts();
+    const flags = this.opts();
+    const { events: everything, types: typed } = flags;
     const context = online(botContext(this, bot), this);
     if (context.format === "json") {
         throw new CliError("validation_error", "watch is a stream — use --jsonl for one update per line");
     }
+    if (flags.port !== undefined && flags.publicUrl === undefined)
+        throw new CliError("validation_error", "--port is the local port behind --public-url; give both");
+    const publicUrl = flags.publicUrl === undefined
+        ? undefined
+        : publicUrlOf(flags.publicUrl, {
+            missing: "--public-url",
+            reaches: `${bot.name ?? "the messenger"} delivers the bot's updates`,
+        });
+    const port = portOf(flags.port, WEBHOOK_PORT);
     const types = typed
         ?.split(",")
         .map((one) => one.trim())
@@ -152,6 +168,42 @@ export const botWatchCommand = (bot) => annotate(new Command("watch"), { effects
     try {
         await context.run(async (events) => {
             const adapter = await context.authenticated({ events, stop: stop.signal });
+            const warn = context.renderer.warn;
+            /** Keeps, prints and settles one batch; `false` when it was not kept and must come again. */
+            const take = async (botId, batch) => {
+                const handled = await context.copy.received(botId, batch, warn);
+                const fresh = batch.filter((event) => !(event.update && handled.has(event.update.id)));
+                if (fresh.length > 0 && !(await keep(this, context, bot, botId, fresh, adapter.senders?.()))) {
+                    await context.copy.settle(botId, fresh, "not_kept", warn);
+                    return false;
+                }
+                for (const event of fresh)
+                    print(event);
+                await context.copy.settle(botId, fresh, null, warn);
+                const seen = [...new Set(batch.flatMap((event) => chatOf(event) ?? []))].filter((id) => CHAT_ID.test(id));
+                if (seen.length > 0)
+                    context.registry.observe(seen.map((id) => ({ id })));
+                return true;
+            };
+            if (publicUrl) {
+                const intake = {
+                    webhookHandshake: botCan(adapter, "webhookHandshake", bot, "receive its updates by webhook"),
+                    webhookAuthentic: botCan(adapter, "webhookAuthentic", bot, "receive its updates by webhook"),
+                    webhookEvents: botCan(adapter, "webhookEvents", bot, "receive its updates by webhook"),
+                };
+                const botId = await botIdOf(context, adapter);
+                const wanted = (event) => !types || (event.update !== undefined && types.includes(event.update.kind));
+                await receiveWebhooks({
+                    intake,
+                    publicUrl,
+                    port,
+                    take: (batch) => take(botId, batch.filter(wanted)),
+                    signal: stop.signal,
+                    warn,
+                    listening: (local) => context.renderer.note(`receiving at ${publicUrl.origin} through ${local.host} — the tunnel must forward there; Ctrl-C to stop`),
+                });
+                return;
+            }
             const poll = botCan(adapter, "updates", bot, "take updates");
             if (adapter.webhooks && (await adapter.webhooks()).length > 0) {
                 throw new CliError("validation_error", `this bot gets its updates by webhook, and ${bot.name ?? "the messenger"} gives polling nothing while one ` +
@@ -182,21 +234,11 @@ export const botWatchCommand = (bot) => annotate(new Command("watch"), { effects
                     await retry(`${bot.name ?? "the messenger"} did not answer (${code ?? "unknown"})`);
                     continue;
                 }
-                const warn = context.renderer.warn;
-                const handled = await context.copy.received(botId, page.events, warn);
-                const fresh = page.events.filter((event) => !(event.update && handled.has(event.update.id)));
-                if (fresh.length > 0 && !(await keep(this, context, bot, botId, fresh, adapter.senders?.()))) {
-                    await context.copy.settle(botId, fresh, "not_kept", warn);
+                if (!(await take(botId, page.events))) {
                     await retry("the updates were not kept");
                     continue;
                 }
                 failures = 0;
-                for (const event of fresh)
-                    print(event);
-                await context.copy.settle(botId, fresh, null, warn);
-                const seen = [...new Set(page.events.flatMap((event) => chatOf(event) ?? []))].filter((id) => CHAT_ID.test(id));
-                if (seen.length > 0)
-                    context.registry.observe(seen.map((id) => ({ id })));
                 if (page.cursor !== undefined && page.cursor !== at) {
                     at = page.cursor;
                     cursor.write(at);

package/dist/cli/bot/webhook-receiver.d.ts

@@ -0,0 +1,22 @@
+import type { BotEvent, BotWebhookIntake } from "./port.js";
+/** The local port behind the tunnel; MCP's `--http` has 8765. */
+export declare const WEBHOOK_PORT = 8766;
+/** Meta sends at most 3 MB in one delivery; anything larger is refused unread. */
+export declare const WEBHOOK_BODY: number;
+export interface WebhookReceiver {
+    intake: BotWebhookIntake;
+    publicUrl: URL;
+    port: number;
+    /** Keeps a batch: `true` once it is safe to tell the messenger it arrived. */
+    take: (events: BotEvent[]) => Promise<boolean>;
+    signal: AbortSignal;
+    /** Where the receiver listens, said once it does. */
+    listening: (local: URL) => void;
+    warn: (message: string) => void;
+}
+/**
+ * Answers the messenger on 127.0.0.1 until `signal` ends it. A delivery is answered 200 only after
+ * `take` kept it: a messenger that pushes retries anything else, so a crash or a full disk loses
+ * nothing. Batches are kept one at a time, in the order they arrived.
+ */
+export declare const receiveWebhooks: (receiver: WebhookReceiver) => Promise<void>;

package/dist/cli/bot/webhook-receiver.js

@@ -0,0 +1,68 @@
+import { listen } from "../../http/listen.js";
+/** The local port behind the tunnel; MCP's `--http` has 8765. */
+export const WEBHOOK_PORT = 8766;
+/** Meta sends at most 3 MB in one delivery; anything larger is refused unread. */
+export const WEBHOOK_BODY = 3 * 1024 * 1024;
+const LOCAL = ["localhost", "127.0.0.1"];
+const answer = (status, body = "") => new Response(body, { status, headers: { "content-type": "text/plain; charset=utf-8" } });
+/**
+ * Answers the messenger on 127.0.0.1 until `signal` ends it. A delivery is answered 200 only after
+ * `take` kept it: a messenger that pushes retries anything else, so a crash or a full disk loses
+ * nothing. Batches are kept one at a time, in the order they arrived.
+ */
+export const receiveWebhooks = async (receiver) => {
+    const { intake, publicUrl, take, warn } = receiver;
+    const hosts = [publicUrl.host, ...LOCAL.map((host) => `${host}:${receiver.port}`), ...LOCAL];
+    let queue = Promise.resolve();
+    const inTurn = (events) => {
+        const turn = queue.then(() => take(events));
+        queue = turn.catch(() => undefined);
+        return turn;
+    };
+    const handle = async (incoming) => {
+        // A page in the owner's browser can reach 127.0.0.1 too; only the tunnel and the machine itself may.
+        if (!hosts.includes(incoming.headers.get("host") ?? ""))
+            return answer(403, "host not allowed");
+        const url = new URL(incoming.url);
+        if (url.pathname !== "/")
+            return answer(404, "not found");
+        const request = {
+            method: incoming.method,
+            url,
+            headers: incoming.headers,
+            body: new Uint8Array(await incoming.arrayBuffer()),
+        };
+        if (request.method === "GET") {
+            const reply = intake.webhookHandshake(request);
+            return reply ? answer(reply.status, reply.body) : answer(404, "not found");
+        }
+        if (request.method !== "POST")
+            return answer(405, "method not allowed");
+        if (!intake.webhookAuthentic(request))
+            return answer(401, "signature does not match");
+        let events;
+        try {
+            events = intake.webhookEvents(request);
+        }
+        catch {
+            return answer(400, "unreadable delivery");
+        }
+        try {
+            return (await inTurn(events)) ? answer(200) : answer(503, "not kept");
+        }
+        catch (error) {
+            warn(`a delivery was not kept: ${error instanceof Error ? error.message : String(error)}`);
+            return answer(503, "not kept");
+        }
+    };
+    const listening = await listen(handle, { host: "127.0.0.1", port: receiver.port, maxBody: WEBHOOK_BODY });
+    try {
+        receiver.listening(listening.url);
+        if (!receiver.signal.aborted)
+            await new Promise((resolve) => receiver.signal.addEventListener("abort", () => resolve(), { once: true }));
+        await queue;
+    }
+    finally {
+        await listening.close();
+    }
+};

package/dist/cli/index.d.ts

@@ -42,7 +42,7 @@ export { type BotContext, botContext, botWords } from "./bot/context.js";
 export { type BotCopy, botCopy } from "./bot/copy.js";
 export { botMcpCommand } from "./bot/mcp.js";
 export { botCan, botIdOf, botMessagesCommand } from "./bot/messages.js";
-export { BOT_ACTIONS, type BotAction, type BotAdapter, type BotCallbacks, type BotChatAdmin, type BotChatAdmins, type BotChatMembers, type BotChatRef, type BotChatTools, type BotConnectOptions, type BotEvent, type BotHistory, type BotMcp, type BotMenu, type BotMenuEntry, type BotMessaging, type BotMessenger, type BotNativeApi, type BotNotice, type BotPeople, type BotPress, type BotSendOptions, type BotUpdates, type BotUpdatesPage, type BotWebhook, type BotWebhooks, } from "./bot/port.js";
+export { BOT_ACTIONS, type BotAction, type BotAdapter, type BotCallbacks, type BotChatAdmin, type BotChatAdmins, type BotChatMembers, type BotChatRef, type BotChatTools, type BotConnectOptions, type BotEvent, type BotHistory, type BotMcp, type BotMenu, type BotMenuEntry, type BotMessaging, type BotMessenger, type BotNativeApi, type BotNotice, type BotPeople, type BotPress, type BotSecret, type BotSendOptions, type BotUpdates, type BotUpdatesPage, type BotWebhook, type BotWebhookAnswer, type BotWebhookIntake, type BotWebhookRequest, type BotWebhooks, } from "./bot/port.js";
 export { botFiles, botsDirectory, ChatRegistry, registryProfiles, type SeenChat } from "./bot/registry.js";
 export { BotTokenStore, type BotTokenStoreOptions } from "./bot/token.js";
 export { PressLog, UpdatesCursor } from "./bot/updates.js";

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

@@ -34,7 +34,11 @@ const ALL_SINCE = "90d";
 const ALL_CHATS = "--all";
 export const syncCommand = (messenger) => {
     const fetching = messenger.fetching ?? FETCHING;
-    return annotate(new Command("sync"), { effects: FETCH, cooperative: true })
+    return annotate(new Command("sync"), {
+        examples: [`${messenger.app.command} personal messages sync "Book club" --last 100`],
+        effects: FETCH,
+        cooperative: true,
+    })
         .description("bring a chat's history in the local store up to date, newest first; run it again to continue; --all syncs every chat")
         .argument("[chat]", messenger.chatArgument)
         .option("--all", `every chat, most recently active first — what search needs; the last ${ALL_SINCE} unless --since-time or --last`)

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

@@ -473,7 +473,10 @@ const answerOf = (text) => {
     return answer;
 };
 /** `messages links`: why a message sits where it does in its conversation. */
-export const linksCommand = (messenger) => annotate(new Command("links"), { effects: LOCAL_READ })
+export const linksCommand = (messenger) => annotate(new Command("links"), {
+    examples: [`${messenger.app.command} personal messages links "Book club" 101`],
+    effects: LOCAL_READ,
+})
     .description("why a message is in its conversation: each link it has, and the chain of answers back to the start")
     .argument("<chat>", messenger.chatArgument)
     .argument("<message>", "the message id")

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

@@ -17,7 +17,10 @@ import { nextStep } from "../steps.js";
 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"), { effects: FETCH })
+export const downloadSubcommand = (messages, messenger) => annotate(messages.command("download"), {
+    examples: [`${messenger.app.command} personal messages download "Book club" 101 --output-dir ./downloads`],
+    effects: FETCH,
+})
     .description("save a message's photos, files, videos and voice notes to a folder — or a whole chat's with --all")
     .argument("<chat>", messenger.chatArgument)
     .argument("[message]", "the message id; left out with --all")

package/dist/cli/messenger/lacks.d.ts

@@ -7,6 +7,7 @@ type Need = readonly [method: keyof MessengerAdapter, what: string];
  */
 export declare const COMMAND_NEEDS: Readonly<Record<string, Need>>;
 interface Lacking {
+    channelComments?: boolean;
     lacks?: readonly (keyof MessengerAdapter)[];
     history?: "server" | "store";
 }

package/dist/cli/messenger/lacks.js

@@ -19,6 +19,7 @@ export const COMMAND_NEEDS = {
     "contacts remove": ["removeContact", "remove a contact"],
     "contacts rename": ["renameContact", "rename a contact"],
     "contacts import": ["importContacts", "import contacts"],
+    "messages comments": ["comments", "read comments on a channel post"],
     "messages pin": ["pin", "pin a message"],
     "messages unpin": ["unpin", "unpin a message"],
 };
@@ -27,7 +28,11 @@ const STORE_ANSWERS = new Set(["chats events"]);
 /** The one method this command needs and this messenger never has; none when it has it or the store answers. */
 export const lackedNeed = (messenger, path) => {
     const need = COMMAND_NEEDS[path];
-    if (!need || !messenger?.lacks?.includes(need[0]))
+    if (!need)
+        return undefined;
+    if (path === "messages comments" && messenger?.channelComments === false)
+        return need;
+    if (!messenger?.lacks?.includes(need[0]))
         return undefined;
     return messenger.history === "store" && STORE_ANSWERS.has(path) ? undefined : need;
 };

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

@@ -6,6 +6,7 @@ import { annotate } from "@wirecat/cli-base/commands";
 import { installerOf } from "@wirecat/cli-base/update";
 import { Command } from "commander";
 import { ATTACHMENT_LIMIT_ENV } from "../../attachments/limits.js";
+import { portOf, publicUrlOf } from "../../http/public-url.js";
 import { envName } from "../../ports/app.js";
 import { environmentOf } from "../context.js";
 import { grantsAuthority, LOCAL_READ, LOCAL_WRITE, REMOTE_WRITE } from "../effects.js";
@@ -17,32 +18,6 @@ import { messengerContext } from "./context.js";
 const DEFAULT_PORT = 8765;
 /** Where `mcp --http` keeps the hashes of the tokens it issued — per profile, in the state folder. */
 export const httpTokenFile = (app, profile, env) => join(resolvePaths({ appName: app.appName, prefix: app.envPrefix, env }).state, "mcp-http", `${profile}.json`);
-const publicUrlOf = (app, given) => {
-    const example = `--public-url https://<name>.ts.net`;
-    if (!given)
-        throw new CliError("configuration_error", `--http needs the tunnel's address: ${example}`);
-    let url;
-    try {
-        url = new URL(given);
-    }
-    catch {
-        throw new CliError("validation_error", `--public-url is not an address: ${example}`);
-    }
-    const local = url.protocol === "http:" && ["localhost", "127.0.0.1"].includes(url.hostname);
-    if (url.protocol !== "https:" && !local)
-        throw new CliError("validation_error", `--public-url must be https — the browser apps reach ${app.command} through it`);
-    if (url.pathname !== "/" || url.search || url.hash)
-        throw new CliError("validation_error", `--public-url is the tunnel's address only, without a path: ${example}`);
-    return url;
-};
-const portOf = (given) => {
-    if (given === undefined)
-        return DEFAULT_PORT;
-    const port = Number(given);
-    if (!Number.isInteger(port) || port < 1 || port > 65535)
-        throw new CliError("validation_error", "--port takes 1–65535");
-    return port;
-};
 const withFlags = (command) => command.option("--permission <key=level>", "make a permission stricter for this server only, like messages.send=deny; it never loosens the profile; repeat for more keys", (value, previous = []) => [...previous, value]);
 export const mcpCommand = (messenger) => {
     const { app } = messenger;
@@ -61,11 +36,14 @@ export const mcpCommand = (messenger) => {
             return;
         }
         if (flags.http) {
-            const publicUrl = publicUrlOf(app, flags.publicUrl);
+            const publicUrl = publicUrlOf(flags.publicUrl, {
+                missing: "--http",
+                reaches: `the browser apps reach ${app.command}`,
+            });
             const { serveOverHttpUntilStopped } = await import("../../mcp/server.js");
             await serveOverHttpUntilStopped(this, context, messenger, {}, {
                 publicUrl,
-                port: portOf(flags.port),
+                port: portOf(flags.port, DEFAULT_PORT),
                 tokenFile: httpTokenFile(app, context.settings.profile, context.env),
             });
             return;

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

@@ -36,7 +36,10 @@ export const messagesCommand = (messenger) => {
     const messages = new Command("messages").description("read and send messages");
     messages.addCommand(evidenceCommand(messenger));
     const history = historyQuery(messenger);
-    const list = annotate(messages.command("list"), { effects: REMOTE_READ })
+    const list = annotate(messages.command("list"), {
+        examples: [`${messenger.app.command} personal messages list "Book club" --limit 20`],
+        effects: REMOTE_READ,
+    })
         .description("a chat's messages, oldest to newest")
         .addHelpText("after", SAVE_HELP)
         .addHelpText("after", queryHelp(history))
@@ -105,7 +108,10 @@ export const messagesCommand = (messenger) => {
         }), view);
     };
     messages.addCommand(sendCommand(messenger));
-    annotate(messages.command("show"), { effects: REMOTE_READ })
+    annotate(messages.command("show"), {
+        examples: [`${messenger.app.command} personal messages show "Book club" 101`],
+        effects: REMOTE_READ,
+    })
         .description("one message, by its chat and id or by its msg: locator")
         .argument("<chat>", `${messenger.chatArgument}; or a msg: locator, with no message id after it`)
         .argument("[message]", "the message id")
@@ -114,7 +120,10 @@ export const messagesCommand = (messenger) => {
             return await readMailWindow(this, chat, { before: 0, after: 0 });
         await readWindow(this, chat, message, { before: 0, after: 0 });
     });
-    threadOptions(annotate(messages.command("context"), { effects: REMOTE_READ }))
+    threadOptions(annotate(messages.command("context"), {
+        examples: [`${messenger.app.command} personal messages context "Book club" 101 --before-n 3 --after-n 3`],
+        effects: REMOTE_READ,
+    }))
         .description("a message and what came either side of it, oldest first")
         .addHelpText("after", SAVE_HELP)
         .argument("<chat>", `${messenger.chatArgument}; or a msg: locator, with no message id after it`)

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

@@ -10,7 +10,10 @@ import { messengerContext } from "./context.js";
 import { COMMENTS_QUERY, cursorOf, historyWindow } from "./history-query.js";
 import { messageItems, viewOf } from "./message-items.js";
 export const commentsCommand = (messenger) => {
-    const command = annotate(new Command("comments"), { effects: REMOTE_READ })
+    const command = annotate(new Command("comments"), {
+        examples: [`${messenger.app.command} personal messages comments "News channel" 101 --limit 20`],
+        effects: REMOTE_READ,
+    })
         .description("the comments under a channel post, oldest to newest; they live in its discussion group")
         .addHelpText("after", queryHelp(COMMENTS_QUERY))
         .argument("<chat>", `the channel: ${messenger.chatArgument}`)