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

package/docs/async-operation-lifecycle.md

@@ -2,8 +2,9 @@
 
 Фоновая операция MCP считается полной только тогда, когда у её стартового инструмента есть
 read-only status-инструмент. Стартовый ответ не является доказательством завершения. При сетевом
-обрыве нельзя повторять start вслепую: сначала вызывается status, указанный в
-`verifyWithToolName` или выведенный из имени.
+обрыве сначала вызывается доступное чтение исхода по исходному ключу. Если для status нужен
+ещё не полученный идентификатор, запуск с `request_key` повторяется с тем же ключом и тем же
+намерением: вернётся та же операция. Запуск без ключа вслепую повторять нельзя.
 
 ## Канон операций
 
@@ -41,6 +42,16 @@ read-only status-инструмент. Стартовый ответ не явл
 `besales_improvement_aggregate_start`) status читает исход по исходному ключу. Исход `UNKNOWN` не
 разрешает новый платный запуск автоматически: сначала выясняется, был ли первый принят.
 
+У `besales_icp_import_dialogues` потерянный ответ сначала проверяется через
+`besales_icp_import_start_result` с теми же `icp_id` и `request_key`. Если исход неизвестен
+(`NOT_FOUND_UNKNOWN`), повторяется исходное намерение с тем же ключом.
+
+У `besales_sandbox_run_start` чтение исхода по ключу пока не опубликовано в MCP.
+При таймауте или 5xx повторите вызов с тем же `request_key` и тем же намерением: вернётся
+тот же прогон. Только после получения `run_id` проверяйте `besales_sandbox_run_get`.
+Новый осознанный прогон запускайте без `request_key` либо с новым UUID: прежний ключ вернёт
+старый прогон, а при смене намерения — `START_KEY_CONFLICT`.
+
 ## Синхронные похожие имена
 
 `besales_prompt_patch_start` синхронно создаёт draft; его дальнейший жизненный цикл —

package/docs/failure-semantics.md

@@ -21,7 +21,10 @@
 
 Признак неоднозначности выводится из уже объявленного у инструмента: `sideEffect !== 'none'`
 и не объявлена идемпотентность. Тогда на **5xx** и на **обрыв связи** уходит ответ вида
-`OUTCOME_UNKNOWN` — без совета повторить и с указанием, чем свериться.
+`OUTCOME_UNKNOWN` — с указанием, чем свериться. Для запуска песочницы после потери ответа
+повтори `besales_sandbox_run_start` с теми же аргументами и тем же `request_key` из
+`requestIdentity`: сервер вернёт тот же прогон. Новый ключ не создавай. Для остальных
+неидемпотентных операций повтор запрещён до сверки состояния.
 
 ⚠️ **Идемпотентность объявляется явно, умолчание — худшее.** Правило «все `*_upsert`
 идемпотентны» неверно: без идентификатора они уходят в создание.
@@ -44,12 +47,22 @@
 «операция → проверка» отстала бы от первого же нового асинхронного инструмента, и он остался
 бы без указания ровно там, где цена ошибки максимальна.
 
-Пару, которую вывести нельзя (`besales_icp_import_dialogues` → `besales_icp_import_status`,
+Пару, которую вывести нельзя (`besales_icp_import_dialogues` → `besales_icp_import_start_result`,
 `besales_model_comparison_run_start` → `besales_model_comparison_get`, …), объявляет поле
 `verifyWithToolName` у определения; объявленное перекрывает выведенное. Тесты держат два
 инварианта: объявленное имя существует, и инструмент проверки сам ничего не меняет — иначе
 совет «сверьтесь» вносил бы новую побочку поверх неизвестного исхода.
 
+Для запусков с `request_key` HTTP-ошибки возвращают отправленный ключ из разобранного входа
+в тексте и в `error.requestIdentity.request_key`, в том числе UUID, сгенерированный мостом для
+песочницы. Аварийные квитанции при превышении размера, сбое сериализации или постобработки
+сохраняют `request_key` рядом с идентификаторами результата.
+При `OUTCOME_UNKNOWN` инструкция разрешает повторить то же намерение с тем же ключом:
+вернётся та же операция; новый ключ означает новую платную операцию. Для ICP сначала вызывается
+`besales_icp_import_start_result`; если исход неизвестен, допускается повтор с прежним ключом.
+У песочницы без `run_id` повтор с тем же ключом восстанавливает прогон, затем доступен
+`besales_sandbox_run_get`. Исход неизвестен до ответа API, автоматического повтора нет.
+
 Если проверки нет ни выведенной, ни объявленной, текст всё равно не советует повтор: он просит
 свериться состоянием на стороне Besales.
 

package/docs/help-navigation.md

@@ -14,6 +14,8 @@
 изменение маршрутизации, запуск GetCourse-волны и финализация промпта находятся обычным русским
 запросом без знания технического имени.
 
+Запрос «создать агента промпт написать» находит создание агента.
+
 `besales_help_get({uri})` возвращает индекс. Параметр `section` отдаёт один раздел, `full=true` —
 весь документ. Ответы содержат version/source/complete; неоднозначный раздел не выбирается молча.
 

package/docs/secret-read-boundary.md

@@ -72,6 +72,13 @@ Unicode-нормализация не превращает невалидное
 
 ## Полная опись
 
+Параметр `stored_file_id` существующего `besales_platform_telegram_personal_profile_bulk`
+учтён отдельно в `secret-read-inventory-additions.json#parameterSurfaces`. Читатель остаётся
+`telegram-personal-profile.ts` (домен `channels-setup`): он возвращает квитанцию задания,
+не байты файла, URL S3 или секреты Telegram. ID файла — метаданные библиотеки; доступ
+повторно проверяет ядро. `photo-only registry response` проверяет настоящий реестр с одним
+фото и секретоносным ответом в обоих режимах конверта. Полный снимок API не переписывается.
+
 Канон — `besales-api/test/bridge-secret-read-inventory.json`, перенесённый в снимок
 верификатором. В нём поимённо перечислены все инструменты `mcp-tools.json`, включая
 setup/init/status/rotation, 1С, CRM, внешние API и их ключи, каналы, переменные,

package/docs/telegram-personal-management.md

@@ -4,15 +4,15 @@
 только к ядру 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` |
+| Инструмент `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` можно не передавать при выбранной рабочей области.
@@ -54,18 +54,59 @@ 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 как лишнее.
+| Вход                         | В теле ядра                         | Правило                                                                                    |
+| ---------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------ |
+| `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` снимает дату                                                 |
+| `stored_file_id`             | `patch.avatar`                      | одно фото библиотеки для всех выбранных номеров, UUID v4; статичный JPEG/PNG/WebP до 5 МиБ |
+| `usernames`                  | `usernames[{accountId, username}]`  | ники по номерам; `account_ids` и `all` не передаются                                       |
+| `username_base`              | `usernameBase`                      | основа ника для номеров из `account_ids` или `all`                                         |
+| `idempotency_key`            | заголовок `x-idempotency-key`       | обязателен: 1–200 видимых ASCII-знаков без пробелов                                        |
+
+`stored_file_id` необязателен: прежняя форма вызова сохранена. Пропуск сохраняет фото;
+`null`, URL и псевдонимы `avatar`/`avatar_file_id` отвергаются до HTTP.
+
+### Лицо канала: фото, имя, ник, описание и дата рождения
+
+1. В рабочей области канала вызови
+   `besales_file_upload_request({name:"Фото канала", file_type:"IMAGE", source:"USER_UPLOAD"})`,
+   без `owner_kind`/`owner_id`. Тип укажи явно: по умолчанию загрузчик создаёт DOCUMENT,
+   который не подходит для фото профиля. Человек загружает
+   фото по полученной ссылке; затем читай `besales_file_upload_status` с `upload_ref`
+   до `status:READY` и возьми `stored_file_id`. Файл должен быть доступен в этой области.
+2. Покажи список номеров и новые значения; при смене ников получи ответ «делать?».
+   Вызови `besales_platform_telegram_personal_profile_bulk` одним запросом:
+
+   ```json
+   {
+     "channel_id": "23000000-0000-4000-8000-000000000001",
+     "all": true,
+     "stored_file_id": "26000000-0000-4000-8000-000000000001",
+     "first_name": "Анна",
+     "username_base": "anna_sales",
+     "bio": "Помогаю с заказами",
+     "birthday": { "day": 1, "month": 2 },
+     "idempotency_key": "channel-face-1"
+   }
+   ```
+
+   Для части номеров замени `all:true` на `account_ids:[…]`. Одно фото уйдёт всем
+   целям того же задания. Для точных разных ников используй `usernames` вместо
+   `all`/`account_ids`/`username_base`.
+
+3. По `job_id` читай `besales_platform_telegram_personal_profile_job` до `COMPLETED`;
+   проверь каждый номер и `outcome.fields.avatar`, а также остальные поля.
+   `PENDING` подтверждает только принятие задания.
+
+404 `FILE_NOT_FOUND` — загрузи фото в область канала; 400 `TELEGRAM_AVATAR_INVALID`
+или 413 `TELEGRAM_AVATAR_TOO_LARGE` — выбери корректное статичное фото до 5 МиБ;
+409 `TELEGRAM_AVATAR_CHANGED` — выбери файл заново. Изменённое намерение требует нового
+ключа; сетевой повтор прежнего вызова — тот же ключ и те же аргументы.
+`PROFILE_PROVIDER_OUTCOME_UNKNOWN` требует сверки профиля, а не слепого повтора.
+Файл чужой области закрыт 404 до фермы. Мост передаёт ID, не читает байты или секреты
+Telegram и не возвращает подписанную ссылку S3.
 
 Пропуск поля сохраняет прежнее значение; пустые строки и `null` передаются буквально, а
 ложное или пустое значение выбора (`all:false`, `account_ids:[]`, `usernames:[]`) отвергается до HTTP.
@@ -84,8 +125,8 @@ Telegram неизвестен, сначала сверь профиль номе
 ядро вернёт прежний ответ, профиль второй раз не изменится и суточный предел смен не тратится.
 При неизвестном исходе новый ключ автоматически не создавай.
 
-Ссылка настройки номера (`…_setup_link`) в этой пачке не выпускается: маршрута
-`telegram-personal-setup-sessions` в ядре нет, это отдельная задача ядра.
+Для подключения номеров в существующий канал используй `…_connect_link`; план прокси
+и защищённый ввод описаны ниже.
 
 Ограничения, ручная жалоба и чтение её исхода описаны в
 [документе апелляции](telegram-personal-restrictions.md). Перед жалобой покажи человеку
@@ -97,4 +138,34 @@ Telegram неизвестен, сначала сверь профиль номе
 `telegram-personal-profile.spec.ts`. `scripts/telegram-personal-confirmation-mutants.mjs`
 проверяет, что снятие обязательного согласия в Zod или опубликованной схеме ломает именованное
 утверждение теста. `scripts/telegram-personal-profile-mutants.mjs` делает то же для запрета
-двух режимов ников сразу (в Zod и в опубликованной схеме) и для имени заголовка ключа.
+двух режимов ников сразу (в Zod и в опубликованной схеме), имени заголовка ключа
+и передачи фото в patch. Схему и варианты карты выводит
+`node --loader ./src/utils/setup-sessions-loader.mjs scripts/sync-telegram-profile-photo.mjs`;
+опись пересчитывает `scripts/sync-tool-inventory.mjs`. Оба поддерживают `--check`.
+
+## Прокси личного Telegram
+
+`besales_platform_telegram_personal_proxy_import_link` выдаёт человеку одноразовую ссылку
+до `expires_at`: логины и пароли вводятся на защищённой странице после входа, не в чате.
+`besales_platform_telegram_personal_proxy_import_status` читает по `channel_id` и `session_id`
+только состояние и счётчики, без строк прокси. Оба маршрута требуют `manage:channels`.
+`besales_platform_telegram_personal_proxy_delete` удаляет свободный прокси по `proxy_id`;
+409 `TELEGRAM_PROXY_NOT_EMPTY` — сначала переключите номера на другой прокси.
+`besales_platform_telegram_personal_account_proxy_change` переключает номер (`account_id`)
+на существующий `proxy_id`. Оба действия требуют `manage:channels` и явное
+`explicit_confirmation:true`; номер при переключении переподключится.
+Для смены обязательны стабильный `action_id` (UUID) и явный `country_change_confirmed`
+(boolean без умолчания). Повтор — с тем же ключом и аргументами. Успех только
+`state=SUCCEEDED`; `UNKNOWN`/`PENDING` не подтверждают исход.
+
+Общий запас пространства и подключение номеров доступны через десять дополнительных
+инструментов: `proxy_stock_list`, `proxy_stock_import_link`, `proxy_stock_import_status`,
+`proxy_stock_delete`, `proxy_stock_check`, `proxy_stock_check_all`, `proxies`,
+`proxy_take_from_stock`, `proxy_return_to_stock`, `connect_link` с общей приставкой
+`besales_platform_telegram_personal_`. Чтение списков — `read:channels`, изменения и статус
+импорта — `manage:channels`; проверяется свежая роль создателя ключа MCP.
+Ссылка `connect_link` работает только с существующим каналом. План пары или страны только
+заполняет страницу: коды и пароль 2FA вводит человек после входа. Пары сохраняют исходный
+`proxy_id`, адрес обратно в id не разрешается. Переносы требуют стабильный `action_id` в
+`Idempotency-Key`; `count` считает прокси, под номера выбирай `proxy_ids` по местам.
+Подробный договор и порядок действий — [прокси личного Telegram](telegram-personal-proxies.md).

package/docs/telegram-personal-proxies.md

@@ -0,0 +1,135 @@
+# Прокси личного Telegram
+
+Мост выдаёт ссылку для массовой загрузки, читает итог, удаляет свободный прокси и переключает
+свой номер на существующий прокси пула. Для этих маршрутов нужен `manage:channels`.
+`workspace_id` необязателен: используется выбранная рабочая область; `channel_id` обязателен.
+
+`besales_platform_telegram_personal_proxy_import_link` (профиль `platform`) создаёт сессию
+и возвращает `session_id`, `setup_page_url`, `expires_at`. Отдай ссылку человеку: он входит
+в приложение и вставляет строки прокси с логинами и паролями на защищённой странице, не в чате.
+Ссылка одноразовая, живёт до `expires_at`. `setup_ref` и строки прокси мост не выдаёт.
+Выдача ссылки ещё не означает загрузку прокси; автоматически создавать новую после обрыва нельзя.
+
+`besales_platform_telegram_personal_proxy_import_status` (профили `readonly`, `platform`)
+принимает `channel_id`, `session_id`, возвращает `sessionId`, `status`, `expiresAt`, `summary`
+со счётчиками `total`, `pending`, `accepted`, `duplicates`, `invalid`, `checkFailed`, `rejected`,
+`registered`. Только эти поля проходят в ответ, без строк и endpoint. `AWAITING_INPUT` ждёт
+ввода, `SUBMITTING`/`PROCESSING` ещё в работе, `UNKNOWN` требует повторного чтения, `COMPLETED`
+означает завершённую обработку (см. счётчики), `EXPIRED`/`CANCELLED` — сессия закрыта.
+
+`besales_platform_telegram_personal_proxy_delete` (профиль `platform`) принимает `channel_id`,
+`proxy_id` и обязательное `explicit_confirmation:true`. Покажи человеку прокси и канал и получи
+явное согласие: удаление необратимо. Ответ ядра 204 превращается в `{ "deleted": true }`.
+409 `TELEGRAM_PROXY_NOT_EMPTY`: сначала переключите номера на другой прокси. 404
+`TELEGRAM_PROXY_NOT_FOUND`: проверь канал и идентификатор в приложении. 503 не означает удаления.
+
+`besales_platform_telegram_personal_account_proxy_change` (профиль `platform`) принимает
+`channel_id`, `account_id`, `proxy_id`, `action_id` (UUID), `country_change_confirmed` (boolean)
+и обязательное `explicit_confirmation:true`. Номер переподключится: покажи человеку номер
+и целевой прокси и получи согласие. Смена страны — отдельное явное решение без умолчания;
+`false` передаётся буквально и не повышается автоматически до `true`.
+Создай `action_id` один раз на намерение, сохраняй его и аргументы при повторе.
+Тело ядра — строго `{ actionId, proxyId, countryChangeConfirmed }`; подтверждение в него не входит.
+Ответ — квитанция `{ message, action_id, state, code?, retry_after_ms? }`.
+Успех только при `state=SUCCEEDED`; `UNKNOWN`/`PENDING` не подтверждают переключение,
+`FAILED`/`EXPIRED` — отказ. Соблюдай `retry_after_ms`; новый ключ автоматически не создавай.
+
+Все схемы строгие: лишние поля, логины, пароли, `host`, `port`, строки импорта и camelCase
+вместо входных snake_case отвергаются до HTTP. `edit-proxy` через MCP не реализован.
+Проверки реестра — `telegram-personal-proxies.spec.ts`, снятие подтверждения в обеих схемах
+для удаления и переключения также включено в `scripts/telegram-personal-proxy-mutants.mjs`.
+
+Четыре прежних инструмента сохраняют свой договор при добавлении общего запаса.
+
+## Общий запас пространства
+
+Запас принадлежит выбранному пространству. Один прокси обслуживает номера одного канала;
+переносится целиком. `workspace_id` необязателен, как у остальных инструментов моста.
+Чтение требует `read:channels`. Изменения и статус импорта требуют `manage:channels`:
+ключ вида MCP, живой создатель и его свежая роль `CHANNEL_MANAGE`; ядро пишет аудит перед
+вызовом фермы. Выдача ссылки подключения проверяет роль на канал и не вызывает ферму.
+
+Все имена в таблице начинаются с `besales_platform_telegram_personal_`.
+
+| Суффикс | Назначение | Обязательные аргументы |
+| --- | --- | --- |
+| `proxy_stock_list` | Список запаса | — |
+| `proxy_stock_import_link` | Ссылка загрузки в запас | — |
+| `proxy_stock_import_status` | Состояние и счётчики импорта | `session_id` |
+| `proxy_stock_delete` | Удалить из запаса | `proxy_id`, `explicit_confirmation:true` |
+| `proxy_stock_check` | Проверить один прокси запаса | `proxy_id` |
+| `proxy_stock_check_all` | Поставить весь запас на проверку | — |
+| `proxies` | Список прокси канала | `channel_id` |
+| `proxy_take_from_stock` | Забрать в канал целые прокси | `channel_id`, `action_id`, один способ выбора |
+| `proxy_return_to_stock` | Вернуть свободный прокси | `channel_id`, `proxy_id`, `action_id` |
+| `connect_link` | Ссылка подключения в существующий канал | `channel_id` |
+
+Читающие инструменты входят также в `readonly` (включая статус импорта); остальные — в
+`platform`. Проверка здоровья меняет состояние и не входит в `readonly`.
+
+У списков одинаковые фильтры: `status` (`ACTIVE`, `CHECKING`, `ERROR`, `INACTIVE`),
+`country_code` (две заглавные буквы), `search` (до 200 знаков), `cursor` (UUID),
+`limit` (1–100, сервер по умолчанию 50). В HTTP страна передаётся как `countryCode`.
+`nextCursor` продолжает список; `counts`, `freeProxies`, `countryCounts`, `freeCountryCounts`
+считаются по всему пулу без фильтров. `occupiedSlots` учитывает настоящую занятость,
+`accountsCount` не показывает свободные места. Данные о стране — [IPinfo](https://ipinfo.io).
+
+Ссылка импорта возвращает только `session_id`, `setup_page_url`, `expires_at`: логин и пароль
+вводятся человеком после входа на защищённой странице, до 50 строк, 1–3 номера на прокси.
+Статус возвращает только состояние и счётчики, без строк. Ссылки не обрезаются и не пишутся
+в журнал. При потере ответа автоматически новую ссылку не создавай. `202 CHECKING` означает
+ожидание проверки; `queued` у проверки всех — число поставленных в очередь, не рабочих прокси.
+
+## Забрать и вернуть
+
+`proxy_take_from_stock` принимает ровно одну форму выбора:
+
+- `proxy_ids`: 1–50 разных UUID;
+- `count`: 1–50, необязательная `country_code` ограничивает выбор страной.
+
+`count` — число прокси, а не мест. У прокси 1–3 места (`maxAccounts`). Под N номеров сначала
+вычти места явных пар и свободные места канала, затем выбери конкретные свободные ACTIVE
+прокси запаса по местам. При выборе страны учитывай только её. Сумма `maxAccounts` должна
+покрыть недостачу; если не покрывает, перенос не вызывай. Для шести номеров и двух прокси
+по три места передай оба `proxy_ids`, не `count:6`.
+
+Оба переноса требуют стабильный `action_id` (UUID), который идёт только заголовком
+`Idempotency-Key`. Взятие передаёт `{proxyIds}` либо `{count,countryCode?}`; возврат — без тела.
+Явного `explicit_confirmation` эти операции не принимают. Забрать — всё или ничего:
+`TELEGRAM_PROXY_STOCK_NOT_ENOUGH` и `TELEGRAM_PROXY_STOCK_REFUSED` не переносят ни одного
+прокси. После устранения причины отказа можно повторить прежний ключ. Успех с тем же ключом
+возвращает прежний результат. `IDEMPOTENCY_REQUEST_MISMATCH` не обходи новым ключом.
+При 503 исход неизвестен: повтори тот же ключ и аргументы, новый автоматически не создавай.
+
+Вернуть можно только свободный прокси без номеров, броней и операций.
+`TELEGRAM_PROXY_NOT_EMPTY` требует освободить его или дождаться операции;
+`TELEGRAM_PROXY_ADDRESS_IN_USE` при возврате означает, что адрес уже в запасе: предложи
+удалить этот прокси из канала. Прямого переноса между каналами нет — только через запас.
+Удаление из запаса необратимо и требует отдельного согласия `explicit_confirmation:true`;
+при занятой операции повтори позже. `204` подтверждает удаление, 503 его не подтверждает.
+
+## Подключение с планом
+
+`connect_link` требует существующий `channel_id`. Необязательный `proxy_plan` имеет ровно
+одну форму: `{pairs:[{phone,proxy_id}]}` либо `{country_code}`. Без плана страница открывается
+для обычного выбора. Телефоны пар — E.164, 1–50 пар, телефоны разные, один прокси не больше
+трёх раз. Строгая проверка вложенных объектов выполняется до HTTP. В ядро идут `channelId`,
+`proxyPlan.pairs[].proxyId` либо `proxyPlan.countryCode`; исходные идентификаторы сохраняются.
+
+План только заполняет страницу. Ссылка ничего не бронирует, не переносит и не подключает.
+Человек входит, проверяет пары и вводит коды Telegram и пароль 2FA на странице, не в чате.
+Ответ содержит только `setup_page_url`, `expires_at` и инструкции, без `setup_ref` и плана.
+Пары берут прокси канала либо запаса пространства. При старте страница проверяет наличие,
+состояние и места; прокси запаса забираются одним атомарным вызовом со списком id.
+
+Пара держится за исходный `proxy_id`: адрес служит только для показа, обратного разрешения
+адреса нет. Совпадение адресов не подменяет id. Пропавший id блокирует старт до правки
+человеком; правка адреса снимает id, удаление адреса делает строку автоматической только
+по его решению. Явная пара молча не переназначается. Итог — `…_accounts`.
+Для уже подключённого номера сначала забери нужный прокси из запаса, затем используй
+`…_account_proxy_change` с отдельным подтверждением переподключения.
+
+Проверки нового набора находятся в `telegram-proxy-stock.spec.ts`, прежнего — в
+`telegram-personal-proxies.spec.ts`. Скрипт `scripts/telegram-personal-proxy-mutants.mjs`
+проверяет строгий ввод, согласие, стабильные заголовки, наличие маршрута, запрет усечения,
+две формы выбора, форму плана и обязательный канал.

package/docs/telegram-session-import.md

@@ -0,0 +1,53 @@
+# Импорт партии номеров Telegram
+
+`besales_platform_telegram_personal_session_import_link` выдаёт человеку ссылку на уже
+существующую защищённую страницу подключения Telegram. Ввод: `channel_id` и необязательный
+`workspace_id` (иначе используется выбранное пространство). Требуется `manage:channels`.
+Профиль `platform`; профиль `readonly` этот инструмент не включает.
+
+Человек входит в приложение, выбирает импорт до 50 файлов и задаёт прокси для каждого файла
+или автоназначение. Содержимое файлов, манифест, ключи приложения и пароли остаются в браузере.
+MCP принимает только идентификаторы; любые дополнительные поля отвергаются до HTTP.
+Ссылка живёт 15 минут. Заказ ссылки сам по себе номера не добавляет.
+
+## Маршрут и ответ
+
+Используется существующий `POST /workspaces/:workspaceId/telegram-personal-setup-sessions`
+с телом `{channelId}`. Новый маршрут ядра и новая страница не создаются.
+Ответ моста перечисляет только `setup_page_url`, `expires_at`, `operation_id: null`,
+`import_status_available: false` и инструкцию следующего шага. Сырой `setup_ref`, состояние
+мастера и неизвестные поля ответа ядра отбрасываются до общей границы сериализации MCP.
+
+Безопасного идентификатора операции импорта этот init пока не возвращает. Пофайловый статус
+`GET /channels/:channelId/telegram-personal/session-imports/:jobId` разрешён только вошедшему
+человеку в браузере. Мост не ослабляет этот запрет и не выдаёт `setup_ref` за идентификатор.
+Результат каждого файла проверяется на странице; `besales_platform_telegram_personal_accounts`
+помогает сверить принятые номера, но не объясняет отклонение каждого файла.
+
+## Список прокси
+
+Уже доступны `besales_platform_telegram_personal_proxy_import_link` / `_status` для канала
+и `besales_platform_telegram_personal_proxy_stock_import_link` / `_status` для общего запаса.
+Они возвращают настоящий `session_id`, ссылку и срок. Статусы содержат только состояние и
+счётчики; причины по строкам остаются на защищённой странице. Пароли и строки SOCKS5
+нельзя присылать инструментам и нельзя копировать из страницы в чат.
+
+## Продолжение
+
+Встроенная справка `besales://workflows/platform-setup-from-scratch`, раздел
+«Подготовить партию номеров Telegram», ведёт по импорту, профилю, фото, Premium и кампании.
+Для фото и Premium отдельных инструментов в текущем пакете нет; эти шаги выполняются
+в интерфейсе приложения. Запуск кампании остаётся отдельным намерением человека.
+
+## Проверки и генерация
+
+`scripts/sync-telegram-session-import.mjs` выводит опубликованную схему и дополнение описи
+чтений из исполняемого определения. Затем `scripts/sync-tool-inventory.mjs` пересчитывает
+инвентарь, а `scripts/sync-route-map.mjs` сверяет маршрут с закреплённым контрактом ядра.
+Каждый поддерживает `--check`; для TypeScript-импортов используется существующий
+`src/utils/setup-sessions-loader.mjs`.
+
+`telegram-session-import.spec.ts` проверяет опубликованную схему, HTTP, запрет секретных
+полей, проекцию ответа в обоих форматах MCP, аннотации и отсутствие автоматического повтора
+после отказов. Общие проверки описи, аннотаций, размеров ответов и ссылок справки также
+включают новый инструмент.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@besales/mcp",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.9",
   "description": "Model Context Protocol server for Besales",
   "license": "MIT",
   "homepage": "https://github.com/be-sales/mcp#readme",
@@ -57,15 +57,16 @@
     "test": "vitest run",
     "lint:fix": "eslint src bin scripts eslint.config.js --fix",
     "lint:errors": "eslint src bin scripts eslint.config.js",
-    "types:gen:api": "node scripts/sync-api-contracts.mjs --types-only",
+    "types:gen:api": "node --loader ./src/utils/setup-sessions-loader.mjs scripts/sync-api-contracts.mjs --types-only",
     "publish:mcp-registry": "node scripts/publish-mcp-registry.mjs",
-    "schemas:sync:agent-models": "node scripts/sync-agent-model-schemas.mjs",
-    "schemas:sync:trigger-arguments": "node scripts/sync-trigger-argument-schema.mjs",
-    "schemas:sync:wave-ids": "node scripts/sync-wave-id-schemas.mjs",
-    "schemas:sync:crm-stage-pool": "node scripts/sync-crm-stage-pool-schema.mjs",
+    "schemas:sync:agent-models": "node --loader ./src/utils/setup-sessions-loader.mjs scripts/sync-agent-model-schemas.mjs",
+    "schemas:sync:trigger-arguments": "node --loader ./src/utils/setup-sessions-loader.mjs scripts/sync-trigger-argument-schema.mjs",
+    "schemas:sync:wave-ids": "node --loader ./src/utils/setup-sessions-loader.mjs scripts/sync-wave-id-schemas.mjs",
+    "schemas:sync:crm-stage-pool": "node --loader ./src/utils/setup-sessions-loader.mjs scripts/sync-crm-stage-pool-schema.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src bin scripts eslint.config.js",
-    "contracts:sync:api": "node scripts/sync-api-contracts.mjs"
+    "contracts:sync:api": "node --loader ./src/utils/setup-sessions-loader.mjs scripts/sync-api-contracts.mjs",
+    "contracts:check:api": "node --loader ./src/utils/setup-sessions-loader.mjs scripts/sync-api-contracts.mjs --check"
   },
   "engines": {
     "node": ">=20.0.0"

package/scripts/body-idempotency-contract.mjs

@@ -0,0 +1,95 @@
+import ts from 'typescript';
+
+/** Читает тела операций снимка, включая inline-типы и ссылки на operations/components. */
+export function bodyIdempotencyOperations(source) {
+  const file = ts.createSourceFile('api-contract.ts', source, ts.ScriptTarget.Latest, true);
+  if (file.parseDiagnostics.length) throw new Error('API_CONTRACT_PARSE_FAILED');
+  const declarations = new Map(
+    file.statements
+      .filter((node) => ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node))
+      .map((node) => [node.name.text, node]),
+  );
+  function members(node, seen = new Set()) {
+    if (!node) throw new Error('API_CONTRACT_TYPE_MISSING');
+    if (seen.has(node)) throw new Error('API_CONTRACT_TYPE_CYCLE');
+    const next = new Set([...seen, node]);
+    if (ts.isTypeReferenceNode(node)) {
+      if (
+        node.typeName.getText(file) === 'Record' &&
+        node.typeArguments?.[0]?.kind === ts.SyntaxKind.StringKeyword &&
+        node.typeArguments?.[1]?.kind === ts.SyntaxKind.NeverKeyword
+      )
+        return [];
+      const declaration = declarations.get(node.typeName.getText(file));
+      if (!declaration) throw new Error('API_CONTRACT_REFERENCE_MISSING: ' + node.getText(file));
+      return members(declaration, next);
+    }
+    if (ts.isTypeAliasDeclaration(node) || ts.isParenthesizedTypeNode(node))
+      return members(node.type, next);
+    if (ts.isIndexedAccessTypeNode(node)) {
+      if (!ts.isLiteralTypeNode(node.indexType)) throw new Error('API_CONTRACT_INDEX_UNSUPPORTED');
+      const field = members(node.objectType, next).find(
+        (one) => one.name?.text === node.indexType.literal.text,
+      );
+      if (!field) throw new Error('API_CONTRACT_REFERENCE_MISSING: ' + node.getText(file));
+      return members(field.type, next);
+    }
+    if (ts.isUnionTypeNode(node) || ts.isIntersectionTypeNode(node))
+      return node.types.flatMap((one) => members(one, next));
+    if (ts.isTypeLiteralNode(node) || ts.isInterfaceDeclaration(node)) return [...node.members];
+    // Основание indexed access — имя интерфейса, а не ссылка TypeReference.
+    if (ts.isIdentifier(node)) return members(declarations.get(node.text), next);
+    if (
+      ts.isArrayTypeNode(node) ||
+      ts.isLiteralTypeNode(node) ||
+      (node.kind >= ts.SyntaxKind.FirstKeyword && node.kind <= ts.SyntaxKind.LastKeyword)
+    )
+      return [];
+    throw new Error('API_CONTRACT_TYPE_UNSUPPORTED: ' + node.getText(file));
+  }
+
+  const paths = declarations.get('paths');
+  if (!paths?.members?.length) throw new Error('API_CONTRACT_PATHS_MISSING');
+  const operations = [];
+  for (const route of paths.members) {
+    for (const method of members(route.type)) {
+      if (!/^(get|post|put|patch|delete|head|options|trace)$/u.test(method.name?.text ?? ''))
+        continue;
+      const body = members(method.type).find((field) => field.name?.text === 'requestBody');
+      if (!body || body.type.kind === ts.SyntaxKind.NeverKeyword) continue;
+      const content = members(body.type).find((field) => field.name?.text === 'content');
+      if (!content) throw new Error('API_CONTRACT_BODY_CONTENT_MISSING');
+      for (const media of members(content.type)) {
+        for (const field of members(media.type)) {
+          const key = field.name?.text;
+          const description = field.getFullText(file);
+          if (
+            !/^(requestKey|idempotencyKey)$/u.test(key ?? '') &&
+            !(
+              /(?:key|token|Id)$/iu.test(key ?? '') &&
+              /@description (?:Неизменный |Обязательный |Сохранённый )?(?:Ключ (?:идемпот|намерения|повтора|операции)|UUID идемпот)/iu.test(
+                description,
+              )
+            )
+          )
+            continue;
+          operations.push({
+            method: method.name.text.toUpperCase(),
+            path: route.name.text,
+            key,
+            required: !body.questionToken && !field.questionToken,
+          });
+        }
+      }
+    }
+  }
+  return operations;
+}
+
+export function contractRoute(entry) {
+  return `${entry.expected.method} /api/v2${entry.expected.pathTemplate.replace(/:([A-Za-z0-9_]+)/gu, '{$1}')}`;
+}
+
+export function operationRoute(operation) {
+  return `${operation.method} ${operation.path}`;
+}

package/scripts/generate-followup-session-contract.mjs

@@ -1,16 +1,23 @@
-import { readFileSync, writeFileSync } from 'node:fs';
+import { writeGeneratedFile } from './generated-output.mjs';
+import { readFileSync } from 'node:fs';
 import { z } from 'zod';
-import { reactivationConfigSchema } from '../dist/tools/definitions/follow-up-config.js';
+import { reactivationConfigSchema } from '../src/tools/definitions/follow-up-config.js';
 
 // Только добавочные поля: остальные ограничения отгруженной поверхности остаются дословными.
 const file = new URL('../src/schemas/mcp-tools.json', import.meta.url);
 const registry = JSON.parse(readFileSync(file, 'utf8'));
-const tool = registry.tools.find(item => item.name === 'besales_followup_sequence_upsert');
+const tool = registry.tools.find((item) => item.name === 'besales_followup_sequence_upsert');
 if (!tool?.inputSchema?.properties?.config?.properties) throw new Error('Нет конфигурации цепочки');
-const derived = z.toJSONSchema(reactivationConfigSchema, { io: 'input', unrepresentable: 'any' });
+const derived = z.toJSONSchema(reactivationConfigSchema, {
+  io: 'input',
+  unrepresentable: 'any',
+});
 for (const field of ['sessionTimeVariable', 'sessionDayOffsets', 'sessionDurationMinutes']) {
-  if (!derived.properties[field]) throw new Error('Не объявлено поле '+field);
+  if (!derived.properties[field]) throw new Error('Не объявлено поле ' + field);
   tool.inputSchema.properties.config.properties[field] = derived.properties[field];
 }
-tool.description = tool.description.replace('непустые dealFields, серия эфиров и неисполняемые виды шагов', 'непустые dealFields и неисполняемые виды шагов');
-writeFileSync(file, JSON.stringify(registry, null, 2)+'\n');
+tool.description = tool.description.replace(
+  'непустые dealFields, серия эфиров и неисполняемые виды шагов',
+  'непустые dealFields и неисполняемые виды шагов',
+);
+writeGeneratedFile(file, JSON.stringify(registry, null, 2) + '\n');

package/scripts/generated-output.mjs

@@ -0,0 +1,9 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+
+// Один режим проверки для узких генераторов: проверка никогда не переписывает вход.
+export function writeGeneratedFile(file, output) {
+  if (process.argv.includes('--check')) {
+    if (readFileSync(file, 'utf8') !== output)
+      throw new Error('GENERATED_CONTRACT_DRIFT: ' + String(file));
+  } else writeFileSync(file, output);
+}