@besales/mcp 0.48.0 → 1.0.0-beta.4

package/docs/response-size-budget.md

@@ -58,7 +58,7 @@
 
 Ресурсы (справочники, отдаются целиком одним чтением): 37 файлов, медиана 4 КБ,
 максимум **104 836** байт — принципы промптинга. Инструкции сервера, уходящие при каждом
-подключении, после выноса подробностей в resources/help — 5 112 байт (3 278 символов).
+подключении, после выноса подробностей в resources/help — 5 118 байт (3 277 символов).
 
 ## Три класса и потолки
 
@@ -95,18 +95,18 @@
 **Порог отказа — 256 КБ.** Он выше наблюдаемого максимума работающих снимков (77,6 КБ),
 чтобы предохранитель не гасил живые сценарии.
 
-## Что теперь лечится на стороне API
+## Что потолком не лечится
 
 **Снимок канала на 8 МБ.** Это не выброс, а штатный ответ для воркспейса с сорока
 агентами на одном канале. 72 % веса — системные промпты агентов, которые в этом сценарии
 не нужны вовсе: их читают отдельными инструментами промптов. Но даже без промптов
 остаётся 2,2 МБ триггеров.
 
-Поэтому `besales_platform_context_get` теперь принимает `sections`: для выбора достаточно
-`platform,agent_summaries,readiness`, а router/behavior/follow_up/pipeline_settings читаются
-отдельно. `besales_agent_list` отдаёт компактные summaries с поиском и пагинацией. Полный
-`compiledPrompt` появляется только в явном `besales_agent_get` или секции `agents_full`.
-Замещающая правка по-прежнему требует полного снимка относящейся к ней секции.
+Ни один потолок здесь не помогает: обрезать нельзя (снимок для замещающей записи),
+отказать — значит закрыть единственный документированный путь безопасной правки триггера.
+Лечится только сужением на стороне бэкенда: снимок должен уметь отдавать **одного агента**,
+а системный промпт — только по явному запросу. До этой правки правка триггеров на крупном
+канале остаётся тем, чем была, — работой в обход моста.
 
 ## Как это включается
 
@@ -128,6 +128,9 @@
 мутацию нельзя. У чтения ошибка постобработки остаётся обычной ошибкой и допускает новый
 вызов.
 
+Под тем же флагом — обрезка **текста ошибки** и обрезка **тела ресурса**. Обе меняют форму
+того, что видит вызывающий, и потому ждут включения наравне с остальным конвертом.
+
 Политика объявляется у самого инструмента:
 
 - `neverTruncate` — обрезать нельзя, при превышении отказ;
@@ -143,6 +146,193 @@
 Маркеры в ответе начинаются с `_mcp`: у бэкенда есть собственные признаки усечения с другим
 смыслом, и совпадение имён их бы перемешало.
 
+## Списочные инструменты без постраничной выдачи — поимённо
+
+Пересчитано по контракту: из 29 списочных инструментов ручки сужения есть у десяти,
+у **девятнадцати** нет ни одной.
+
+| Инструмент | Адрес |
+|---|---|
+| `agent_list` | `/channels/:id/agents` |
+| `broadcast_cohorts_list` | `/workspaces/:id/broadcast-analytics/cohorts` |
+| `broadcast_mailing_variant_list` | `/workspaces/:id/broadcast-mailing-variants` |
+| `crm_list` | `/workspaces/:id/crm-connections` |
+| `crm_operator_list` | `/crm-connections/:id/operators` |
+| `crm_pipeline_list` | `/crm-connections/:id/pipelines` |
+| `crm_pipeline_status_list` | `/crm-connections/:id/pipelines/:id/statuses` |
+| `datasource_catalog_roles` | `/workspaces/:id/data-sources/:id/catalog-roles` |
+| `datasource_catalogs` | `/workspaces/:id/data-sources/:id/catalogs` |
+| `datasource_list` | `/workspaces/:id/data-sources` |
+| `feedback_sheet_list` | `/agents/:id/feedback-sheets` |
+| `followup_reactions` | `/channels/:id/followup-sequences/reactions` |
+| `followup_sequence_list` | `/channels/:id/followup-sequences` |
+| `getcourse_departments_list` | `/channels/:id/getcourse/departments` |
+| `icp_scenarios_list` | `/icp/:id/scenarios` |
+| `knowledge_space_list` | `/workspaces/:workspaceId/knowledge-spaces` |
+| `model_catalog_list` | `/model-catalog` |
+| `variable_list` | `/workspaces/:id/variables` |
+| `wazzup_templates_list` | `/workspaces/:id/wazzup-waves/templates/:id` |
+
+Поиск по вопросам-ответам сюда не входит: у него уже есть `top_k`, и вторая ручка на ту же
+ось только запутала бы.
+
+### Четыре списка знаний: постраничность была фальшивой
+
+⛔ **Исправлено.** Ручки `page`/`limit` у документов, вопросов-ответов, таблиц и сайтов резали
+ответ **в самом мосту**, а по сети всё равно приезжало всё. Хуже того, у нарезки было
+**умолчание в двадцать строк**: вызов без аргументов молча возвращал первые двадцать источников
+— ни признака усечения, ни общего числа. Увидеть подмену было нечем.
+
+Теперь `limit` и `cursor` уходят на сервер, нарезка в мосту удалена. Номер страницы заменён
+курсором: между страницами источники создают и удаляют, и смещение пропускало бы строку или
+показывало бы её дважды. Расхождение с отгруженной копией объявлено в реестре отставания.
+
+⚠️ **Умолчание у размера страницы здесь ОСТАВЛЕНО — и это не противоречие правилу.** Источники
+знаний это содержимое, а не конфигурация: их у пространства бывают тысячи, и отдавать всё по
+умолчанию значило бы менять поведение в худшую сторону. Предел стоял и раньше (500 строк на
+стороне сервера), но стоял МОЛЧА — ровно по границе, из-за чего продолжение было неотличимо от
+конца списка. Новое здесь одно: сервер берёт строку сверх предела и возвращает курсор, поэтому
+«показано не всё» стало видно.
+
+### Разбор по стороне работы (сверено с контрактом besales-api)
+
+**Сделано — три списка.**
+
+`variable_list` — сервер УЖЕ умел страницы (`cursor`, `limit`, предел 200), а мост их не
+пробрасывал: перечень молча обрывался на пятидесятой строке по серверному умолчанию, и дочитать
+было нечем. Ручки добавлены, вызов без них при неполной выдаче отказывает.
+
+`agent_list` — страницы построены на бэкенде (тот же ключевой курсор). ⚠️ Здесь исправлялась
+ДРУГАЯ болезнь: сервер не резал ничего, но перечень парка не помещался в потолок ответа, и
+политика `neverTruncate` отказывала **без выхода** — сузить запрос было нечем. Теперь у отказа
+есть выход. Умолчания у `limit` нет ни на одной стороне: без него перечень приходит целиком,
+как и раньше, — иначе раскатка правки уехала бы на ЧАСТЬ парка при успешном отчёте.
+
+⚠️ Урок этого случая шире одного инструмента: **политика `neverTruncate` стережёт обрезку
+МОСТОМ и слепа к обрезке СЕРВЕРОМ.** Пятьдесят строк не дотягивают до потолка размера никогда,
+поэтому предохранитель не срабатывал ни разу. Для остальных списков проверять надо не размер
+ответа, а наличие серверного предела.
+
+`icp_scenarios_list` — единственный, у кого отказ был **замерен**: 119 КБ голым массивом против
+потолка в 64 КБ, то есть инструмент отказывал уже сегодня и добрать отрезанное было нечем.
+
+`crm_pipeline_list`, `crm_pipeline_status_list`, `followup_sequence_list` — по цене ошибки:
+недостающая воронка сужает охват задачи, недостающая стадия даёт недостижимое правило
+маршрутизации, а замещающая запись цепочки меняет её конфигурацию целиком.
+
+⭐ **Стадии и воронки упорядочены НОМЕРОМ, а не датой**, и переупорядочить их нельзя: порядок
+стадий — сам по себе бизнес-смысл, его задаёт CRM. У них свой курсор («номер + идентификатор»)
+рядом с общим — обобщать общий было нельзя, это поменяло бы поведение уже работающих читателей.
+Полезная нагрузка у двух курсоров разной формы намеренно: курсор одного списка, поданный в
+другой, разбирается в ничто, а не в правдоподобный мусор.
+
+### У отказа обязан быть выход — и это теперь проверяется
+
+Политика «не обрезать» превращает переполнение в отказ. Это верно ровно до тех пор, пока
+вызывающему есть чем сузить запрос; иначе инструмент отвечает «слишком много» на каждый вызов и
+не говорит, что делать, — тупик, из которого не выбраться ни повтором, ни другими аргументами.
+
+Выходом считается любое из: ручка сужения в схеме, объявленная подсказка «чем сузить», перечень
+выбрасываемых путей, собственный потолок инструмента. Инвариант держит тест, читающий **разбор**
+схемы, а не текст исходника: ручной обход регуляркой ошибается на границе окна и дважды подряд
+дал неверный ответ — сначала объявил тупиком `crm_list`, у которого политики нет вовсе, потом
+`broadcast_cohorts_list`, у которого подсказка есть с самого начала.
+
+Настоящий тупик был **один** на весь мост: снимок перезаписей переменных агента. Сузить его
+нечем по построению — набор неделим, он вход замещающей записи, — поэтому у него свой потолок и
+сказанное вслух следствие: не помещается, значит безопасно обновить агента невозможно.
+
+### Чем § 3.3 закрыт и что осталось
+
+**Тихого усечения не осталось ни одного — это проверено, а не предположено.** Оба найденных
+случая исправлены: перечень переменных резал СЕРВЕР (50 строк), четыре списка знаний резал МОСТ
+(20 строк). У остальных двенадцати списков запросы просмотрены поимённо — **предела в запросе нет
+ни у одного**, то есть скрывать им нечего.
+
+Осталось двенадцать списков без ручек сужения: `crm_list`, `crm_operator_list`,
+`datasource_catalog_roles`, `datasource_catalogs`, `datasource_list`, `feedback_sheet_list`,
+`getcourse_departments_list`, `model_catalog_list`, `wazzup_templates_list`,
+`knowledge_space_list`, `broadcast_mailing_variant_list`, `broadcast_cohorts_list`.
+
+⚠️ **Это другой класс работы.** Они отдают всё; если ответ не помещается, конверт обрезает его
+**с пометкой** `_mcpTruncated` — усечение видно и вызывающему, и человеку. То есть здесь речь про
+экономию контекста, а не про тихую ложь. Половина из них к тому же мала по природе (отделы,
+шаблоны, подключения CRM, каталог моделей), а у когорт рассылок есть девять фильтров и
+подсказка, чем сузить.
+
+Образец, если браться: общий keyset-курсор (`shared/utils/keyset-cursor`), `take: limit + 1`,
+курсор из последней отданной строки — отработан шестикратно и повторяется механически.
+
+**Сузить можно уже сегодня, страниц нет (5):** `broadcast_cohorts_list`, `followup_reactions`,
+`followup_sequence_list`, `broadcast_mailing_variant_list`, `knowledge_space_list` — у них богатые
+фильтры; постраничная выдача им нужна, но обходной путь у вызывающего есть.
+
+Правила для будущей работы: `limit` только необязательный и БЕЗ значения по умолчанию
+(усечённый список конфигурации — не «неполный ответ», а тихая порча настройки); ответ обязан
+нести общее число и признак «есть ещё»; курсор по устойчивому ключу, а не по смещению —
+между страницами сущности создают и архивируют; параметр кладётся в строку запроса, потому
+что у всех двадцати метод GET, а тело GET сервер игнорирует.
+
+## Чего потолок не лечит: эхо правки
+
+Правка триггера возвращала триггер ЦЕЛИКОМ — со всеми шагами и условиями, то есть копию только
+что отправленного. Потолок здесь бесполезен: один такой ответ до него не достаёт. Расход
+возникает от повторения — на канале триггеры правят десятками подряд.
+
+Лечится не потолком, а **проекцией ответа**: наружу уходят все скалярные поля (они дёшевы, и
+среди них есть решённые СЕРВЕРОМ) и числа вместо двух тяжёлых массивов. Проекция обязана быть
+тотальной: она выполняется ПОСЛЕ состоявшейся записи, и исключение в ней стало бы приглашением
+повторить мутацию — незнакомая форма проходит насквозь.
+
+Тестов два и они про разное: сама проекция и её **проводка** в инструмент. Без второго функция
+могла бы быть написана и не подключена — ровно то состояние, в котором этот пункт и пролежал.
+
+## Текст промпта в шагах правки
+
+Промпт доходит до 80 000 символов — до ~160 КБ кириллицей. Шаги правки возвращали его снова и
+снова: создание черновика, каждое применение операций, коммит. За один сеанс правки один и тот
+же текст прилетал вызывающему по нескольку раз.
+
+⛔ **Выбросить его везде нельзя, и это не осторожность, а механика.** Операции адресуются
+точными якорями, а якоря берут из текста; без текста доля непопавших операций становится 100 %.
+Поэтому:
+
+- **чтение черновика отдаёт текст ВСЕГДА** — это единственный путь получить его целиком, и
+  флага у него нет намеренно;
+- **создание черновика и применение операций** по умолчанию отдают отпечаток и длину, а текст —
+  по флагу `include_prompt_text`. Изменился ли текст, видно по отпечатку;
+- **коммит** возвращал текст ДВАЖДЫ — в черновике и в новой версии. Копия из черновика заменена
+  отпечатком; авторитетна версия, именно она уехала агенту. ⚠️ Если копии почему-то разошлись,
+  не убирается ни одна: расхождение — факт, который вызывающий обязан увидеть.
+
+Длина считается в символах: в них же задан боевой предел промпта, с ним вызывающий и сравнивает.
+
+## Соседний слой: аннотации и гейты
+
+Потолок отвечает на вопрос «сколько», аннотации — на вопрос «что инструмент делает».
+Признак объявляется полем `sideEffect` (`none` / `write` / `spend`) у каждого определения
+и превращается в четыре подсказки хосту: только чтение, разрушительность, идемпотентность,
+выход во внешние системы. Ослабление любой из них — отдельное явное объявление
+(`reversible`, `idempotent`, `closedWorld`), умолчание всегда худшее.
+
+⚠️ Аннотация — подсказка, и автоодобряющий хост вправе ей не поверить. Там, где цена ошибки
+велика, стоит `explicit_confirmation` — условие входа, которое обойти нельзя.
+
+### Подтверждение: гейт моста, а не поле запроса
+
+⛔ **`explicit_confirmation` НЕ уходит на сервер и уходить не должен.** У сервера включены
+`whitelist + forbidNonWhitelisted`: поле, которого нет в его DTO, даёт отказ 400 на **каждом**
+вызове. Ни один из адресов, за которыми стоят гейты, такого поля не принимает. Смысл гейта
+другой — заставить вызывающего принять решение осознанно, а не выполнить операцию по умолчанию;
+авторизацию проверяет сервер своими средствами, и это отдельный слой.
+
+⛔ **Опубликованная схема обязана пришпиливать значение к `true`** (`const: true`, равнозначная
+форма — `enum: [true]`). Объявив просто `boolean`, мост СООБЩАЕТ вызывающему, что `false`
+допустим; разбор его отвергнет, и отказ будет выглядеть капризом инструмента, а не невыполненным
+условием. Схема, которая **проверяет** вызов (Zod в определении), и схема, которая
+**публикуется** (`mcp-tools.json`), — разные файлы: разойтись они могут молча, поэтому согласие
+между ними проверяется тестом, выводящим ожидание разбором, а не чтением формы.
+
 ## Когда пересматривать
 
 Если предохранитель начнёт срабатывать на штатных ответах — **поднимать потолок, а не

package/docs/secret-read-boundary.md

@@ -0,0 +1,102 @@
+# Чтение подключений и секретных настроек
+
+Мост читает опубликованные маршруты API с ключом выбранного пространства. Значения SECRET,
+учётные данные подключений и исполняемые настройки шагов проецирует сервер до HTTP-ответа.
+Перед формированием текста и `structuredContent` мост дополнительно применяет
+`src/utils/secret-read-boundary.ts#projectBridgeSecretRead`. Проекция обходит объекты,
+массивы и свободные карты, скрывает значения секретных ключей, SECRET-переменные,
+конфиги шагов с серверным признаком `configReadable: false` и снимки аудита.
+Формы уже спроецированных сервером шагов без метаданных редактирования сохраняются;
+повторное закрытие всей настройки потеряло бы безопасные `method`, `timeout_ms` и ссылки
+на переменные. Ответы этих читателей проверяет совместный серверный договор.
+Маски и ссылки на переменные сохраняются. Проекция действует при обоих режимах
+конверта; цикл или превышение бюджета дают существующую безопасную квитанцию.
+Каждый строковый лист дополнительно проверяется по NFKC-представлению на сигнатуры
+provider key, JWT, bot token, Bearer и private key, включая позиции имён колонок.
+При совпадении исходное значение маскируется до формирования обоих конвертов;
+безопасные значения сохраняются без нормализации выдаваемого текста.
+В позициях имён колонок действует копия серверной `dataSourceColumnNameDecision`:
+1–512 символов, ASCII-буквы/цифры/`_ . -` и русские `А-Я а-я Ё ё`, непустые части
+через точку. Смешение письменностей запрещено, кроме служебных `Catalog_` и `_Key`
+из полного штатного словаря. Проверка исходной строки предшествует сигнатурам;
+Unicode-нормализация не превращает невалидное имя в допустимое. Невалидное имя
+маскируется до обоих конвертов. Служебные серверные маски сохраняются.
+Общая таблица `columnNames` передаётся в подтверждённом серверном снимке; unit-тест
+моста требует идентичных решений, включая длину, все найденные обходы, Cf и гомоглифы.
+
+Вместо секретов доступны имена переменных, маски, состояние подключения и признаки безопасного
+редактирования. Секретные адреса CRM выдаются человеку через браузерную страницу; карточки
+подключений их не содержат. Ошибка области или права остаётся ошибкой инструмента.
+
+## Совместная проверка API и моста
+
+`test/bridge-secret-read-contract.ts` в API получает настоящие HTTP-ответы приложения с PostgreSQL
+и ключами MCP: владельца, чужого пространства и без прав. Исходные данные содержат исторические
+секреты шагов, шифрованную SECRET-переменную, историческую перезапись и зашифрованные ключи CRM.
+Проверка требует отсутствия каждого исходного значения и сохранения безопасных полей.
+Свободные метаданные источника проверяются после настоящей записи через HTTP и после
+штатного переноса в PostgreSQL; отдельно подкладывается историческая строка с паролем
+в объекте внутри массива. Новая запись секретов запрещена; перенос маскирует сигнатуры
+и запрещает остаточные структурные секреты. Историческое чтение сохраняет безопасные
+соседи и скрывает значение. Правка триггера проверяется двумя отдельными сценариями: допустимое определение возвращает
+успех, а исторические открытые HTTP-ключи получают безопасный отказ без передачи значений.
+
+Для 1С договор сверяет полные метаданные обычного маппинга `Ref_Key`/`Code` и
+штатного словаря обогащения после записи и переноса. Реальные HTTP-ответы записи
+через ключ моста также входят в снимок: два допустимых назначения и все отказы таблицы решений
+для секретных метаданных. Проверка реестра моста требует неизменного тела POST и
+сохранения безопасных метаданных в тексте и `structuredContent` при обоих режимах
+конверта; вложенный `password` продолжает маскироваться общей проекцией.
+Невалидные имена и сигнатуры в позициях имён запрещаются на записи и пропускаются
+штатным переносом с `DATA_SOURCE_METADATA_UNSAFE`. Исторические строки возвращают
+маску, безопасные соседи сохраняются. Вне позиций имён сигнатуры маскируются при переносе.
+
+После успешных assertions тест печатает `PRSM_BRIDGE_CONTRACT=<base64 JSON>`. Этот снимок
+переносится без изменения тел командой
+`node scripts/import-secret-read-contract.mjs <API_ROOT> <VREQ_LOG>`
+в `src/tools/__fixtures__/secret-read-contract.json` и прогоняется
+`yarn test src/tools/secret-read-contract.spec.ts`. Тест использует настоящий реестр и HTTP-клиент,
+сверяет метод, адрес, тело запроса и итоговый ответ в обоих режимах конверта. Снимок содержит
+коммит API и SHA-256 серверных читателей, писателя, переноса и проверочных фикстур.
+Импорт сверяет родство Git-метки канала с локальным коммитом и хэши всех этих файлов;
+каждый runtime-файл, изменённый как между коммитами, так и в рабочем дереве, допускается
+только при наличии его проверенного хэша в снимке. Локальный коммит сохраняется отдельно
+как `verifiedApiRevision`; исходная метка канала `apiRevision` не подменяется. Это позволяет проверить незакоммиченный
+дифф при режиме Git только для чтения. При расхождении импорт отказывает:
+результат относится к этой паре исходников, а не к будущей версии API.
+
+Обновлять снимок вручную нельзя. При изменении серверного читателя требуется новый серверный
+прогон и перенос его вывода. Самостоятельный тест моста проверяет обработку зафиксированного
+договора; он не доказывает, что произвольный другой сервер скрывает секреты. Добавление нового
+читателя требует серверного теста с секретом в его исходных данных и проверки итогового MCP-ответа.
+
+## Полная опись
+
+Канон — `besales-api/test/bridge-secret-read-inventory.json`, перенесённый в снимок
+верификатором. В нём поимённо перечислены все инструменты `mcp-tools.json`, включая
+setup/init/status/rotation, 1С, CRM, внешние API и их ключи, каналы, переменные,
+исполняемые настройки и остальные опубликованные объекты. Безопасных исключений из
+общей проекции нет: домен описывает читателя, а не разрешение выдать секрет.
+Каждая группа называет файл определения; общие `projection` и `check` задают
+исполняемую проекцию и проверку для каждого инструмента этой группы.
+
+`src/tools/secret-read-inventory.spec.ts` сравнивает полные множества описи,
+`mcp-tools.json` и рабочего реестра, проверяет ссылки и для каждой строки пропускает
+секретоносный ответ через общую сериализацию с выключенным и включённым конвертом.
+Добавление любого нового инструмента без строки в описи красит сторожа, независимо
+от имени, HTTP-метода и класса побочного эффекта. Отдельные инструменты управления
+исходящими вебхуками и ключами рабочего пространства в текущем `mcp-tools.json`
+отсутствуют; выдачу ключей внешнего API покрывает группа `external-api-keys`.
+Это полная опись и проверка общей проекции, а не утверждение о живом HTTP-прогоне
+каждого из инструментов: реальные HTTP-тела покрывает совместный договор.
+
+Дополнительно для каждого из 55 читателей подключений, CRM, 1С, внешнего API,
+переменных и локальных подключений к пространству тест вызывает настоящий
+registry/ApiClient с корректным входом и управляемым HTTP-транспортом, возвращающим
+секретоносную вложенную карту. В обоих режимах конверта проверяются состоявшийся
+запрос, успешный ответ и отсутствие секрета без квитанции сбоя форматирования.
+
+`node scripts/verify-secret-read-mutants.mjs` снимает общую проекцию, обход массивов
+и добавляет инструмент вне описи; каждый случай должен упасть по assertion, а файлы
+восстанавливаются с проверкой SHA-256. `node scripts/verify-secret-read-import.mjs
+<API_ROOT> <VREQ_LOG>` проверяет пять отказов импортера и неизменность снимка.

package/docs/task-state.md

@@ -1,5 +1,8 @@
 # Состояние длительной задачи
 
+В [сетевом режиме](modules/network-mode.md) локальные `besales_task_*` недоступны:
+они возвращают отказ до обращения к файловому хранилищу. Контекст задачи хранит MCP-клиент.
+
 ## Решение
 
 Состоянием владеет локальный `besales-mcp`. Оно хранится в
@@ -54,5 +57,7 @@ browser setup state и исходные диалоги сюда не сохра
 Автоматический повтор мутации запрещён. Если status-tool или нужный scope недоступен, исход остаётся
 неразрешённым и это фиксируется в задаче.
 
-Setup URL, OAuth ticket и состояние отдельного async job остаются своими сущностями. Они не
-заменяют общую задачу и не копируются в неё вместе с секретами.
+Setup ref допускается в `object_refs`/`pending_operations` для продолжения polling.
+Адрес страницы настройки, OAuth-входа, загрузки или раскрытия секрета отвергается
+при создании и обновлении задачи и не записывается в `tasks-v1.json`.
+Сам мастер и отдельный async job остаются своими сущностями и не заменяют общую задачу.

package/docs/telegram-personal-management.md

@@ -0,0 +1,50 @@
+# Личные номера 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` |
+
+У инструментов канала обязателен `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 и []
+передаются буквально. Допустимые рабочие диапазоны настроек проверяет ядро.
+
+Ограничения, ручная жалоба и чтение её исхода описаны в
+[документе апелляции](telegram-personal-restrictions.md). Перед жалобой покажи человеку
+номер и текст, получи явное согласие и только затем передай `explicit_confirmation:true`.
+Жалоба необратима, не чаще раза в сутки на номер; автоматическая подача выключена.
+
+Проверки схем, запросов, профилей, строгого ввода, описаний и сохранения ответа находятся
+в `telegram-personal-management.spec.ts` и `telegram-personal-restrictions.spec.ts`.
+`scripts/telegram-personal-confirmation-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/docs/telegram-pool-policy.md

@@ -0,0 +1,19 @@
+# Поведение личного Telegram при потере номера
+
+Единственный инструмент — `besales_platform_telegram_personal_pool_policy`.
+Он работает через канал ядра и требует `manage:channels`.
+
+Для чтения передай `platform_id` и `operation:get`. Для смены сначала прочитай настройку,
+согласуй её с человеком и передай `operation:set`, `rebind_policy:rebind|escalate` и
+стабильный `idempotency_key` (1–200 видимых ASCII-символов).
+
+`rebind` выбирает другой доступный номер для автоматического ответа. `escalate` передаёт
+разговор оператору; оператор сможет ответить с другого доступного номера. Дожимы и
+напоминания при обеих настройках могут уходить с другого номера. Ответ ядра содержит
+локализованные варианты `options` и цену смены `consequence`; показывай их человеку.
+После записи приходит `previousRebindPolicy` из квитанции фермы.
+
+Чтение и запись объединены, поэтому инструмент объявлен изменяющим и входит в профиль
+`platform`, а не `readonly`. Смена повторяется тем же ключом: другое значение с прежним
+ключом отклоняется. При неизвестном исходе сначала проверь настройку; автоматически
+выдавать новый ключ нельзя. Прямых вызовов фермы и записи в Telegram нет.

package/docs/tool-effects.md

@@ -8,8 +8,8 @@
 - `write` — изменение состояния Besales, внешней CRM или локальной MCP-сессии;
 - `spend` — операция может отправить сообщение, вызвать модель, индексацию или потратить квоту.
 
-На 11 сентября 2026 года активный каталог из 231 инструмента содержит 96 `none`, 116 `write`
-и 19 `spend`. Эти числа проверяются по живым definitions, а не поддерживаются отдельным списком.
+Числа по группам здесь не фиксируются: они дрейфуют с каждым инструментом. Актуальные считаются
+по живым определениям (`toolDefinitions` из `src/tools/definitions.ts`), отдельного списка нет.
 
 HTTP-метод не является источником эффекта. Например, `besales_prompt_diff`,
 `besales_prompt_lint` и `besales_knowledge_qa_search` читают через POST. В то же время
@@ -22,22 +22,28 @@ HTTP-метод не является источником эффекта. На
 в четыре стандартные подсказки MCP:
 
 - `readOnlyHint=true` только для `sideEffect=none`;
-- `destructiveHint=false` для чтения и доказуемо обратимых записей;
-- `idempotentHint=true` только при безусловной идемпотентности с теми же аргументами;
-- `openWorldHint=false` только если операция гарантированно не выходит за Besales.
+- `destructiveHint=false` для чтения и доказуемо обратимых записей (`reversible`), иначе `true`;
+- `idempotentHint=true` только при безусловной идемпотентности с теми же аргументами
+  (`idempotent`);
+- `openWorldHint=false` только если операция гарантированно не выходит за Besales
+  (`closedWorld`).
 
-Неизвестное свойство трактуется консервативно. Аннотации помогают хосту показать характер
-операции, но не заменяют API scopes, tenant/workspace проверки и обязательный
-`explicit_confirmation` у опасных действий.
+Неизвестное свойство трактуется консервативно: умолчание — худший случай, а не «неизвестно».
+Аннотации помогают хосту показать характер операции, но не заменяют API scopes, tenant/workspace
+проверки и обязательный `explicit_confirmation` у опасных действий.
 
 `explicit_confirmation` является гейтом самого MCP и не передаётся в API DTO, если endpoint
 его не принимает. Опубликованная JSON Schema использует `const: true`, а runtime-схема —
-`z.literal(true)`: вызывающий видит ровно то условие, которое затем проверяется.
+`z.literal(true)`: вызывающий видит ровно то условие, которое затем проверяется. Расхождение
+двух объявлений ловит `src/tools/confirmation-contract.spec.ts`.
 
 Поле `Tool.title` строится из первой русской фразы локализованного описания, ограничено 80
 символами и передаётся через `tools/list`. Это подпись для интерфейса; стабильным API-ключом
 операции остаётся `name`.
 
+Признак «ответ несёт данные клиентов» (`carriesCustomerData`) — отдельная ось, не эффект:
+[customer-data.md](customer-data.md).
+
 ## Проверка
 
 `src/tools/annotations.spec.ts` требует эффект у каждого определения, полный набор четырёх