@wirecat/cli-core 0.390.0 → 0.392.0

package/CHANGELOG.md

@@ -5,6 +5,66 @@ 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.
 
+## 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
+
+### Changed — may break callers
+
+- Reads never mark chats read: `messages list`, `inbox` and `review` no longer take `--mark-read` or
+  `--no-mark-read`. Remove `catch_up_marks_read` from configuration; it is now refused. Use
+  `<cli> <profile> chats mark-read <chat>` when you intend to send a read receipt.
+- `tags auto` declares its messenger read, including the preparatory read requested with `--sync-first`.
+
+### 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.
+- `readMeetingLinks` (`@wirecat/cli-core/services`) and `MeetingStore.meetingChatLines`: links shared in the chat of
+  the selected meetings, most shared first, with who shared them, in which meetings, and the Google file each names.
+  Found when read, not stored; at most 100000 chat messages, more is an error.
+- A local read with an unknown profile now lists the profiles on this computer in its error and
+  `details.profiles`, so a typo does not suggest linking a new account. A configured profile with no
+  saved account still explains how to fill its local history.
+
+- Unknown permission keys now refuse messenger commands with `configuration_error`, including typos after
+  the resource name such as `messages.sedn`. Correct the key or remove it with `config unset`; a warning
+  no longer leaves the intended restriction unenforced.
+- **Message search reads `"a b"~N`: the words at most N words apart in one message, in any order.** It was a
+  `query.unsupported-operator` error; now it is syntax for `text:`, `exact:`, `transcript:`, `content:` and a bare
+  word, N up to 50 (`query.invalid-number` above). Words match in any form, as in a phrase; `exact:` keeps the typed
+  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/effects.d.ts

@@ -36,6 +36,8 @@ export declare const isLogin: (command: Command) => boolean;
  * (merge/unmerge, claim/release) or keeps the old value in the task's history; under the lock a close only suggests.
  */
 export declare const destroysNothing: <T extends Command>(command: T) => T;
+/** A local edit remains an edit even when it first fetches metadata from the messenger. */
+export declare const changesStore: <T extends Command>(command: T) => T;
 /**
  * Whether `<PREFIX>_READ_ONLY` refuses the command as a change to the store. Every write that stays on this machine
  * is refused unless `destroysNothing` marks it, so a new one fails closed (WC-PERM-12). A fetch (`remote: "read"`)

package/dist/cli/effects.js

@@ -52,6 +52,12 @@ export const destroysNothing = (command) => {
     KEPT_UNDER_LOCK.add(command);
     return command;
 };
+const STORE_WRITES = new WeakSet();
+/** A local edit remains an edit even when it first fetches metadata from the messenger. */
+export const changesStore = (command) => {
+    STORE_WRITES.add(command);
+    return command;
+};
 /**
  * Whether `<PREFIX>_READ_ONLY` refuses the command as a change to the store. Every write that stays on this machine
  * is refused unless `destroysNothing` marks it, so a new one fails closed (WC-PERM-12). A fetch (`remote: "read"`)
@@ -59,8 +65,8 @@ export const destroysNothing = (command) => {
  */
 export const isStoreChange = (command) => {
     const effects = metaOf(command).effects;
-    return (effects?.remote === "none" &&
-        effects.local === "write" &&
+    return ((effects?.remote === "none" || STORE_WRITES.has(command)) &&
+        effects?.local === "write" &&
         !KEPT_UNDER_LOCK.has(command) &&
         !changesAuthority(command));
 };

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/catch-up.d.ts

@@ -1,22 +1,3 @@
 import type { Command } from "commander";
-import type { Id, Message } from "../../domain/models.js";
-import type { MarkedRead } from "../../services/chats.js";
-import type { Services } from "../../services/index.js";
-import type { Settings } from "../settings.js";
-export declare const MARK_READ_OPTION: readonly ["--mark-read", "also mark each chat shown read, up to the newest message shown; the other side sees it"];
-export declare const NO_MARK_READ_OPTION: readonly ["--no-mark-read", "do not, whatever the catch_up_marks_read setting says"];
-/**
- * The typed flag decides; without one, the owner's `catch_up_marks_read` setting, off unless turned on (NEED-566).
- * An agent's run never marks read on that setting: the other side sees it, so only an agent that asks does.
- */
-export declare const marksRead: (typed: boolean | undefined, settings: Settings, command: Command) => boolean;
 /** Whose `--new` points a run moves: an agent's are its own, so the owner's `inbox --new` still shows everything. */
 export declare const pointsOf: <N extends "inbox" | "review">(command: Command, name: N) => N | `mcp-${N}`;
-/**
- * Marks each chat read up to the newest message shown in it — never further, so what arrived after
- * the read stays unread. Through the send guard, so `permissions.chats.mark-read` applies.
- */
-export declare const markShown: (services: Services, chats: {
-    id: Id;
-    messages: Pick<Message, "id" | "timestamp">[];
-}[], warn: (message: string) => void) => Promise<MarkedRead[]>;

package/dist/cli/messenger/catch-up.js

@@ -1,46 +1,3 @@
-import { CliError, isCliError } from "@wirecat/cli-base";
 import { environmentOf } from "../context.js";
-export const MARK_READ_OPTION = [
-    "--mark-read",
-    "also mark each chat shown read, up to the newest message shown; the other side sees it",
-];
-export const NO_MARK_READ_OPTION = ["--no-mark-read", "do not, whatever the catch_up_marks_read setting says"];
-// Neither is offered to an agent (`ownerOnlyOption`): a read tool may run unasked, and the other side sees a mark.
-// An agent marks read with `chats mark-read`, a write.
-/**
- * The typed flag decides; without one, the owner's `catch_up_marks_read` setting, off unless turned on (NEED-566).
- * An agent's run never marks read on that setting: the other side sees it, so only an agent that asks does.
- */
-export const marksRead = (typed, settings, command) => {
-    const marking = typed ?? (environmentOf(command).agent ? false : settings.catchUpMarksRead);
-    if (marking && settings.offline) {
-        throw new CliError("validation_error", "--mark-read tells the messenger; not with --offline");
-    }
-    return marking;
-};
 /** Whose `--new` points a run moves: an agent's are its own, so the owner's `inbox --new` still shows everything. */
 export const pointsOf = (command, name) => environmentOf(command).agent ? `mcp-${name}` : name;
-/**
- * Marks each chat read up to the newest message shown in it — never further, so what arrived after
- * the read stays unread. Through the send guard, so `permissions.chats.mark-read` applies.
- */
-export const markShown = async (services, chats, warn) => {
-    const marked = [];
-    for (const { id, messages } of chats) {
-        const newest = messages.reduce((last, one) => (last === undefined || Date.parse(one.timestamp) >= Date.parse(last.timestamp) ? one : last), undefined);
-        if (newest === undefined)
-            continue;
-        try {
-            const { chatId, until } = await services.chats.markRead({ chat: id, until: newest.id });
-            marked.push({ chatId, until });
-        }
-        catch (error) {
-            // A hold refuses every chat alike; what was read is still the answer, as reads go on during one.
-            if (!isCliError(error) || error.details.sendBlock === undefined)
-                throw error;
-            warn(`${error.message}; nothing more was marked read`);
-            break;
-        }
-    }
-    return marked;
-};

package/dist/cli/messenger/context.js

@@ -282,7 +282,10 @@ export const connectedFor = async (command, messenger, base, options) => {
         }),
     };
 };
-const unrecorded = (command, messenger, profile, offline) => {
+const unrecorded = (command, messenger, profile, { offline, profilesHere }) => {
+    if (!profilesHere.includes(profile)) {
+        return new CliError("not_found", `no profile named "${profile}" — profiles here: ${profilesHere.length > 0 ? profilesHere.join(", ") : "none"}`, { profiles: profilesHere });
+    }
     const words = `${messenger.app.command} ${asFirstWord(profile)}`;
     const setup = rootOf(command).commands.some((one) => one.name() === "setup") ? `\`${words}setup\`` : undefined;
     if (messenger.history === "store")
@@ -346,14 +349,14 @@ export const messengerContext = (command, messenger, resolving = {}) => {
     refuseDenied(command, base.settings);
     refuseLacking(messenger, pathOf(command));
     for (const key of unknownPermissionKeys(base.settings.permissions, knownPermissionKeys(command, messenger.permissionKey))) {
-        base.renderer.warn(`permissions.${key} names no command and does nothing — \`config unset permissions.${key}\``);
+        throw new CliError("configuration_error", `permissions.${key} names no command — remove it with \`${app.command} ${asFirstWord(profile)}config unset permissions.${key}\``, { permission: key });
     }
     // Read when warning, not now: serve swaps the renderer's methods for log records after this.
     const warn = (text, warning) => base.renderer.warn(text, warning);
     const accountFor = () => {
         const account = messenger.accountOf?.(command) ?? recalledAccount(app, provider, profile, base.env);
         if (!account)
-            throw unrecorded(command, messenger, profile, base.settings.offline);
+            throw unrecorded(command, messenger, profile, base.settings);
         return account;
     };
     const guard = messenger.guard?.(command, base.settings, warn) ??

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")