@besales/mcp 0.47.1 → 1.0.0-beta.2

package/docs/modules/network-mode.md

@@ -0,0 +1,284 @@
+# Сетевой MCP
+
+BeSales MCP может работать как HTTP-служба: мост выполняется на сервере, а клиент
+подключается к нему по сети с ключом своей рабочей области. Публичный адрес службы должен использовать
+HTTPS; TLS завершает прокси перед Node.js. Служба предоставляет `/mcp` через Streamable HTTP.
+
+## Онлайн-MCP: подключение коллег
+
+Онлайн-MCP позволяет Claude Code и Codex CLI работать с твоей рабочей областью Besales:
+смотреть данные и выполнять действия в пределах выданных прав. Клиенты обращаются к
+`https://mcp.besales.ai/mcp`; держать локальный мост запущенным не нужно.
+
+Нужны Node.js 20+ (`node -v`), Claude Code и/или Codex CLI и аккаунт Besales с доступом
+к нужной рабочей области. Выполняй команды сам в своём терминале, не передавай ключ агенту
+и не вставляй его в чат.
+
+**Важно:** `beta` — тег предварительной версии. Для этих инструкций нужен именно
+`@besales/mcp@beta`. Обычный `npx -y @besales/mcp` без тега по-прежнему устанавливает
+прежнюю версию 0.48. Пакет этой ветки станет доступен через `beta` после публикации владельцем.
+
+### Шаг 1. Получи ключ своей рабочей области
+
+```bash
+npx -y @besales/mcp@beta connect
+npx -y @besales/mcp@beta connections
+```
+
+Первая команда открывает браузер: войди в Besales, выбери область и подтверди права.
+Ключ `mcp_…` сохранится в локальной связке ключей. Повтори `connect` один раз для каждой
+нужной области; вторая команда покажет их имена и UUID. Ключ получается локальной командой
+`connect` один раз, а дальше локальный мост для работы онлайн-клиентов не нужен.
+
+### Шаг 2. Настрой клиентов скриптом или вручную
+
+В репозитории [be-sales/mcp](https://github.com/be-sales/mcp) скачай файл
+`scripts/connect-clients.sh` из ветки с онлайн-MCP и запусти:
+
+```bash
+bash scripts/connect-clients.sh
+```
+
+Или получи скрипт из установленного пакета:
+
+```bash
+npm install -g @besales/mcp@beta
+bash "$(npm root -g)/@besales/mcp/scripts/connect-clients.sh"
+```
+
+Скрипт читает только `connections --json`: это JSON-массив объектов
+`{workspaceId, workspaceName, accountLabel, keyPrefix, active}` одной строкой, без полных ключей.
+В обычном выводе управляющие символы имён и подписей заменяются пробелами; JSON сохраняет
+имя целиком с экранированием. Имена передаются разборщику только через stdin, без исполнения.
+Скрипт принимает UUID только по шаблону `^[0-9a-f-]{36}$` и создаёт запись
+`besales-<слаг имени>` только из букв `a-z`, цифр и дефиса: для слага берутся первые
+200 символов очищенного имени, сам слаг ограничен 64 символами; пустой слаг заменяется
+первыми 8 символами UUID. При совпадении имён добавляются первые четыре символа UUID,
+при дальнейшей коллизии — полный UUID. Отсутствующий в PATH клиент
+пропускается. Повторный запуск обновляет подключения. Для выбора отдельных областей передай
+имена записей или префиксы UUID:
+
+```bash
+bash scripts/connect-clients.sh besales-sales 1234abcd
+```
+
+Ключи для Codex сохраняются в `~/.besales-secrets/mcp-remote-keys.env` (каталог 700, файл 600).
+Скрипт напечатает строку `source` без ключей: добавь её в `~/.zshrc` или `~/.bashrc` и выполни
+в текущем терминале. Запускай Codex из терминала, где загружены эти переменные.
+При любом запуске сохраняются посторонние строки и переменные остальных областей:
+заменяются или добавляются только `export BESALES_MCP_KEY_<ИМЯ>="…"` успешно подключённых
+в этом запуске областей и отсутствующий заголовок. Повторный запуск не дублирует записи.
+Запись атомарна: временный файл рядом с исходным и `mv`; ошибка клиента сохраняет прежний файл.
+
+Адрес можно задать через `BESALES_MCP_URL`, команду получения ключей — через
+`BESALES_MCP_BRIDGE` (по умолчанию `npx -y @besales/mcp@beta`). Для исходников:
+
+```bash
+BESALES_MCP_BRIDGE='node /путь/к/mcp/bin/besales-mcp.js' bash scripts/connect-clients.sh
+```
+
+Здесь команда моста — аргументы через пробелы; путь не должен содержать пробелов.
+
+Вместо скрипта можно выполнить три команды вручную. Замени `UUID` идентификатором из
+`connections`, а `besales-sales` — своим уникальным именем записи:
+
+```bash
+claude mcp add --scope user --transport http besales-sales https://mcp.besales.ai/mcp --header "Authorization: Bearer $(npx -y @besales/mcp@beta key UUID)"
+export BESALES_MCP_KEY_SALES="$(npx -y @besales/mcp@beta key UUID)"
+codex mcp add besales-sales --url https://mcp.besales.ai/mcp --bearer-token-env-var BESALES_MCP_KEY_SALES
+```
+
+Для ручной настройки Codex повторяй `export` в каждом новом терминале или добавь именно
+команду с подстановкой `$(…)` в профиль оболочки. При нескольких областях нужны разные
+имена записей, UUID и имена переменных. Для обновления уже существующей записи сначала
+удали её: `claude mcp remove --scope user besales-sales` или `codex mcp remove besales-sales`,
+затем повтори нужную команду добавления. Скрипт делает это сам.
+
+Ключ лежит в настройках Claude Code открытым текстом. Codex хранит имя переменной,
+а её значение скрипт записывает открытым текстом в закрытый файл. Не публикуй настройки
+или файл ключей, ограничь доступ к своему компьютеру. Подстановка команды в терминале
+не печатает ключ; отдельная команда `key [UUID]` выводит секрет, поэтому не запускай её
+на общей демонстрации экрана.
+
+Известное ограничение: Claude Code принимает заголовок только аргументом команды
+`claude mcp add --header`, поэтому на время её выполнения (доли секунды) ключ виден в
+списке процессов этого же компьютера. Запускай скрипт на личном компьютере, где нет
+посторонних пользователей. У Codex такого нет: ему передаётся только имя переменной.
+
+### Шаг 3. Проверь подключение
+
+```bash
+claude mcp list
+codex mcp list
+```
+
+Проверь установленный у тебя клиент, открой новую сессию агента и спроси:
+«какая у меня рабочая область?». Ответ должен соответствовать выбранной области.
+
+| Ответ службы | Что делать |
+| --- | --- |
+| 401 | Ключ просрочен (срок — 90 дней), отозван или потерял доступ. Снова выполни `npx -y @besales/mcp@beta connect`, затем скрипт; для Codex повтори `source`. |
+| 502 | Ядро временно недоступно. Для известного ключа повторная проверка приостановлена до 5 секунд; соблюдай `Retry-After`. |
+| 429 | Достигнут лимит. Подожди число секунд из `Retry-After` и повтори запрос. |
+| 503 | Служба занята или обновляется. Повтори через несколько секунд. |
+
+Чтобы отозвать доступ, открой список подключений в Besales и отзови нужное подключение.
+Удаление записи только в Claude Code или Codex не отзывает сам ключ.
+Общая проверка службы учитывает отзыв ключа после истечения кэша, даже если все
+ожидавшие её клиенты отключились до ответа ядра.
+
+## Как работает служба без сессий
+
+Каждый POST на `/mcp` независим. Клиент один раз выполняет `initialize`, затем отправляет
+`notifications/initialized`, `tools/list` и `tools/call` отдельными HTTP-запросами.
+В каждом запросе обязателен собственный `Authorization: Bearer mcp_…`.
+Штатный stateless-режим SDK 1.29.0 использует `sessionIdGenerator: undefined` и
+`enableJsonResponse: true`: ответы на вызовы — JSON, уведомления получают HTTP 202.
+Служба не выдаёт `Mcp-Session-Id`, а присланный клиентом старый заголовок игнорирует.
+
+Для клиента нет сессий: простой и обновление службы между завершёнными запросами ему
+не видны, повторная инициализация и ручное переподключение не требуются. Во время
+самой недоступности службы запрос может получить сетевую ошибку; незавершённый вызов
+при принудительной остановке сверх срока ожидания также не гарантируется.
+`GET /mcp` и `DELETE /mcp` дают HTTP 405 с `Allow: POST`: постоянного SSE-потока
+и операции удаления подключения нет. Реплики не требуют привязки клиента к процессу.
+
+| Код | Что означает и что делать |
+| --- | --- |
+| 200 / 202 | JSON-RPC ответ / принятое уведомление. Ошибку инструмента смотри в JSON-RPC результате. |
+| 400 | Неверный JSON/JSON-RPC или запрещённый POST-массив: отправь отдельный запрос. Для массива код JSON-RPC — -32600. |
+| 401 | Ключ не принят, имеет неверный формат или лишён доступа; ответ содержит `WWW-Authenticate: Bearer`. Повтори `connect` и настройку клиента при необходимости. |
+| 403 | Запрос содержит Origin: браузерные обращения запрещены. |
+| 404 | Неизвестный путь; к сроку жизни подключения этот код не относится. |
+| 405 | На `/mcp` разрешён только POST, смотри `Allow: POST`. |
+| 406 / 415 | Неверный Accept / Content-Type, проверяемый SDK. |
+| 413 | Тело больше 1 МиБ, в том числе chunked; уменьши объём. |
+| 429 | Лимит ключа или адреса; подожди `Retry-After` секунд. |
+| 502 | Ядро недоступно, проверка ключа завершилась таймаутом или непригодным ответом; повтори позже. |
+| 503 | Достигнут потолок работы либо служба останавливается; `Retry-After: 1`. |
+
+## Запуск службы
+
+```sh
+yarn install --immutable
+yarn build
+node bin/besales-mcp-http.js
+```
+
+Для контейнера собери `Dockerfile` и запусти образ. Node.js 22 используется для сборки
+и выполнения. Финальный образ содержит только производственные зависимости. Нативный
+keytar не загружается, libsecret не требуется. Обычный запуск через stdio сохраняется.
+
+| Переменная | Назначение | Умолчание |
+| --- | --- | --- |
+| `PORT` | Порт HTTP, в том числе назначаемый прокси | `3000` |
+| `BESALES_API_BASE_URL` | Базовый URL API | `https://core.besales.ai/api/v2` |
+
+`BESALES_WORKSPACE_ID` и `BESALES_MCP_TASK_STATE_PATH` не определяют поведение HTTP.
+Область подтверждается через `GET /auth/mcp-context` с ключом текущего запроса.
+
+## Проверка ключа и ограниченная память
+
+До чтения тела и обращения к ядру проверяется заголовок `Authorization: Bearer mcp_…`.
+После префикса допустимы латинские буквы, цифры, `_` и `-`, весь ключ — до 512 символов.
+Отказ по формату даёт 401; при исчерпанном лимите адреса действует 429.
+Отказы ядра 401/403 запоминаются на 60 секунд по SHA-256, без исходного ключа:
+не более 1000 записей, вытесняется старейшая. Попадание в память не продлевает срок.
+Повторный отказ не читает тело и не обращается к ядру.
+
+Успешный вердикт кэшируется на 60 секунд по SHA-256: идентификатор и имя рабочей
+области, подпись аккаунта и права; сырой ключ в кэше отсутствует. Не более 1000 записей,
+при заполнении вытесняется старейшая, обращения не продлевают TTL. Одновременные
+проверки одного отпечатка склеиваются в один запрос к ядру; каждый ожидающий запрос
+сохраняет собственное подключение и собственный ключ. После TTL выполняется новая проверка.
+Отпечатки ранее принятых ключей дополнительно хранятся до 6 часов (не более 1000,
+с вытеснением самого старого); это не кэш полномочий. Успешная проверка ядром обновляет
+этот срок, отказ 401/403 удаляет отпечаток и запоминает отказ; 5xx/таймаут его не меняют.
+5xx ядра, сетевые ошибки, таймауты и невалидный контекст дают 502 и не попадают ни в
+успешный кэш, ни в память отвергнутых ключей. Для известного ключа сбой проверки
+запоминается отдельно по SHA-256 на 5 секунд (до 1000 записей с вытеснением старейшей):
+повторы получают 502 с `Retry-After` без обращения к ядру и не продлевают паузу.
+После срока проверка повторяется, успех очищает запись; известный отпечаток при сбое
+сохраняется. Неизвестные ключи по-прежнему ограничены ведром адреса и не заполняют эту
+таблицу. Исход общей проверки обрабатывается один раз в самом обещании: успех сохраняет
+вердикт и известный отпечаток, 401/403 забывает отпечаток и запоминает отказ, даже если
+все ожидающие оборвались. Таблица сбоев очищается по таймеру и при остановке.
+
+Отозванный ключ сразу перестаёт работать на вызовах инструментов у ядра: вызов всегда
+передаёт ему текущий ключ клиента. Собственная проверка службы может отставать до TTL
+(60 секунд): до обновления кэша перечисление инструментов ещё доступно, но полномочия
+вызовов проверяет само ядро. Кэш контекста не выдаёт доступ вместо ядра.
+
+## Лимиты и защита от перебора
+
+| Ограничение на один процесс | Значение |
+| --- | --- |
+| Одновременные запросы, включая проверку ключа, тело и выполнение | 100, далее 503 |
+| Тело, включая chunked | 1 МиБ |
+| Ведро принятого ключа | 120 запросов; восстановление 1 запроса в секунду |
+| Число вёдер ключей | 10 000; мусорные и отвергнутые ключи их не создают |
+| Ведро адреса для проверок | 20 попыток; восстановление 1 попытки за 3 секунды |
+| Число вёдер адресов | 10 000 |
+| Успешные вердикты / отвергнутые отпечатки | По 1000 записей, TTL 60 секунд |
+| Известные отпечатки ключей | 1000 записей, срок 6 часов |
+| Сбои проверки известных отпечатков | 1000 записей, пауза 5 секунд |
+| Таймаут заголовков / получения HTTP-запроса | 10 / 65 секунд |
+| Таймаут обращения к ядру | 60 секунд |
+| Ожидание принятых запросов при остановке | До 5 секунд |
+
+Ведро ключа расходуется только после подтверждения ядром или попадания в успешный кэш.
+Ведро адреса расходуют неизвестные ключи, которым необходима проверка у ядра (включая
+ожидающих общую проверку), и отказы по формату или отвергнутому отпечатку. Успешный кэш
+и повторная проверка известного ключа не расходуют ведро адреса. После проверки для
+известного ключа по-прежнему действуют склейка проверок и собственное ведро ключа.
+429 содержит `Retry-After` в секундах с округлением вверх: до 3 для адреса, 1 для ключа.
+Заполненная таблица вёдер отказывает новому элементу без вытеснения действующих вёдер.
+
+Адрес берётся только из `X-Real-IP`, который должен устанавливать доверенный входной
+прокси (в целевом окружении — Railway). Перед службой стоит Cloudflare: адрес в
+`X-Real-IP` может быть адресом его узла, общим для многих людей. Поэтому защита не
+наказывает известные ключи за перебор других ключей с этого общего адреса. Прямой доступ к Node.js должен быть закрыт,
+иначе этот заголовок можно подделать. `X-Forwarded-For` и адрес сокета не используются;
+без `X-Real-IP` все клиенты делят одно ведро неизвестного адреса. Адрес не передаётся
+ядру и не записывается в журнал. Неактивные вёдра адресов очищаются через 60 секунд,
+ключей — через 120 секунд; таблица известных ключей очищается по сроку и при остановке; общая чистка выполняется каждую минуту, а при заполнении
+таблицы также перед отказом. Кэши дополнительно проверяют срок при обращении.
+
+Любой присутствующий `Origin` (включая пустой и `null`) получает JSON 403 до
+авторизации, чтения тела и расхода вёдер. Это защищает службу от браузерных обращений
+и DNS-rebinding; сетевые CLI-клиенты работают без `Origin`.
+
+## Изоляция и завершение запроса
+
+Каждый POST создаёт новые MCP Server, транспорт, ConnectionStore и хранилище ровно
+одного подключения. Ключ берётся из заголовка этого запроса, живёт до его завершения
+и не записывается на диск. После закрытия ответа credentials очищаются, транспорт
+и сервер закрываются. Даже совпадающие JSON-RPC id параллельных запросов не разделяют
+состояние SDK. Место в лимите освобождается только после завершения HTTP-обработчика и всех начатых
+им API-вызовов, даже если клиент уже оборвал соединение. При остановке эта работа
+также ожидается до общего срока 5 секунд. Обрыв отслеживается до первого await и проверяется после проверки ядра,
+чтения тела, заполнения store и подключения транспорта. Оборванная проверка ключа
+немедленно отсоединяет ожидающего и освобождает его место; остальные живые ожидающие
+продолжают общую проверку; результат сохраняет сама проверка независимо от ожидающих. Оборванный ожидающий сам
+не создаёт вердикт, credentials или ведро ключа и не пишет предупреждение в журнал.
+
+Область фиксирована ключом: явный запрос другой области отклоняется. Число (292) и
+имена инструментов совпадают со stdio. `besales_workspace_current` видит только текущее
+подключение; `besales_workspace_use` отказывает. Локальные `besales_task_*` также
+возвращают отказ: контекст длительной задачи храни у клиента.
+
+`GET /health` без ключа возвращает только `{status, version}`. При SIGTERM служба
+перестаёт принимать новые соединения, ждёт принятые запросы до 5 секунд, затем закрывает
+оставшиеся соединения и выходит с кодом 0. Новая работа во время ожидания получает
+503 с `Retry-After: 1`. Настрой проверку здоровья на `/health`.
+
+Журнал скрывает Authorization, MCP-ключи и секреты настройки, включая строки ошибок.
+Не включай журналирование сырых заголовков на внешнем прокси. Маска `mcp_…` применяется
+только к журналу; проверки содержимого локальных stdio-задач сохранены.
+Общего ConnectionStore, файлов задач, БД, Redis, томов или серверного общего ключа нет.
+Автоматический браузерный вход и OAuth для сетевых MCP-клиентов не поддерживаются:
+подключение выполняется через заголовок клиента и HTTPS-прокси.
+
+## Известные ограничения
+
+Ядро, бесконечно отдающее тело по капле, может удерживать место запроса до отмены транспорта (абсолютного срока API нет, общий со stdio `src/http/api-client.ts` не меняется); обработчики `Promise.race` оборвавшихся ожидающих остаются на общем обещании до его завершения (оно ограничено таймаутом API 60 с).

package/docs/modules/prompt-batch-and-dialogue-controls.md

@@ -0,0 +1,69 @@
+# Раскатка промптов, пауза дожимов и настройки канала
+
+`besales_pipeline_settings_update.auto_finish` сохраняет форму отгруженного клиента:
+мост переводит прежние snake_case-поля в camelCase. Дни — целое число от 1 до 36500.
+Изменение отправки заметки в CRM требует `explicit_confirmation=true`; сервер сверяет
+действующий флаг автозавершения и синхронно сохраняет зеркало заметки CRM. `null` у
+шаблона снимает его. Поле `finish_auto_timeout` остаётся отложенным (422).
+
+`besales_prompt_batch_start` сохраняет прежнюю форму. После потери ответа прочитай
+`besales_prompt_batch_by_key` с исходным ключом: он передаётся без нормализации. Тот же
+ключ и состав возвращают прежний прогон; другой состав даёт 409. Новый ключ может
+запустить вторую раскатку. Ответ чтения сохраняет `operations`, `startedBy`, фазы и
+локализованные причины отказа агентов.
+
+`besales_prompt_batch_stop` принимает `run_id`. Ответ 202 подтверждает принятие
+остановки после текущего агента. Начатая запись завершается; применённые изменения
+сохраняются. Конечное состояние проверяется через `besales_prompt_batch_status`.
+Повтор остановки идемпотентен. STOPPED может содержать не начатых агентов, поэтому
+ненулевой PENDING сам по себе не означает, что прогон выполняется. 404 означает
+недоступный прогон, 503 — недоступное управление.
+
+`besales_prompt_batch_resume` продолжает оставшихся, отказавших и сброшенных
+барьером агентов, включая откатанных подготовкой `allOrNothing`. Уже записанные
+агенты не повторяются. 400 означает живой прогон, 409 — неустановленный исход
+прежней операции: перечитай статус и не создавай новую раскатку автоматически.
+
+`besales_dialogue_followup_state_get` читает состояние по `conversation_id` под
+правом чтения диалогов. API разрешает пару «контакт × канал» и возвращает сохранённую
+и действующую паузу, момент измерения, версию, допустимые действия, последствия и
+ограничения. Матрица и её локализованный текст передаются целиком. Ошибки 403/404/503
+сохраняются как отказы; ошибка чтения не превращается в NONE. Внешние ограничения
+остаются NOT_CHECKED. Включение оси не гарантирует отправку и не воскрешает отменённый
+прогон.
+
+`besales_dialogue_followup_state_update` записывает явное решение человека через
+PATCH `/conversations/:conversationId/followup-state/bridge`: `expected_version`
+берётся из чтения, `mute_expires_at` передаётся только для `MUTE_TEMPORARY`. Перед
+записью покажи последствия и ограничения. После 409/428 перечитай состояние и
+получи новое решение человека; после неизвестного исхода сначала прочитай состояние
+без автоматического повтора записи.
+
+`besales_platform_settings_update` принимает прежние необязательные разделы:
+
+- `smsgorod_settings`: `channel` (DIGIT/CHAR) и nullable `sender`, для SMS-канала с
+  подключением SMS-город.
+- `bitrix24_bot_settings`: имя и режим работы бота. Смена `ignore_crm_stage_gate`
+  требует `explicit_confirmation=true`; неизменное значение допускается без него.
+  `bot_id`, `bot_code`, `open_line_id` управляются подключением: точное ненулевое эхо
+  допустимо, изменение/null даёт 422 `BITRIX24_BOT_IDENTITY_MANAGED`.
+- `crm_behavior.use_cross_platform_history`: канальный выбор истории одного человека
+  между каналами; `false` передаётся явно, omission сохраняет прежний выбор.
+
+Все разделы отправляются одним PATCH. Неверный тип канала даёт 400, отсутствие
+подключения, неверный sender и отсутствие подтверждения — адресный 422. Ошибка не
+означает частично сохранённую настройку. `bitrix24BotSettingsApply` различает
+сохранение и применение у провайдера; неизвестное/отложенное применение не является
+подтверждённым успехом провайдера.
+
+Создание и изменение агента, клонирование и чтение ICP сохраняют прежние обязательные
+поля. Необязательный `default_icp_profile_id` передаётся как раньше; явный null в
+изменении агента сохраняется. Прямой POST связи ICP не добавлен. Конфликт 409 не
+вызывает автоматический PATCH или DELETE→POST.
+
+Откат `besales_audit_revert` передаёт необязательное `explicit_confirmation` в
+`explicitConfirmation` канального запроса. Опасное восстановление поведения,
+включая удаление строки и откат клона, требует отдельного согласия человека и
+значения `true`. Без него сервер возвращает `EXPLICIT_CONFIRMATION_REQUIRED`;
+безопасный откат проходит без подтверждения. Согласие исходной правки не является
+согласием на её откат. Workspace-вход сохраняется без изменений.

package/docs/pii-policy.md

@@ -1,20 +1,22 @@
 # Политика PII в Besales MCP
 
-Дата инвентаризации: 2026-09-11. Секреты и PII — разные контуры: browser handoff не отдаёт
-credentials модели, но разрешённые рабочие данные могут оказаться в транскрипте хоста.
+Секреты и PII — разные контуры: browser handoff не отдаёт credentials модели, но разрешённые
+рабочие данные могут оказаться в транскрипте хоста. Какие именно инструменты несут данные клиентов
+и как это помечено в определениях — [customer-data.md](customer-data.md); здесь — инвентарь
+поверхностей и правила.
 
 ## Инвентарь
 
 | Поверхность | Возможные данные | Зачем нужны | Политика |
 |---|---|---|---|
-| dialogue query/transcript | имя, username/телефон, сообщения, CRM-ссылки | аудит, диагностика, ICP | list по умолчанию краткий; полный transcript только явным get и под `read:conversations` |
-| ICP dialogue samples | реплики, outcome, признаки контакта | анализ сегментов и скрипта | import с anonymize по умолчанию; raw источник не копировать в task state |
-| wave contacts / run contacts | contact ID, messenger, статус доставки, причина отказа | dry-run, восстановление рассылки | scope кампаний; страницы; не эхоить весь вход после записи |
+| dialogue query/transcript | имя, username/телефон, сообщения, CRM-ссылки | аудит, диагностика, ICP | список краткий, тексты — отдельным явным вызовом `besales_dialogue_transcript`; оба под `read:conversations` |
+| ICP dialogue samples | реплики, outcome, признаки контакта | анализ сегментов и скрипта | импорт принимает `anonymize` только со значением `true`; raw источник не копировать в task state |
+| wave contacts / run contacts | contact ID, messenger, статус доставки, причина отказа | dry-run, восстановление рассылки | право `mcp:platform-setup`; страницы; не эхоить весь вход после записи |
 | findings/evidence | выдержки сообщений, оценки, scenario evidence | объяснить качество | возвращать минимальный фрагмент, нужный для вывода; полный источник получать точечно |
-| link clicks | имя контакта, contact/message IDs, время | атрибуция | описание инструмента явно предупреждает о PII; отдельный scope conversations |
-| workspace labels | название компании, email владельца | выбор подключения | email только маскированный; label cache не хранит raw email |
-| API keys/webhook secrets | credentials | подключение канала | только одноразовый browser reveal; рекурсивно удаляются из MCP result/log |
-| structured errors | operation/object ID, service account email, remediation | продолжение после сбоя | whitelist; неизвестные поля и payload бэкенда наружу не проходят |
+| link clicks | имя контакта, contact/message IDs, время | атрибуция | описание инструмента предупреждает о PII; права `read:analytics` и `read:conversations` вместе |
+| workspace labels | название компании, подпись аккаунта | выбор подключения | подпись приходит от сервера уже маскированной; индекс подключений raw email не хранит |
+| API keys/webhook secrets | credentials | подключение канала | только одноразовый browser reveal; из ответов инструментов удаляются поля-credentials, из лога — поля-секреты по имени на любой глубине |
+| structured errors | operation/object ID, service account email, remediation | продолжение после сбоя | whitelist безопасных полей; неизвестные поля и payload бэкенда наружу не проходят |
 
 ## Правила
 
@@ -26,7 +28,8 @@ credentials модели, но разрешённые рабочие данны
    требует доставку конкретному человеку или разбор конкретного сообщения, удаление ID разрушило
    бы разрешённую функцию; доступ ограничивается scope и минимальным ответом.
 4. MCP не пишет raw dialogue, contact list или findings в локальный progress/task payload.
-   Допустимы только IDs созданных сущностей, агрегаты, checkpoints и согласованные ограничения.
+   Допустимы только IDs созданных сущностей, агрегаты, checkpoints и согласованные ограничения
+   ([task-state.md](task-state.md)).
 5. Host transcript и telemetry находятся под retention-политикой выбранного хоста. MCP не может
    удалить уже переданный ему текст; поэтому перед полным чтением описания предупреждают о PII,
    а оператор выбирает корпоративный host/retention. Экспорт в сторонний файл выполняется только
@@ -34,13 +37,15 @@ credentials модели, но разрешённые рабочие данны
 6. Ошибка не должна удалять полезную безопасную диагностику: `serviceAccountEmail`, operation ID,
    missing scope и remediation сохраняются. Сырые stack, токены, webhookSecret, apiKey и headers
    удаляются.
-7. Локальные логи маскируют email/телефоны/ключи; тесты проверяют вложенные объекты, массивы и
-   ошибки, а не только top-level поля.
+7. Вызов API в логе моста — это метод, путь (с замаскированными секретами) и статус; тела
+   запросов и ответов инструментов в лог не пишутся. Поля-секреты в любых логируемых объектах
+   заменяются на любой глубине, включая массивы (`src/utils/logger.ts`); список ведётся от
+   обратного — имена секретов, а не имена безопасных полей.
 
 ## Retention и удаление
 
 API-источники живут по профильным retention/GDPR правилам домена. MCP resources и tool schemas
-не содержат customer PII. Keychain хранит credentials до disconnect/revoke. Кэш подключения
-хранит только workspace ID/name, маскированный account label, scopes и timestamps. Потерянный
-browser reveal не восстанавливается из MCP-транскрипта: пользователь выпускает новый credential
-только осознанно, понимая отзыв прежнего.
+не содержат customer PII. Keychain хранит credentials до disconnect/revoke. Индекс подключений
+хранит только workspace ID/name, префикс ключа, маскированную подпись аккаунта, выданные права и
+времена. Потерянный browser reveal не восстанавливается из MCP-транскрипта: пользователь
+выпускает новый credential только осознанно, понимая отзыв прежнего.