@ykurilov/agent-chat-messengers 0.0.0-stage → 0.55.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yury Kurilov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,382 @@
-# Temporary Holding Version
+# @ykurilov/agent-chat-messengers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Чат приложения в Telegram, VK и MAX: человек пишет боту, отвечает тот же агент, что и в вебе. Пакет сам принимает
+обновления (вебхук или опрос), привязывает аккаунты, шлёт ответы с учётом ограничений мессенджера и карточки задач.
+
+```ts
+import { createMessengers } from "@ykurilov/agent-chat-messengers";
+import { createSqliteMessengerStore } from "@ykurilov/agent-chat-messengers/sqlite";
+import { telegramBot } from "@ykurilov/agent-chat-messengers/telegram";
+
+const store = await createSqliteMessengerStore({ filePath: "./data/messengers.db" });
+const messengers = createMessengers({
+  store,
+  bots: [telegramBot({ token, username: "my_school_bot", receive: { polling: true } })],
+  service, // служба чата из createChatServer
+  resolveUser: async (request) => currentUser(request), // кто сейчас в приложении (для привязки)
+  basePath: "/api/messengers",
+  attachments: ingestMessengerFile, // необязательно, см. ниже
+  transcribe: transcribeVoice, // необязательно, см. ниже
+});
+app.all("/api/messengers/*", (c) => messengers.handler.fetch(c.req.raw));
+await messengers.start(); // меню команд, недоставленное, опрос
+// при остановке сервера: await messengers.stop(); await store.close();
+```
+
+## Боты
+
+Один бот на мессенджер. Токены — из окружения сервера, в код и журналы они не попадают.
+
+```ts
+import { telegramBot } from "@ykurilov/agent-chat-messengers/telegram";
+import { vkBot } from "@ykurilov/agent-chat-messengers/vk";
+import { maxBot } from "@ykurilov/agent-chat-messengers/max";
+
+telegramBot({ token, username: "my_school_bot", receive: { webhook: { secret } } }); // или { polling: true }
+vkBot({ token, groupId: 123456, groupScreenName: "my_school", receive: { callback: { secret, confirmation } } }); // или { longPoll: true }
+maxBot({ token, botName: "my_school_bot", receive: { webhook: { secret } } }); // или { polling: true }
+```
+
+| Мессенджер | Вебхук | Опрос |
+|---|---|---|
+| Telegram | `receive: { webhook: { secret } }` | `receive: { polling: true }` |
+| VK | `receive: { callback: { secret, confirmation } }` — секретный ключ (обязателен) и строка подтверждения из настроек сервера в сообществе | `receive: { longPoll: true }` |
+| MAX | `receive: { webhook: { secret } }`, секрет 5–256 знаков из `A–Z a–z 0–9 _ -` | `receive: { polling: true }` |
+
+- **Вебхук** нужен публичный HTTPS-адрес приложения. Telegram и MAX надо сказать, куда присылать:
+  `await bot.registerWebhook("https://my.app/api/messengers/telegram/webhook")` при запуске (у VK адрес
+  вписывается в настройках сообщества).
+- **Опрос** адреса не требует: подходит для локальной разработки и серверов без внешнего адреса. Одним опросом
+  одного бота занимается только одна копия сервера.
+- **Из России** `api.telegram.org` может не открываться. Telegram-боту тогда дают `api` с адресом обратного прокси:
+  `api: { baseUrl: "https://tg-proxy.example", headers: { "x-key": "…" } }` или свою функцию `api: { fetch }`.
+  Тот же `api` есть у `vkBot` и `maxBot`. Адреса по умолчанию: `https://api.telegram.org`, `https://api.vk.com`,
+  `https://platform-api.max.ru`. Значения заголовков из журналов прячутся.
+- **Группы Telegram.** Бот в группе по умолчанию видит только команды и ответы на свои сообщения («режим
+  приватности»). Чтобы он читал упоминания, надо отключить этот режим в BotFather (`/setprivacy` → Disable) и
+  заново добавить бота в группу.
+
+## Настройки `createMessengers`
+
+| Настройка | Что | По умолчанию |
+|---|---|---|
+| `store`, `bots`, `basePath`, `resolveUser` | Обязательные | — |
+| `service` | Служба чата из `createChatServer`. Нет — бот только привязывает аккаунты, см. «Рецепт: бот только для привязки и уведомлений» | бот без чата |
+| `conversations` | `"single"` — одна переписка, без `/new` и `/chats`; `"many"` — несколько чатов | `"single"` |
+| `resolveAccount` | Кто может писать: `{ userId }` или `{ refuse: "текст" }` | только привязанные аккаунты |
+| `chatForConversation` | Какой чат открыть для разговора (`first`, `new`, `chat_gone`, `start_payload`); можно дать агенту `agentStarts` — он напишет первым | новый пустой чат |
+| `groups` | Включает группы; нет поля — боты в группах молчат | выключены |
+| `groups.answerTo` | `"mentions"` — упоминание и ответ на сообщение бота; `"all"` — на всё | `"mentions"` |
+| `groups.allowedTools` | Какие инструменты приложения доступны в группе | ни одного |
+| `groups.payer` | Чей лимит тратится; `null` — не отвечать | тот, кто подключил |
+| `groups.perMemberHourly` | Обращений одного участника в час | 20 |
+| `voiceReplies` | Голосовые ответы, см. ниже | текст |
+| `onLinked(link)` | Человек привязал аккаунт: приложение узнаёт об этом (например, чтобы выдать награду), см. «Привязка аккаунта» | нет сигнала |
+| `onUnlinked(link)` | Привязка снята: приложение узнаёт об этом (например, чтобы убрать человека из рассылки), см. «Привязка аккаунта» | нет сигнала |
+| `allowedOrigins` | Чужие страницы, которым можно выдавать и снимать привязку (`POST`, `DELETE` на `/links`) с куками человека, например `["https://school.getcourse.ru"]`. С других чужих страниц — 403 `forbidden_origin` | только свой сайт |
+| `commandsMenu` | `false` — не ставить ботам меню команд и снять поставленное раньше. У бота есть своя `commandsMenu`, она главнее | `true` |
+| `taskReadyPing` | `true`: «Задача готова» приходит в мессенджер, когда вкладка закрыта | выключено |
+| `attachments`, `transcribe` | Файлы и голос, см. «Два мостика» | «не принимаю» |
+| `webChatUrl(chatId)` | Кнопка «Открыть в приложении» | без кнопки |
+| `texts` | Свои фразы бота для всех ботов; у бота есть свои `texts`, они главнее. См. «Свои фразы бота» | `defaultMessengerTexts` |
+| `onAnswerDelivery(report)` | Исход доставки каждого ответа агента: `delivered`, `blocked`, `window_closed`, `retry`, `failed`. Сценарию — `(report) => flow.reportDelivery(report)`. См. «Доставка ответов» | нет сигнала |
+
+Команды: `/start <код>` и `/link <код>` — привязка, `/stop` — остановить ответ, при `conversations: "many"` ещё
+`/new` и `/chats`. В группе `/stop` принимается от автора текущего хода, плательщика и того, кто подключил бота.
+Код привязки гасится только в своём мессенджере: код Telegram, введённый в VK, не сгорает.
+
+Права и закрытый чат приложения работают и здесь. Голосовое при `voice: false` и файлы при `attachments: false` не
+скачиваются и не распознаются: человек получает «недоступно, напишите текстом». `/chats` и выбор чата смотрят на `chatList`
+текущего чата, закрытый чат в списке помечен «закрыт». Отказ `beforeCreateChat` на `/new`, `/start` с меткой и первый чат
+приходит человеку текстом. Своя служба вместо ядра может реализовать необязательный `assertCapability`.
+
+## Привязка аккаунта
+
+Человек в приложении нажимает «Подключить» — получает ссылку на бота с кодом (живёт 15 минут, подходит один раз),
+открывает её в мессенджере, нажимает «Начать» — аккаунт привязан. Адреса внутри `basePath`: `GET /links` — список,
+`POST /links` — новый код, `DELETE /links/<мессенджер>` — отвязать. Готовая панель — `MessengerConnect` из
+`@ykurilov/agent-chat-messengers/react`; свой вид — через `MessengersSkin` (см. `docs/messengers.md`).
+
+Узнать, что человек привязал аккаунт, можно через `onLinked`. Её вызывают после того, как привязка сохранена, и ждут
+до ответа «Готово: аккаунт подключён». Неверный, просроченный и уже использованный код сигнала не дают. Ошибка внутри
+`onLinked` уходит в `logError` и привязку не отменяет.
+
+```ts
+createMessengers({
+  // …
+  onLinked: async (link) => {
+    // link: { messenger, botId, externalUserId, userId, name, username?, linkedAt }
+    await grantLimitReset(link.userId, `${link.messenger}:${link.externalUserId}`);
+  },
+});
+```
+
+Сигнал может прийти не один раз для одного аккаунта мессенджера: человек отвязал и привязал снова. Награду за
+привязку выдавайте идемпотентно, например по паре `messenger` + `externalUserId`.
+
+Аккаунт мессенджера, уже привязанный к одному пользователю, код другого пользователя не переносит: человек получает
+фразу `linkTaken`, привязка остаётся прежней, сигналов нет. Чтобы перенести аккаунт, его сначала отключают в
+приложении у прежнего пользователя.
+
+Узнать, что привязку сняли, можно через `onUnlinked`. Её вызывают, когда привязки в базе уже нет. Привязка снимается
+одним путём: человек отвязал аккаунт в приложении (`DELETE /links/<мессенджер>`, кнопка «Отключить» в
+`MessengerConnect`) — сигнал на каждый его аккаунт этого мессенджера. Ответ 204 ждёт, пока обработчик закончит: долгий
+`onUnlinked` задерживает кнопку «Отключить», поэтому тяжёлую работу лучше ставить в очередь.
+
+Других путей нет: блокировка бота человеком привязку не снимает, а `/disconnect` в группе отключает бота от группы,
+а не аккаунт. Ошибка внутри `onUnlinked` уходит в `logError` и отвязку не отменяет.
+
+Сигнал может повториться: два одновременных запроса отвязки дадут его дважды. Поэтому обработчик должен быть
+идемпотентным: «убрать, если есть». Бывает и наоборот: сервер упал сразу после удаления — сигнала не будет. Перед
+рассылкой надёжнее сверяться с `store.listLinks(userId)`.
+
+```ts
+createMessengers({
+  // …
+  onUnlinked: async (link) => {
+    // Убрать человека из рассылки этого мессенджера. Повторный вызов ничего не ломает.
+    await newsletter.unsubscribe(link.userId, `${link.messenger}:${link.externalUserId}`);
+  },
+});
+```
+
+## Свои фразы бота
+
+Все фразы бота лежат в `defaultMessengerTexts` (тип `MessengerTexts`). Любую можно заменить в `texts` у
+`createMessengers` (для всех ботов) или у самого бота: `telegramBot({ …, texts })`, `vkBot`, `maxBot`. Фраза бота
+главнее общей, общая главнее фразы по умолчанию. Незаданные фразы остаются по умолчанию.
+
+- **Пустая строка — молчание.** `""` или фраза-функция, вернувшая `""`, значит «ничего не отправлять». Ответ агента
+  фразой не считается и уходит как обычно.
+- **Нажатие своей кнопки подтверждается всегда.** Иначе у человека вечно крутится значок загрузки. При пустой фразе
+  (`accepted`, `taskCanceled` и т. п.) бот подтверждает нажатие без текста. Совсем не отвечает он только на чужую или
+  неизвестную кнопку, на кнопку от того, кому писать нельзя, и на кнопку в группе не от плательщика.
+- **Пустой итог убирает «Работаю…».** Если ответ состоял только из строки статуса, а `done`, `stopped` или
+  `answerFailed` пустые, бот удаляет сообщение статуса. Telegram, VK и MAX это умеют. Свой адаптер без
+  `deleteMessage` оставит строку статуса в чате как есть.
+- **Сообщения с кнопками не глушатся.** Список `/chats` (`chatsTitle`), вопрос о разрешении (`approvalQuestion`) и
+  вопрос задачи (`taskApprovalQuestion`) без текста не отправить. Пустая фраза здесь — фраза по умолчанию.
+- **Фразы-функции** получают данные: `chatSelected(title)`, `limitReached({ resetsAt, timeZone, unit })`,
+  `fileTooBig(limitMb)`, `fileRefused(reason)` и другие — см. `defaultMessengerTexts`.
+- **Команды подчиняются тем же правилам, что сообщение.** `/start`, `/help`, `/new`, `/chats`, `/stop` и кнопки от
+  того, кому писать нельзя, получают отказ `resolveAccount` (а без него — фразу `howToConnect`). Пустой отказ — тишина.
+
+Что непривязанный человек может получить и чем это выключить:
+
+| Когда | Фраза |
+|---|---|
+| Любое сообщение, команда, голос, файл, кнопка в личке | отказ `resolveAccount`, без него — `howToConnect` |
+| Неверный или просроченный код в `/start <код>`, `/link <код>` | `linkFailed` |
+| Код другого пользователя, а аккаунт уже привязан | `linkTaken` |
+| Удачная привязка | `linked` |
+| Группа, группы выключены (один раз на группу) | `writeInPrivate` |
+| Группа, группы включены | `connectHint`, `helpGroup`, `groupNeedsLink`, `groupOnlyConnector`, `groupRefused`, `memberLimit`, `onlyPayer`, `stopNotYours` |
+
+### Рецепт: бот только для привязки и уведомлений
+
+Приложению мессенджер нужен только для привязки аккаунта и своих уведомлений, без разговора с агентом. Тогда
+`service` не передают — это «бот без чата»:
+
+- привязка (`/start <код>`, `/link <код>`), отвязка, `onLinked` и `onUnlinked` работают как обычно;
+- привязанный человек на любое сообщение, команду, голосовое, файл и кнопку получает фразу `notifyOnly` (пустая —
+  тишина). Ход агента не начинается, файлы и голосовые не скачиваются. Нажатие кнопки бот подтверждает без текста;
+- непривязанный получает `howToConnect`, в группе — один раз `writeInPrivate`. Если задан `resolveAccount`, его отказ
+  главнее: это та же проверка «кто пишет», что и с чатом;
+- фразы по умолчанию не обещают разговор: `linked` — «Готово: аккаунт подключён.», `howToConnect` зовёт подключить
+  аккаунт ради уведомлений (обе в `defaultMessengerTextsWithoutChat`). Порядок тот же: фраза бота → общая `texts` →
+  умолчание бота без чата → обычное умолчание;
+- меню команд снимается: команд, которые бот выполняет, нет. В Telegram снимаются меню личных и групповых чатов;
+  общее меню, заданное в BotFather (и меню для отдельных языков), нужно очистить там. MAX снимает меню пустым
+  списком `commands` — так сказано в его документации (dev.max.ru); живым ботом это не проверено;
+- настройки разговора (`groups`, `conversations`, `chatForConversation`, `attachments`, `transcribe`, `voiceReplies`,
+  `taskReadyPing`, `webChatUrl`) без `service` задать нельзя — `typecheck` не пропустит.
+
+Уведомления приложение шлёт само; кому — видно по `store.listLinks(userId)`.
+
+**ВК-бот, который молчит.** Сообщество ВК обслуживает другой сервер, поэтому бот не пишет ничего, кроме фразы после
+удачной привязки.
+
+```ts
+const vk = vkBot({
+  token: process.env.VK_TOKEN!,
+  groupId: 123456,
+  groupScreenName: "my_app",
+  receive: { callback: { secret, confirmation } },
+  texts: { linked: "Аккаунт привязан. Уведомления придут сюда.", linkFailed: "", howToConnect: "", notifyOnly: "", writeInPrivate: "" },
+});
+```
+
+**Telegram-бот с одной фразой.** На всё, кроме привязки, бот отвечает одной фразой — и привязанным, и непривязанным,
+и в группе.
+
+```ts
+const NOTIFY_ONLY = "Это бот уведомлений AppStudio. Писать сюда не нужно — откройте приложение.";
+
+const telegram = telegramBot({
+  token: process.env.TELEGRAM_TOKEN!,
+  username: "appstudio_bot",
+  receive: { webhook: { secret } },
+  texts: { linked: "Готово: уведомления AppStudio будут приходить сюда.", howToConnect: NOTIFY_ONLY, notifyOnly: NOTIFY_ONLY, writeInPrivate: NOTIFY_ONLY },
+});
+
+const store = await createPostgresMessengerStore({ connectionString: process.env.DATABASE_URL! });
+const messengers = createMessengers({
+  store,
+  bots: [vk, telegram],
+  basePath: "/api/messengers",
+  resolveUser,
+  // service нет: разговора с агентом нет, меню команд снимается.
+  onLinked: (link) => notifications.subscribe(link.userId, `${link.messenger}:${link.externalUserId}`),
+  onUnlinked: (link) => notifications.unsubscribe(link.userId, `${link.messenger}:${link.externalUserId}`),
+});
+await messengers.start();
+
+// Остановка сервера: сначала мессенджеры, потом хранилище (оно закрывает свой пул соединений).
+process.once("SIGTERM", async () => {
+  await messengers.stop();
+  await store.close();
+});
+```
+
+Почему у Telegram одна фраза стоит в трёх местах. `howToConnect` — ответ непривязанному, `notifyOnly` — привязанному,
+`writeInPrivate` — один раз в группе. `resolveAccount` здесь не нужен: без `service` бот и так никого не пускает к
+агенту. Если он задан и отказывает, звучит его отказ.
+
+Бот с чатом, которому не нужно меню, — `commandsMenu: false` в `createMessengers` или у бота (`telegramBot`,
+`maxBot`). У VK меню команд нет, ставить и снимать там нечего.
+
+## Голосовые ответы
+
+Бот может отвечать голосовым сообщением. Озвучку делает `createVoiceReplies` из
+`@ykurilov/agent-chat-voice-dialog/server` (ElevenLabs; цена и настройки — в README того пакета):
+
+```ts
+import { createVoiceReplies } from "@ykurilov/agent-chat-voice-dialog/server";
+
+voiceReplies: createVoiceReplies({
+  apiKey: process.env.ELEVENLABS_API_KEY!,
+  voiceId: "JBFqnCBsd6RMkjVDRZzb",
+  model: "eleven_v4_turbo",
+  language: "ru",
+  logError: console.error,
+  storage, // тот же, что у чата: туда пишется расход
+  pricePerThousandChars: { eleven_v4_turbo: 0.11 },
+}),
+```
+
+Лимит расходов исчерпан или сервис недоступен — человек получает обычный текст. Код, таблицы и схемы вслух не
+читаются («код на экране»). Длинный ответ озвучивается до 1500 знаков (`maxChars`), дальше — фраза «Дальше на
+экране.».
+
+## Два мостика приложения
+
+Пакет не тянет вложения и распознавание речи в зависимости. Приложение подаёт их сюда двумя короткими функциями.
+Нет функции — человек получает понятный ответ: «Файлы здесь не принимаю», «Голосовые здесь не распознаю».
+
+**Файлы** — в вложения чата через `ingestFile` пакета `@ykurilov/agent-chat-attachments`. Владелец файла — человек,
+привязанный к аккаунту мессенджера (`ownerId`):
+
+```ts
+import type { AttachmentIngest } from "@ykurilov/agent-chat-messengers";
+
+const ingestMessengerFile: AttachmentIngest = ({ ownerId, chatId, bytes, name }) =>
+  attachments.ingestFile({ userId: ownerId, chatId, bytes, name });
+```
+
+Отказ вложений (`{ ok: false, reason }`: не тот тип, слишком большой, занято) человек получает словами, агент не
+запускается. Тип файла вложения определяют по содержимому, поэтому `mediaType` из мессенджера не нужен.
+
+**Голос** — обёртка над `transcribeAudioFile` пакета `@ykurilov/agent-chat-voice/server`:
+
+```ts
+import type { AudioTranscriber } from "@ykurilov/agent-chat-messengers";
+import { transcribeAudioFile } from "@ykurilov/agent-chat-voice/server";
+
+const transcribeVoice: AudioTranscriber = async ({ ownerId, audio }) => {
+  if (await voiceLimitReached(ownerId)) return { skipped: "limit" };
+  return {
+    text: await transcribeAudioFile({
+      bytes: audio,
+      apiKey: process.env.SONIOX_API_KEY!,
+      model: "stt-rt-preview",
+      languageHints: ["ru"],
+      websocketUrl: sonioxUrl, // с российского сервера — адрес прокси
+      logError: console.error,
+    }),
+  };
+};
+```
+
+`{ skipped: "limit" }` — человек узнаёт, что лимит исчерпан. Ошибка распознавания — «Не получилось распознать голосовое».
+Голосовые MAX, которые мессенджер распознал сам, сюда не попадают. Голосовое длиннее 10 минут или больше 20 МБ
+не распознаётся.
+
+## Вебхук: один бот на мессенджер
+
+У каждого мессенджера один адрес вебхука внутри `basePath`: `/telegram/webhook`, `/vk/callback`, `/max/webhook`.
+Его принимает первый бот этого мессенджера с `receive: "webhook"`. Второй бот того же мессенджера работает опросом
+(`receive: "polling"`). Это решение, а не недоделка: одному приложению нужен один бот в мессенджере, а адрес без id
+бота проще настроить.
+
+## Приём сообщений
+
+- Обновление от мессенджера записывается в хранилище вместе с содержимым, потом обрабатывается. Повтор того же
+  обновления от мессенджера не обрабатывается второй раз.
+- База не приняла запись — вебхук отвечает 503, и мессенджер присылает обновление снова. При опросе то же обновление
+  пробуется снова, пауза растёт от секунды до 30 секунд, следующие его не обгоняют. Обновление, которое не
+  записывается десять минут подряд, пропускается с ошибкой в `logError`: одно битое обновление не держит бота.
+- Цена этого порога: база недоступна дольше 10 минут — сообщения людей, которые не удалось записать за это время,
+  пропускаются. От них остаётся только запись в журнале ошибок, агент их не увидит. Вебхук после порога отвечает
+  мессенджеру 200, и мессенджер их больше не присылает.
+- Postgres не хранит символ NUL: хранилище убирает его из строк от мессенджера и модели перед записью.
+- Сервер упал посреди обработки — после срока аренды (2 минуты) обновление подбирает живая копия или эта же после
+  `start()`. Обработка сорвалась с ошибкой — повтор через полминуты. Не вышло за три повтора или прошли сутки —
+  обновление брошено, ошибка в `logError`.
+- Двойного ответа нет: сообщение агенту получает номер из ключа обновления. Повтор сверяется с историей чата. На
+  сообщение уже ответили — второго хода нет. Сообщение записано, а ответа нет — служба чата доводит ответ на него же,
+  файлы второй раз не скачиваются.
+- Приём — «хотя бы раз», не «ровно раз». Защита от двойного ответа агента есть, у остального её нет. Сервер упал
+  после обработки, но до записи «готово» — команда (`/new`, `/connect`) выполнится второй раз. Повторное нажатие
+  кнопки получит «Уже отвечено.».
+- Порядок при повторе не гарантирован. Повтор встаёт в очередь разговора за сообщениями, которые пришли позже и уже
+  обработаны: после падения сервера повтор идёт через 2 минуты, после ошибки — через полминуты.
+
+## Доставка ответов
+
+- Итог ответа, карточка и «Задача готова» записываются в хранилище до отправки. Сервер упал или перезапустился —
+  после старта (`start()`) недоставленное уходит снова, с теми же кнопками.
+- Копия сервера держит свои записи 2 минуты и продлевает раз в 30 секунд. Запись упавшей копии забирает другая копия
+  после этого срока. Две копии одну запись не шлют.
+- Доставка «хотя бы раз»: падение между отправкой и удалением записи даст повтор того же сообщения.
+- Мессенджер недоступен дольше повторов очереди — запись остаётся и повторяется позже: пауза растёт от 30 секунд
+  до 30 минут, после суток ожидания запись удаляется. Постоянная ошибка (отказ, блокировка) удаляет запись сразу.
+- Не переживают перезапуск: голосовые ответы и промежуточные правки живого сообщения. Итог их перекрывает.
+- `onAnswerDelivery` получает исход каждого ответа агента: чей ответ (`ownerId`, `chatId`, `messageId`), как начат ход
+  (`trigger`: `human` или `notice` — агент пишет первым) и `outcome`. Один ответ может дать несколько исходов: `retry`,
+  потом итог повтора. Разбирать по `messageId`, последний главнее. Ошибка в обработчике уходит в `logError`.
+- ВК не пускает писать первым, пока человек не напишет сам (ошибка 950): это `window_closed` и
+  `MessengerWindowClosedError`, а не сбой.
+- С проверками ответа (`replyChecks` службы чата) мессенджер не шлёт ответ по словам: уходит только проверенный текст.
+
+## Карточки задач
+
+- Задача ждёт подтверждения — карточка «Разрешить / Отклонить». Кнопки несут номер вопроса: нажатие на старой
+  карточке после нового вопроса отвечает «Уже отвечено.».
+- Фоновая задача идёт — карточка «Задача … выполняется» с кнопкой «Отменить задачу».
+- Задача закончена — «Задача готова» в личный чат того, кто её запустил.
+
+## Хранилище
+
+Память (`createMemoryMessengerStore`, для тестов), SQLite (`/sqlite`) и Postgres (`/postgres`). Миграции лежат в
+`drizzle/` и применяются при создании хранилища.
+
+После `start()` записи старше 30 дней убираются при запуске и потом раз в час: коды привязки, принятые обновления,
+кнопки под ответами, обращения участников групп. Кнопка под ответом старше месяца отвечает «Уже отвечено.».
+Привязки, разговоры и недоставленные итоги не убираются, сколько бы им ни было. Необработанное входящее обновление
+остаётся, пока его кто-то держит или ждёт повтора. Если его никто не трогал 30 дней (например, бота убрали из
+настроек), оно убирается вместе с текстом.
+
+SQLite и Postgres открывают своё соединение: файл и пул. Закрывает его `store.close()` — зовите при остановке сервера
+после `messengers.stop()`. Повторный вызов ничего не делает. Если хранилище не удалось подготовить (база недоступна,
+миграция упала), соединение закрывается до ошибки. Чужой пул или файл хранилище не принимает, поэтому закрывает только
+своё.

package/dist/chunk-4QQ62ZKT.js

@@ -0,0 +1,197 @@
+// src/messenger-api.ts
+import { scrubSecrets } from "@ykurilov/agent-chat-core";
+var MIN_SECRET_LENGTH = 8;
+var MessengerApiError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "MessengerApiError";
+  }
+  status;
+};
+var MessengerRateLimitError = class extends MessengerApiError {
+  constructor(message, retryAfterMs) {
+    super(message, 429);
+    this.retryAfterMs = retryAfterMs;
+    this.name = "MessengerRateLimitError";
+  }
+  retryAfterMs;
+};
+var MessengerBlockedError = class extends MessengerApiError {
+  constructor(message) {
+    super(message, 403);
+    this.name = "MessengerBlockedError";
+  }
+};
+var MessengerWindowClosedError = class extends MessengerApiError {
+  constructor(message) {
+    super(message, 403);
+    this.name = "MessengerWindowClosedError";
+  }
+};
+var MessengerMarkupError = class extends MessengerApiError {
+  constructor(message) {
+    super(message, 400);
+    this.name = "MessengerMarkupError";
+  }
+};
+function createMessengerApi(input) {
+  const settings = input.api ?? {};
+  const ownFetch = "fetch" in settings ? settings.fetch : void 0;
+  const headers = "fetch" in settings ? {} : settings.headers ?? {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (value.length < MIN_SECRET_LENGTH) {
+      throw new Error(`${input.messenger}: \u0437\u043D\u0430\u0447\u0435\u043D\u0438\u0435 \u0437\u0430\u0433\u043E\u043B\u043E\u0432\u043A\u0430 \xAB${name}\xBB \u043A\u043E\u0440\u043E\u0447\u0435 ${MIN_SECRET_LENGTH} \u0437\u043D\u0430\u043A\u043E\u0432 \u2014 \u0442\u0430\u043A\u043E\u0439 \u0442\u043E\u043A\u0435\u043D \u043D\u0435 \u0441\u043F\u0440\u044F\u0442\u0430\u0442\u044C \u0432 \u0436\u0443\u0440\u043D\u0430\u043B\u0430\u0445; \u043D\u0443\u0436\u0435\u043D \u0434\u043B\u0438\u043D\u043D\u0435\u0435`);
+    }
+  }
+  const baseUrl = (("fetch" in settings ? void 0 : settings.baseUrl) ?? input.defaultBaseUrl).replace(/\/+$/, "");
+  const secrets = [input.token, ...Object.values(headers)].filter((value) => value.length >= MIN_SECRET_LENGTH);
+  const hideSecrets = (text) => scrubSecrets(text, secrets);
+  return {
+    baseUrl,
+    hideSecrets,
+    error: (status, description) => new MessengerApiError(`${input.messenger}: ${hideSecrets(description)}`, status),
+    async fetch(path, init = {}) {
+      const merged = new Headers(init.headers);
+      for (const [name, value] of Object.entries(headers)) merged.set(name, value);
+      try {
+        return await (ownFetch ?? globalThis.fetch)(`${baseUrl}${path}`, { ...init, headers: merged });
+      } catch (error) {
+        if (init.signal?.aborted) throw error;
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new MessengerApiError(`${input.messenger}: \u0441\u0431\u043E\u0439 \u0437\u0430\u043F\u0440\u043E\u0441\u0430 \u043A API: ${hideSecrets(reason)}`, 0);
+      }
+    }
+  };
+}
+function buttonsRejected(error) {
+  return error instanceof MessengerApiError && !(error instanceof MessengerBlockedError) && !(error instanceof MessengerWindowClosedError) && !(error instanceof MessengerRateLimitError) && !(error instanceof MessengerMarkupError) && error.status >= 400 && error.status < 500;
+}
+
+// src/bot-commands.ts
+function parseCommand(text) {
+  const match = /^\/([A-Za-z0-9_]+)(?:@\S+)?(?:\s+([\s\S]*))?$/.exec((text ?? "").trim());
+  return match ? { name: (match[1] ?? "").toLowerCase(), args: (match[2] ?? "").trim() } : null;
+}
+function commandOf(update) {
+  if (update.kind === "start") return { name: "start", args: update.startPayload ?? "" };
+  return update.kind === "command" ? parseCommand(update.text) : null;
+}
+
+// src/bounded-body.ts
+var MAX_JSON_BODY_BYTES = 1024 * 1024;
+var BodyTooLargeError = class extends Error {
+  constructor(maxBytes) {
+    super(`\u0442\u0435\u043B\u043E \u0431\u043E\u043B\u044C\u0448\u0435 ${maxBytes} \u0431\u0430\u0439\u0442`);
+    this.maxBytes = maxBytes;
+    this.name = "BodyTooLargeError";
+  }
+  maxBytes;
+};
+async function readAtMost(source, maxBytes, tooLarge = () => new BodyTooLargeError(maxBytes)) {
+  if (Number(source.headers.get("content-length")) > maxBytes) {
+    void source.body?.cancel().catch(() => void 0);
+    throw tooLarge();
+  }
+  if (!source.body) return new Uint8Array(0);
+  const reader = source.body.getReader();
+  const chunks = [];
+  let size = 0;
+  for (let read = await reader.read(); !read.done; read = await reader.read()) {
+    size += read.value.byteLength;
+    if (size > maxBytes) {
+      void reader.cancel().catch(() => void 0);
+      throw tooLarge();
+    }
+    chunks.push(read.value);
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}
+async function readJsonBody(request) {
+  let bytes;
+  try {
+    bytes = await readAtMost(request, MAX_JSON_BODY_BYTES);
+  } catch (error) {
+    return { error: error instanceof BodyTooLargeError ? "too_large" : "bad" };
+  }
+  try {
+    return { json: JSON.parse(new TextDecoder().decode(bytes)) };
+  } catch {
+    return { error: "bad" };
+  }
+}
+
+// src/messenger-files.ts
+function uploadForm(fields) {
+  const form = new FormData();
+  for (const [name, value] of Object.entries(fields)) {
+    if (value === void 0) continue;
+    if (typeof value === "string") form.set(name, value);
+    else form.set(name, new Blob([value.bytes], value.mediaType ? { type: value.mediaType } : {}), value.name);
+  }
+  return form;
+}
+var MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024;
+var DownloadTooLargeError = class extends Error {
+  constructor(maxBytes) {
+    super(`\u0444\u0430\u0439\u043B \u0431\u043E\u043B\u044C\u0448\u0435 ${maxBytes} \u0431\u0430\u0439\u0442`);
+    this.maxBytes = maxBytes;
+    this.name = "DownloadTooLargeError";
+  }
+  maxBytes;
+};
+async function downloadedFile(response, maxBytes = MAX_DOWNLOAD_BYTES) {
+  const mediaType = response.headers.get("content-type")?.split(";")[0]?.trim();
+  const bytes = await readAtMost(response, maxBytes, () => new DownloadTooLargeError(maxBytes));
+  return { bytes, ...mediaType && { mediaType } };
+}
+var MEDIA_TYPES = {
+  pdf: "application/pdf",
+  txt: "text/plain",
+  csv: "text/csv",
+  md: "text/markdown",
+  json: "application/json",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  zip: "application/zip",
+  mp3: "audio/mpeg",
+  ogg: "audio/ogg",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+};
+function mediaTypeOfExtension(ext) {
+  return ext ? MEDIA_TYPES[ext.toLowerCase().replace(/^\./, "")] : void 0;
+}
+function mediaTypeOfFileName(name) {
+  return name?.includes(".") ? mediaTypeOfExtension(name.split(".").pop()) : void 0;
+}
+
+export {
+  parseCommand,
+  commandOf,
+  readJsonBody,
+  uploadForm,
+  MAX_DOWNLOAD_BYTES,
+  DownloadTooLargeError,
+  downloadedFile,
+  mediaTypeOfExtension,
+  mediaTypeOfFileName,
+  MessengerApiError,
+  MessengerRateLimitError,
+  MessengerBlockedError,
+  MessengerWindowClosedError,
+  MessengerMarkupError,
+  createMessengerApi,
+  buttonsRejected
+};
+//# sourceMappingURL=chunk-4QQ62ZKT.js.map