@besales/mcp 1.0.0-beta.2 → 1.0.0-beta.5

package/docs/dialogue-nudge.md

@@ -0,0 +1,50 @@
+# Подтолкнуть агента
+
+`besales_dialogue_nudge_agent` нужен, когда клиент остался без ответа из-за ошибки или
+сбоя бота, а переобработка последнего входящего не подходит. Он запускает полный ход
+по всей истории диалога. Это платная операция: клиент получит настоящее сообщение бота.
+Инструмент отказывает (`REFUSED`, при тишине обычно `BOT_SILENCED`) при тишине,
+поставленной человеком/оператором (ручная остановка, стоп-слово), отписке, блокировке,
+бане, вне срока переписки канала, при выключенном канале/ИИ и пока ход уже идёт.
+Отказ сервера не обходи.
+
+Служебную тишину (ожидание оператора «до /start», стадия CRM, фильтр сделки,
+тишина агента) инструмент снимает и возвращает `reactivated: true`, как кнопка в интерфейсе.
+Перед подтверждением предупреди человека: клиент получит настоящее сообщение бота
+даже при служебном ожидании оператора. Покажи `reactivated` в итоге.
+
+Только после явного «да» человека передай `explicit_confirmation: true` и
+`conversation_ids`: от 1 до 30 UUID без дублей. `workspace_id` необязателен; без него
+используется выбранное подключение. Агент выбирается сервером: тело запроса всегда `{}`.
+API должен разрешать MCP-ключу область `run:conversation-nudge`.
+
+Для каждого диалога мост отправляет `POST /conversations/{id}/nudge-agent` с заголовком
+`Idempotency-Key: nudge:<UUID в нижнем регистре>:<SHA-256 attempt_key>`.
+Необязательный `attempt_key` — строка до 64 символов, по умолчанию пустая. Тот же вход
+отправляет тот же ключ, независимо от порядка диалогов в пакете. Сервер возвращает
+прежний результат без второго ответа клиенту. Для нового осознанного запуска позже
+можно задать новый `attempt_key`, только после нового явного подтверждения.
+
+Запросы последовательные. Отчёт разделяет:
+
+- `STARTED` — ход принят. `delivery` отдельно показывает `DELIVERED`, `NOT_DELIVERED`
+  или `PENDING`; `PENDING` не подтверждает доставку. Сохраняются `notice`, `reasonCode`,
+  `reactivated` и `replayed`. При `replayed=true` нового запуска не было.
+  Если беседа была закрыта (`CLOSED`/`RESOLVED`) и текущей нет, сервер создаёт новую:
+  `conversationId` в отчёте сохраняет запрошенный UUID, `startedConversationId` содержит
+  новый UUID, а `message` поясняет «диалог был закрыт — создан новый».
+  Статус определяется по `delivery` как обычно; переписку проверяй по новому UUID.
+- `REFUSED` — отказ с HTTP-статусом, кодом, текстом и доступной причиной. 404 и 409
+  не мешают следующим диалогам. 429 останавливает пакет.
+- `UNKNOWN` — 503, таймаут, сетевая ошибка, некорректная квитанция или
+  `delivery=UNKNOWN`. Не повторяй запуск, не меняй ключ. Сначала проверь переписку через
+  `besales_dialogue_transcript`; отсутствие сообщения ещё не доказывает отказ запуска.
+- `NOT_PROCESSED` — запрос не отправлялся после 429. Автоматически пакет не продолжай.
+
+STARTED не равно доставлено: смотри `delivery` у каждого. В `summary` сохранены
+`started`, `refused`, `unknown`, `notProcessed`; дополнительно `notDelivered` считает
+`STARTED` с `NOT_DELIVERED`, а `deliveryUnknown` — квитанции с `UNKNOWN`/`PENDING`.
+
+Отчёт не усекается: при превышении бюджета ответа общий конверт моста возвращает
+квитанцию с предупреждением вместо частичного отчёта. В будущих вызовах выбирай
+меньший пакет; уже отправленный пакет целиком не повторяй.

package/docs/dialogue-reprocess.md

@@ -0,0 +1,37 @@
+# Повтор ответа на последнее входящее
+
+`besales_dialogue_reprocess_last_inbound` заново запускает ответ бота на сохранённое последнее
+сообщение клиента. Нового входящего в истории не появляется. Клиент получит настоящее сообщение;
+генерация ответа расходует квоту. Нужен администратор с правом управления каналом и явное «да» человека.
+
+Перед вызовом покажи человеку выбранные диалоги и последствие: бот ответит каждому клиенту.
+После подтверждения передай `conversation_ids` — от одного до 50 UUID без дублей — и
+`explicit_confirmation: true`. Поле `workspace_id` выбирает подключение по обычным правилам моста.
+Без подтверждения, при дублях, невалидном UUID или превышении лимита ни один запрос не отправляется.
+
+Не применяй, если клиент уже видел ответ, бот заглушён или ход идёт. Сервер проверяет эти условия,
+а также более новое входящее, отказ клиента, закрытое окно переписки и остальные ограничения кнопки.
+Инструмент вызывает тот же `POST /conversations/:conversationId/reprocess-last-inbound`, сохраняя
+серверные правила допуска, дедупликации и брони. Область `run:conversation-reprocess` входит в `mcp:*`;
+роль человека за ключом проверяется сервером. Личные ключи публичного API и интеграции не допускаются.
+
+Запросы идут строго последовательно. В `results` для каждого диалога возвращается:
+
+- `ENQUEUED`: исходное `messageId` и уведомление сервера. Это постановка в очередь, не доставка.
+- `REFUSED`: `httpStatus`, `code` и `message` сервера. Отказы одного диалога не скрывают остальные.
+- `UNKNOWN`: исход отправленного запроса неизвестен (таймаут, 5xx или неразобранное подтверждение).
+- `NOT_PROCESSED`: запрос не отправлялся, потому что перед ним получен 429.
+
+Сводка `summary` содержит `enqueued`, `refused`, `unknown`, `notProcessed`; сумма равна размеру списка.
+При 429 пакет останавливается без ожидания и автоповтора, доступный срок ожидания возвращается как
+`retryAfterSeconds`. Не повторяй весь пакет: уже принятые диалоги остаются принятыми.
+
+При `UNKNOWN` сначала найди квитанцию или статус хода и проверь переписку через
+`besales_dialogue_transcript`. Отсутствие ответа в истории сразу после вызова не доказывает,
+что постановка не состоялась. Отдельного маршрута receipt у этой операции нет; до выяснения
+исхода не повторяй мутацию автоматически. Результат пакета не усекать.
+При отказе по размеру передавай меньше `conversation_ids` в следующих вызовах; уже отправленный пакет не повторяй, сначала проверь квитанции, статус хода и переписку.
+
+Версия пакета остаётся предварительной. Выпуск — после выкладки API и серверной проверки,
+по решению владельца и правилам [RELEASING.md](../RELEASING.md). Подписанную выгрузку маршрутов
+перевыпускают из чистого коммита моста; локальный диагностический экспорт её не заменяет.

package/docs/modules/besales-mcp.md

@@ -135,3 +135,10 @@ enumValuesByPath разворачивает refs и все ветки anyOf/oneO
 Адрес отказавшего поля API сохраняется в `error.details.path`, например `isEnabled` или
 `config.steps[0].getcourse.delivery`. Диагностика допускает только ограниченный адрес поля;
 URL, файловые пути и произвольное содержимое вместо адреса не передаются.
+
+Предпросмотр холодного приветствия GetCourse принимает `message` вместе с `mailing_variant_id`,
+включая `continuation:true`: разовый текст переопределяет текст рассылки, её настройки сохраняются.
+Продолжению по-прежнему нужны файл contacts, сегмент и фактически выбранный непустой текст;
+отсутствие обоих источников адресуется обоим полям. `start` и `batch_start` требуют ровно один источник.
+Проверки: `getcourse-cold-welcome.spec.ts` и `scripts/getcourse-text-source.spec.mjs`; второй набор
+также сохраняет контроль альтернативных путей отказа с искусственным XOR.

package/docs/telegram-personal-management.md

@@ -0,0 +1,100 @@
+# Личные номера Telegram: прогрев и лесенка
+
+Инструменты входят в профиль `platform`, читающие — также в `readonly`. Мост обращается
+только к ядру Besales; пароли, сессии и ключи Telegram не принимаются и не возвращаются.
+Идентификаторы канала и номера берутся из навигации и таблицы номеров.
+
+| Инструмент `besales_platform_telegram_personal_…` | Назначение | Право |
+| --- | --- | --- |
+| `accounts` | Таблица номеров, сводка и листание | `read:channels` |
+| `warmup` | Настройки и аналитика прогрева | `read:channels` |
+| `warmup_update` | Частичная правка настроек прогрева | `manage:channels` |
+| `account_warmup` | Включение и ручной отказ отдельного номера | `manage:channels` |
+| `ramp` | Чтение `newAccountRampEnabled` | `read:channels` |
+| `profile_bulk` | Пачечная правка профилей своих номеров: имя, описание, дата рождения, ники | `manage:channels` |
+| `profile_job` | Итог задания правки профилей по номерам | `read:channels` |
+
+У инструментов канала обязателен `channel_id`; у `account_warmup` также `account_id`
+и булев `is_warming_up`. `workspace_id` можно не передавать при выбранной рабочей области.
+Лишнее поле отклоняется до HTTP. Прогревом можно управлять без подтверждения, потому что
+сообщения идут только между своими номерами.
+
+Таблица принимает `search` (до 200 знаков), `status` (состояние связи), `page` (от 1)
+и `limit` (1–100). Сводка `summary` относится ко всем живым номерам до фильтра;
+`pagination` описывает страницу, `truncated` — неполное чтение. Мост сохраняет их целиком.
+Прогрев читается отдельно в `warmup`: `active`, `reason`, `label`, `until`, `optedOut`.
+Он не блокирует участие в рассылке; `campaign` и состояние строки показывают участие и разгон.
+`restriction` содержит ограничения, наблюдения проверок и жалоб. `autoAppealNotBefore`
+не означает запланированную подачу: автоматическая подача жалоб сейчас выключена.
+
+Лесенка: 3, 4, 5, 6, 7 с первого дня рассылки; прогрев идёт параллельно 5 дней.
+Прогрев включается сам при подключении номера, если его не выключить вручную.
+`is_warming_up:false` выводит номер из автоматического прогрева до ручного включения;
+true снимает ручной отказ. Чтение лесенки возвращает только её булев флаг, без других
+настроек рассылки.
+
+`warmup_update` принимает поля `TelegramWarmupPatchDto` в snake_case: `enabled`,
+`images_enabled`, `messages_per_day`, `time_variation_minutes`, `response_delay_min_minutes`,
+`response_delay_max_minutes`, `image_chance_percent`, `posts_to_react`,
+`max_accounts_per_channel_reaction`, `pairing_hour_utc`, `hourly_interval_hours`,
+`reaction_types` (до 100 строк), `reaction_hours_utc` (до 24 целых чисел).
+В HTTP уходят camelCase-поля DTO. Пропуск сохраняет прежнее значение, false, 0 и []
+передаются буквально. Допустимые рабочие диапазоны настроек проверяет ядро.
+
+## Профили номеров: `profile_bulk` и `profile_job`
+
+`profile_bulk` меняет профили СВОИХ личных номеров канала, а не клиентов. Операция идёт
+заданием фермы номеров: ответ `{job_id, state, total}` означает «принято», а не «изменено».
+Итог по каждому номеру читает `profile_job` (`channel_id` и `job_id` из ответа): `state` задания
+(`PENDING`, `RUNNING`, `COMPLETED`), `counters`, а у каждого номера — `state`, `failure_code` и
+`outcome.fields.<поле>`. Элемент с частичным успехом остаётся `SUCCEEDED`, поэтому читай поля:
+отдельное поле может быть `FAILED`. `TELEGRAM_BIO_TOO_LONG` — описание длиннее лимита Telegram
+(до 70 знаков без Premium, до 140 с Premium); `PROFILE_PROVIDER_OUTCOME_UNKNOWN` — исход у
+Telegram неизвестен, сначала сверь профиль номера, не повторяй вслепую.
+
+Поля `profile_bulk` в snake_case, в HTTP уходят camelCase-поля `TelegramPersonalBulkProfileDto`:
+
+| Вход | В теле ядра | Правило |
+| --- | --- | --- |
+| `account_ids` или `all:true` | `accountIds` или `all` | ровно одно; `account_ids` — 1–100 уникальных UUID v4 |
+| `first_name`, `last_name` | `patch.firstName`, `patch.lastName` | до 64 знаков, без нормализации |
+| `bio` | `patch.bio` | до 140 знаков; лимит Telegram по Premium проверяет ферма |
+| `birthday` | `patch.birthday` | `{day, month, year?}`; `null` снимает дату |
+| `usernames` | `usernames[{accountId, username}]` | ники по номерам; `account_ids` и `all` не передаются |
+| `username_base` | `usernameBase` | основа ника для номеров из `account_ids` или `all` |
+| `idempotency_key` | заголовок `x-idempotency-key` | обязателен: 1–200 видимых ASCII-знаков без пробелов |
+
+Фото через MCP пока не меняется — только в приложении: поле `avatar_file_id` не принимается и
+отвергается до HTTP как лишнее.
+
+Пропуск поля сохраняет прежнее значение; пустые строки и `null` передаются буквально, а
+ложное или пустое значение выбора (`all:false`, `account_ids:[]`, `usernames:[]`) отвергается до HTTP.
+Вызов без единой правки (ни поля профиля, ни ников) тоже отвергается: нечего менять.
+
+Ники — ровно один режим либо ни одного: `usernames` (по номерам) или `username_base` (общая основа).
+Оба режима сразу, `usernames` вместе с `account_ids`/`all`, повтор номера или ника (без учёта
+регистра) и ник вне правил Telegram (5–32 знака, латиница, цифры и `_`, с буквы, без `__`,
+без `_` в конце) отвергаются до HTTP. Ники необратимо освобождают прежние ники у Telegram:
+перед вызовом покажи человеку список номеров и новые значения и получи ответ «делать?».
+Явный `explicit_confirmation` не принимается: так решено в плане пачки.
+
+Ключ идемпотентности для этого маршрута ядро читает из `x-idempotency-key`, а не из общего
+`Idempotency-Key`, поэтому транспорт моста отправляет его именно под этим именем (поле
+`idempotencyKeyHeader` запроса). Повтор того же намерения — с тем же ключом и аргументами:
+ядро вернёт прежний ответ, профиль второй раз не изменится и суточный предел смен не тратится.
+При неизвестном исходе новый ключ автоматически не создавай.
+
+Ссылка настройки номера (`…_setup_link`) в этой пачке не выпускается: маршрута
+`telegram-personal-setup-sessions` в ядре нет, это отдельная задача ядра.
+
+Ограничения, ручная жалоба и чтение её исхода описаны в
+[документе апелляции](telegram-personal-restrictions.md). Перед жалобой покажи человеку
+номер и текст, получи явное согласие и только затем передай `explicit_confirmation:true`.
+Жалоба необратима, не чаще раза в сутки на номер; автоматическая подача выключена.
+
+Проверки схем, запросов, профилей, строгого ввода, описаний и сохранения ответа находятся
+в `telegram-personal-management.spec.ts`, `telegram-personal-restrictions.spec.ts` и
+`telegram-personal-profile.spec.ts`. `scripts/telegram-personal-confirmation-mutants.mjs`
+проверяет, что снятие обязательного согласия в Zod или опубликованной схеме ломает именованное
+утверждение теста. `scripts/telegram-personal-profile-mutants.mjs` делает то же для запрета
+двух режимов ников сразу (в Zod и в опубликованной схеме) и для имени заголовка ключа.

package/docs/telegram-personal-restrictions.md

@@ -0,0 +1,87 @@
+# Ограничения личных номеров Telegram
+
+Все три инструмента входят в профиль `platform`. Они обращаются к API выбранного канала;
+UUID номера берётся из таблицы номеров. Прямых обращений к сервису номеров в мосту нет.
+
+| Инструмент                                                | Назначение                                   | Право             |
+| --------------------------------------------------------- | -------------------------------------------- | ----------------- |
+| `besales_platform_telegram_personal_restriction_check`    | Проверка через системного бота @SpamBot      | `manage:channels` |
+| `besales_platform_telegram_personal_restriction_appeal`   | Отправка апелляции от выбранных номеров      | `manage:channels` |
+| `besales_platform_telegram_personal_operational_task_get` | Чтение состояния задачи и ограничений номера | `read:channels`   |
+
+В проверке и апелляции выбери ровно одну форму: `all:true` либо `account_ids` из 1–100 уникальных
+UUID v4. Предел 100 относится и ко всем номерам канала: если их больше, API отклонит пакет до
+постановки. `workspace_id` необязателен при однозначно выбранном пространстве.
+`idempotency_key` обязателен: 1–200 видимых ASCII-символов без пробелов. Мост передаёт его в
+`idempotencyKey` тела API. Заголовок `x-idempotency-key` также поддерживается ядром; разные
+ключи в теле и заголовке дают 400. Для одного намерения сохраняй ключ и аргументы.
+
+Проверка обращается только к системному боту, людям ничего не отправляет и
+`explicit_confirmation` не принимает. Апелляция требует явного согласия человека и
+`explicit_confirmation:true`. Перед вызовом покажи человеку номер и свой текст, если он задан (без текста система подберёт английский шаблон сама), и получи явное согласие.
+Автоматическая подача сейчас выключена. Номер отправит текст @SpamBot от своего имени, отменить отправку
+нельзя. `text` необязателен: без него система выбирает английский текст из пула разных
+апелляций со спинтаксом: 18 шаблонов, 144 раскрытия, отдельно для каждого номера,
+без одинаковых текстов внутри пакета. Формулировок об общении только по входящим обращениям нет.
+Выбор сохраняется до отправки и повторяется с тем же ключом. Сохранённый удалённый или
+неизвестный ID даёт 409 `IDEMPOTENCY_REQUEST_MISMATCH` до отправки всей пачки;
+новый ключ автоматически не создаётся. Свой `text` — 1–500 знаков
+после удаления пробелов по краям; он имеет приоритет и не раскрывается как спинтакс.
+Ограничение — раз в UTC-сутки
+на номер; автоматической апелляции нет.
+
+Ответ пакетных инструментов содержит `items` с отдельным исходом каждого номера:
+`QUEUED` с `taskId`, `FAILED` с `code/message` или `SKIPPED` с причиной. `APPEAL_NOT_RESTRICTED`
+и `APPEAL_DAILY_LIMIT` дают `SKIPPED`. Очередь не подтверждает проверку или отправку апелляции.
+Для системного текста исход номера содержит `appealTemplateId`; текст в ответе не возвращается.
+Квитанции не обрезаются. При неизвестном исходе сначала прочитай задачу или доступность
+номеров (`besales_get_telegram_personal_capacity`); новый ключ автоматически не создавай.
+Если taskId неизвестен, capacity показывает последний результат и время проверки, но не
+доказывает исход именно твоего запроса.
+
+Чтение задачи принимает `channel_id` и `task_id`, входит также в `readonly` и возвращает
+`state` (`PENDING`, `RUNNING`, `SUCCEEDED`, `FAILED`), код/текст отказа и `restrictionStatus`.
+Последнее поле — текущий статус номера, прочитанный после задачи, а не исторический снимок
+её исхода. Более поздние действия могли его изменить. `null` означает, что статус номера
+недоступен; `SUCCEEDED` само по себе не означает отсутствие ограничений.
+
+Примеры с вымышленными UUID:
+
+```json
+{
+  "name": "besales_platform_telegram_personal_restriction_check",
+  "arguments": {
+    "channel_id": "23000000-0000-4000-8000-000000000001",
+    "all": true,
+    "idempotency_key": "example-check-1"
+  }
+}
+```
+
+```json
+{
+  "name": "besales_platform_telegram_personal_restriction_appeal",
+  "arguments": {
+    "channel_id": "23000000-0000-4000-8000-000000000001",
+    "account_ids": ["24000000-0000-4000-8000-000000000001"],
+    "explicit_confirmation": true,
+    "idempotency_key": "example-appeal-1"
+  }
+}
+```
+
+```json
+{
+  "name": "besales_platform_telegram_personal_operational_task_get",
+  "arguments": {
+    "channel_id": "23000000-0000-4000-8000-000000000001",
+    "task_id": "25000000-0000-4000-8000-000000000001"
+  }
+}
+```
+
+Выкладка: сначала ядро с поддержкой ключа в теле и `restrictionStatus`, затем мост после
+вливания в отгружаемую ветку. В тот же день выгрузи реестр маршрутов командой
+`BESALES_SPECS_CONTRACTS_DIR=/путь/к/specs/contracts BESALES_API_CONTRACTS_DIR=/путь/к/besales-api/contracts yarn publish:mcp-registry`.
+В ядре выполни `yarn contracts:mcp-routes:check` и `yarn contracts:mcp-routes:check-fresh`.
+До вливания моста выгрузка не выполняется; `contracts/mcp-tool-routes.json` вручную не правится.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@besales/mcp",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0-beta.5",
   "description": "Model Context Protocol server for Besales",
   "license": "MIT",
   "homepage": "https://github.com/be-sales/mcp#readme",

package/scripts/getcourse-text-source.spec.mjs

@@ -0,0 +1,110 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { getcourseColdWelcomeTools } from '../src/tools/definitions/getcourse-cold-welcome.ts';
+import { diffRegistries } from './registry-diff.mjs';
+import { sampleFor } from './sample-args.mjs';
+import { loadShippedDefinitions } from './shipped-definitions.mjs';
+import { shippedRef } from './shipped-ref.mjs';
+import { mergeShippedArgs } from './shipped-sample-candidates.mjs';
+import {
+  buildShippedSample,
+  filterOf,
+  prepareKnownArgs,
+  routeShape,
+  schemaLagExplains,
+  schemaPathsOf,
+} from './shipped-sample.mjs';
+
+const inputRoot = fileURLToPath(new URL('..', import.meta.url));
+const inputWorkspace = '00000000-0000-4000-8000-0000000000ff';
+const inputMap = JSON.parse(
+  readFileSync(new URL('../src/schemas/mcp-v2-route-map.json', import.meta.url), 'utf8'),
+);
+const inputLocalRegistry = JSON.parse(
+  readFileSync(new URL('../src/schemas/mcp-tools.json', import.meta.url), 'utf8'),
+);
+let inputShippedRegistry;
+let inputShippedDefinitions;
+
+// Как у emit-tool-routes.spec.mjs: настоящий кэшированный git-ref, без fetch и записи Git.
+beforeAll(async () => {
+  const commit = execFileSync('git', ['-C', inputRoot, 'rev-parse', shippedRef()], {
+    encoding: 'utf8',
+  }).trim();
+  inputShippedRegistry = JSON.parse(
+    execFileSync('git', ['-C', inputRoot, 'show', commit + ':src/schemas/mcp-tools.json'], {
+      encoding: 'utf8',
+      maxBuffer: 16 * 1024 * 1024,
+    }),
+  );
+  inputShippedDefinitions = (await loadShippedDefinitions(inputRoot, commit)).toolDefinitions;
+}, 60000);
+
+describe('источник текста в настоящем переборе отгруженных образцов', () => {
+  it.each([
+    { suffix: 'preview', xor: false },
+    { suffix: 'start', xor: false },
+    { suffix: 'batch_start', xor: false },
+    { suffix: 'preview', xor: true },
+  ])(
+    'cold_welcome_$suffix (контроль XOR=$xor): отгруженный образец без ложного отсутствия текста',
+    ({ suffix, xor }) => {
+      const name = `besales_getcourse_cold_welcome_${suffix}`;
+      const definition = getcourseColdWelcomeTools.find((entry) => entry.name === name);
+      const shippedDefinition = inputShippedDefinitions.find((entry) => entry.name === name);
+      const shippedSchema = inputShippedRegistry.tools.find(
+        (entry) => entry.name === name,
+      ).inputSchema;
+      const localSchema = inputLocalRegistry.tools.find((entry) => entry.name === name).inputSchema;
+      const canonical = inputMap.find((entry) => entry.tool === name).canonicalArgs;
+      // Искусственный адресный XOR сохраняет регрессию W10FIX3, когда продуктовый preview уже исправлен.
+      const acceptV2 = filterOf(
+        xor
+          ? {
+              ...definition,
+              schema: definition.schema.superRefine((input, ctx) => {
+                if (
+                  input.continuation === true &&
+                  input.message !== undefined &&
+                  input.mailing_variant_id !== undefined
+                ) {
+                  for (const field of ['message', 'mailing_variant_id']) {
+                    ctx.addIssue({ code: 'custom', path: [field], message: 'контроль XOR' });
+                  }
+                }
+              }),
+            }
+          : definition,
+        inputWorkspace,
+      );
+      const main = acceptV2(canonical);
+      expect(main.ok).toBe(true);
+      const mainRouteShape = routeShape(main.request);
+      const shippedPaths = schemaPathsOf(shippedSchema, name);
+      const v2Paths = schemaPathsOf(localSchema, name);
+      const lag = diffRegistries(
+        inputShippedRegistry.tools,
+        inputLocalRegistry.tools,
+      ).contractLag.filter((entry) => entry.tool === name);
+      const known = prepareKnownArgs(canonical, shippedPaths, { acceptV2, mainRouteShape });
+      const outcome = buildShippedSample({
+        full: mergeShippedArgs(sampleFor(name, shippedSchema, false), known),
+        known,
+        acceptShipped: filterOf(shippedDefinition, inputWorkspace),
+        acceptV2,
+        explains: (path, args) => schemaLagExplains(path, args, lag, v2Paths),
+        shippedConstraints: shippedPaths,
+        goodValues: () => [],
+        mainRouteShape,
+      });
+      expect(outcome.absentKnown).toEqual([]);
+      expect(outcome.refused).toEqual(xor ? [{ path: 'message', message: 'контроль XOR' }] : []);
+      expect(outcome.pathless).toEqual([]);
+      expect(outcome.impossible).toBeUndefined();
+      expect(routeShape(outcome.request)).toEqual(mainRouteShape);
+    },
+  );
+});

package/scripts/shipped-sample.mjs

@@ -452,6 +452,9 @@ export function v2Verdict(args, acceptV2, explains) {
       }
       current = withoutPath(current, path);
       omitted.push({ path, why: 'DECLARED' });
+      // Пути одного отказа могут быть альтернативами: не снимаем следующий, если v2 уже принимает.
+      const retried = acceptV2(current);
+      if (retried.ok) return { request: retried.request, args: current, omitted, refused };
     }
   }
   return { pathless: ['ветка v2 не приняла образец за предел раундов снятия'], omitted, refused };

package/scripts/sync-trigger-argument-schema.mjs

@@ -8,13 +8,19 @@ import { triggerActionArgumentSchema } from '../dist/tools/definitions/trigger-a
 import { toolDefinitions } from '../dist/tools/definitions.js';
 import { triggerActionItemSchema } from '../dist/tools/definitions/platform-setup.js';
 import { canonicalCallOperatorTaskSchema } from '../dist/tools/definitions/call-operator-task.schema.js';
+import { syncCallOperatorTaskSchema } from './sync-trigger-task-schema.mjs';
 
 // Границы опубликованных полей — из контракта выбранного API checkout, не из ручного JSON.
 const contractsDir = process.env.BESALES_API_CONTRACTS_DIR?.trim() || '../besales-api/contracts';
 let callOperator;
 await openapiTS(pathToFileURL(resolve(contractsDir, 'openapi-besales-api.yaml')), {
   transform(schema) {
-    if (schema.properties?.step_type?.enum?.includes('CALL_OPERATOR') && schema.properties.task_text && schema.properties.task_due_hours) callOperator = schema;
+    if (
+      schema.properties?.step_type?.enum?.includes('CALL_OPERATOR') &&
+      schema.properties.task_text &&
+      schema.properties.task_due_hours
+    )
+      callOperator = schema;
   },
 });
 if (!callOperator?.properties?.task_text || !callOperator.properties.task_due_hours) {
@@ -29,38 +35,7 @@ const canonical = z.toJSONSchema(canonicalCallOperatorTaskSchema, {
   target: 'draft-7',
   io: 'input',
 });
-for (const [name, alias] of [
-  ['task_text', 'taskText'],
-  ['task_due_hours', 'taskDueHours'],
-]) {
-  const property = callOperator.properties[name];
-  const nullable = property.anyOf?.some((branch) => branch.type === 'null');
-  const value = property.anyOf?.find((branch) => branch.type !== 'null');
-  const runtime = canonical.properties[name].anyOf.find((branch) => branch.type !== 'null');
-  // refine считает Unicode; JSON Schema maxLength считает те же кодовые точки.
-  if (
-    !nullable ||
-    (name === 'task_text'
-      ? value?.type !== 'string' || value.maxLength !== 500
-      : value?.type !== runtime.type ||
-        value.minimum !== runtime.minimum ||
-        value.maximum !== runtime.maximum)
-  ) {
-    throw new Error(`CALL_OPERATOR_TASK_CONTRACT_DRIFT:${name}`);
-  }
-  canonical.properties[name] = {
-    ...property,
-    description: canonical.properties[name].description,
-  };
-  action.properties.callOperatorConfig.properties[alias] = {
-    ...property,
-    description: action.properties.callOperatorConfig.properties[alias].description,
-  };
-}
-action.properties.config = {
-  ...action.properties.config,
-  properties: canonical.properties,
-};
+syncCallOperatorTaskSchema(action, canonical, callOperator);
 
 // Публикуемые объявления берутся из исполняемой схемы: refine не обещает maxLength в JSON Schema.
 const target = new URL('../src/schemas/mcp-tools.json', import.meta.url);
@@ -73,7 +48,8 @@ for (const [name, field] of [
   const definition = toolDefinitions.find((entry) => entry.name === name);
   const schema = definition?.schema.shape?.[field];
   const tool = registry.tools.find((entry) => entry.name === name);
-  if (!schema || !tool?.inputSchema?.properties) throw new Error(`INSTAGRAM_SCHEMA_MISSING:${name}`);
+  if (!schema || !tool?.inputSchema?.properties)
+    throw new Error(`INSTAGRAM_SCHEMA_MISSING:${name}`);
   const published = z.toJSONSchema(schema, { target: 'draft-7', io: 'input' });
   delete published.$schema;
   tool.inputSchema.properties[field] = published;

package/scripts/sync-trigger-argument-schema.spec.mjs

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { triggerActionItemSchema } from '../src/tools/definitions/platform-setup.js';
+import { canonicalCallOperatorTaskSchema } from '../src/tools/definitions/call-operator-task.schema.js';
+import { syncCallOperatorTaskSchema } from './sync-trigger-task-schema.mjs';
+
+function schemas() {
+  const options = { target: 'draft-7', io: 'input' };
+  const action = z.toJSONSchema(triggerActionItemSchema, options);
+  const canonical = z.toJSONSchema(canonicalCallOperatorTaskSchema, options);
+  const api = structuredClone(canonical);
+  // Уточнение API, которого refine исполняемой схемы не объявляет в JSON Schema.
+  api.properties.task_text.anyOf.find((branch) => branch.type === 'string').maxLength = 500;
+  return { action, canonical, api };
+}
+
+describe('sync trigger CALL_OPERATOR schema', () => {
+  it.each(['plain', 'anyOf', 'oneOf'])('синхронизирует %s без потери null и описаний', (shape) => {
+    const { action, canonical, api } = schemas();
+    const generated = action.properties.callOperatorConfig;
+    const object = generated.anyOf.find((branch) => branch.type === 'object');
+    const originalObject = structuredClone(object);
+    const configBefore = structuredClone(action.properties.config);
+    const apiBefore = structuredClone(api);
+    const wrapper =
+      shape === 'plain'
+        ? object
+        : {
+            description: 'nullable config',
+            [shape]: [{ type: 'null' }, object],
+          };
+    action.properties.callOperatorConfig = wrapper;
+    syncCallOperatorTaskSchema(action, canonical, api);
+    expect(action.properties.callOperatorConfig).toBe(wrapper);
+    if (shape !== 'plain') {
+      expect(wrapper[shape]).toEqual([{ type: 'null' }, object]);
+      expect(wrapper.description).toBe('nullable config');
+    }
+    for (const [name, alias] of [
+      ['task_text', 'taskText'],
+      ['task_due_hours', 'taskDueHours'],
+    ]) {
+      expect(object.properties[alias]).toEqual({
+        ...api.properties[name],
+        description: originalObject.properties[alias].description,
+      });
+      expect(action.properties.config.properties[name]).toEqual(canonical.properties[name]);
+    }
+    expect({ ...object, properties: undefined }).toEqual({
+      ...originalObject,
+      properties: undefined,
+    });
+    expect({ ...action.properties.config, properties: undefined }).toEqual({
+      ...configBefore,
+      properties: undefined,
+    });
+    expect(api).toEqual(apiBefore);
+  });
+
+  it('синхронизирует фактическую nullable-схему Zod', () => {
+    const { action, canonical, api } = schemas();
+    syncCallOperatorTaskSchema(action, canonical, api);
+    expect(action.properties.callOperatorConfig.anyOf[1]).toEqual({
+      type: 'null',
+    });
+    expect(
+      action.properties.callOperatorConfig.anyOf[0].properties.taskText.anyOf[0].maxLength,
+    ).toBe(500);
+  });
+
+  it.each(['task_text', 'task_due_hours'])('сохраняет отказ на дрейф API: %s', (field) => {
+    const { action, canonical, api } = schemas();
+    const value = api.properties[field].anyOf.find((branch) => branch.type !== 'null');
+    if (field === 'task_text') value.maxLength = 501;
+    else value.maximum += 1;
+    expect(() => syncCallOperatorTaskSchema(action, canonical, api)).toThrow(
+      `CALL_OPERATOR_TASK_CONTRACT_DRIFT:${field}`,
+    );
+  });
+
+  it('не принимает неоднозначное объединение объектов', () => {
+    const { action, canonical, api } = schemas();
+    action.properties.callOperatorConfig.anyOf.push({
+      type: 'object',
+      properties: {},
+    });
+    expect(() => syncCallOperatorTaskSchema(action, canonical, api)).toThrow(
+      'CALL_OPERATOR_CONFIG_SCHEMA_UNEXPECTED',
+    );
+  });
+});

package/scripts/sync-trigger-event-schema.mjs

@@ -0,0 +1,20 @@
+// Точечный вариант sync-api-contracts: только схема и описание событийного триггера.
+// Сохраняет ручные ограничения и все прочие инструменты; типы и маршруты уже актуальны.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { z } from 'zod';
+import { toolDefinitions } from '../src/tools/definitions.ts';
+import { eventTriggerDescription } from '../src/tools/definitions/trigger-upsert.tool.ts';
+import { syncSchemaDescriptions } from './sync-schema-descriptions.mjs';
+
+const registryPath = new URL('../src/schemas/mcp-tools.json', import.meta.url);
+const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+const name = 'besales_trigger_upsert';
+const definition = toolDefinitions.find(tool => tool.name === name);
+const tool = registry.tools.find(tool => tool.name === name);
+if (!definition || !tool) throw new Error(`REGISTRY_TOOL_MISSING:${name}`);
+const derived = z.toJSONSchema(definition.schema, { io: 'input', unrepresentable: 'any' });
+if (!derived.properties?.trigger) throw new Error('EVENT_TRIGGER_SCHEMA_MISSING');
+tool.inputSchema.properties.trigger = derived.properties.trigger;
+syncSchemaDescriptions(tool.inputSchema, derived);
+if (!tool.description.includes(eventTriggerDescription)) tool.description += ' ' + eventTriggerDescription;
+writeFileSync(registryPath, JSON.stringify(registry, null, 2) + '\n');