@besales/mcp 0.46.0 → 0.47.0

package/docs/help-navigation.md

@@ -0,0 +1,48 @@
+# Навигация по справке Besales MCP
+
+## Зачем нужен tool-мост
+
+Некоторые MCP-хосты показывают модели tools, но не передают список resources или не предлагают
+прочитать resource автоматически. Поэтому справка доступна двумя равноправными путями:
+
+- MCP resource по URI `besales://...`;
+- `besales_help_search` и `besales_help_get`, которые читают те же файлы пакета.
+
+В ответах tool-моста есть `version`, `source` и `complete`. Это позволяет отличить актуальную
+справку пакета от пересказа модели и понять, был ли получен весь документ или один раздел.
+
+## Поиск
+
+`besales_help_search({query})` принимает обычную русскую или английскую формулировку. Встроенные
+синонимы связывают лексику пользователя и продукта: «дожим» с follow-up, «волна» с broadcast,
+«бот молчит» с silence/handoff. Ответ разделяет найденные операции (`operations`) и документы
+(`results`). Для операции также возвращаются `score` и `matchedBy`: совпадение по имени или по
+пользовательскому намерению.
+
+Все активные инструменты получают короткую русскую формулировку намерения в описании, которое
+публикуется через `tools/list`. Английская часть сохраняется для существующих клиентов и поиска.
+Так модель может найти создание агента, изменение маршрутизации, запуск GetCourse-волны или
+финализацию промпта по обычному русскому запросу без знания технического имени инструмента.
+
+Поиск не вызывает API и не читает данные workspace. Если результатов нет, нужно уточнить объект
+или цель, а не угадывать имя инструмента.
+
+## Точечное и полное чтение
+
+`besales_help_get({uri})` возвращает индекс заголовков. Затем можно запросить один раздел через
+`section` или весь документ через `full=true`. Неоднозначный фрагмент заголовка возвращает список
+кандидатов; отсутствующий раздел возвращает `found=false`.
+
+Полная версия остаётся доступной, но для небольшой операции лучше читать один релевантный раздел.
+Содержимое resource и tool-ответа берётся из одного файла, поэтому две копии документа не
+расходятся.
+
+## Проверка
+
+- `src/tools/definitions/help.spec.ts` проверяет паритет русских и английских намерений, индекс,
+  раздел и полное чтение.
+- `src/tools/description-localization.spec.ts` не допускает активный инструмент без русской
+  формулировки в опубликованном описании.
+- `src/resources/registry.spec.ts` проверяет ссылки на реальные инструменты во всех resources и
+  коротких server instructions.
+- `src/server.spec.ts` проверяет публикацию server instructions через MCP initialize.

package/docs/host-compatibility-matrix.md

@@ -0,0 +1,153 @@
+# Матрица хостов, версий и установки
+
+Снимок: 2026-09-11. Это проверяемая граница текущего hardening, а не обещание для любого
+MCP-клиента.
+
+## Линии продукта
+
+| Линия | MCP | API | Источник API-контракта | Tool schema | Transport |
+|---|---|---|---|---|---|
+| main | `be-sales/mcp`, `codex/mcp-hardening-main-20260910`, `0.46.0` | `be-sales/back-main`, `codex/mcp-hardening-api-main-20260910`, `1.0.1` | loose `animaly/docs/specs/v2/contracts/openapi-besales-api.yaml` → `src/types/api-contract.gen.ts` | tracked `besales-mcp/src/schemas/mcp-tools.json`; build копирует его в dist | local stdio |
+| v2 beta | тот же GitHub repo, отдельная ветка `codex/mcp-hardening-v2-20260910`, `1.0.0-beta.1` | `be-sales/besales-api`, `codex/mcp-hardening-api-v2-20260910`, `0.0.1` | `besales-api/contracts/openapi-besales-api.yaml` → generated types | локальный `src/schemas/mcp-tools.json` + route export | local stdio |
+
+Main и v2 не взаимозаменяемы по совпадению имени файла. Изменение переносится только после
+сверки route, DTO, scope, ответа и теста своей пары.
+
+Общий loose `docs/specs/v2/contracts/mcp-tools.json` является целью v2 registry publish и больше
+не копируется внутрь main. Это устраняет перезапись канона одной линии контрактом другой; main
+проверяет собственный tracked schema, v2 публикует свой schema в явно выбранные targets.
+
+## Поддерживаемые хосты этой итерации
+
+| Хост | Проверенная версия | Фактическое поведение | Статус |
+|---|---|---|---|
+| MCP SDK / Inspector | SDK из lockfile, raw stdio | полный initialize; main: 253 tools / 38 resources / 5 prompts, v2: 213 / 38 / 5; schema validation до HTTP | блокирующий protocol gate |
+| Codex CLI / App | `codex-cli 0.153.4` | один сервер `besales`; tools могут грузиться отложенно; resources модели не гарантированы, поэтому есть `besales_help_*` | поддержан |
+| Claude Code | `2.1.220` | stdio подключён; видит tools/resources/prompts; server instructions режет **4123 → 2048 символов** | поддержан с полезным префиксом и help-tools |
+| Claude Desktop | app `1.49585.0` | local stdio; два намеренно разных подключения `besales-tg` и `besales-ksamata`, каждое прибито к своему workspace | поддержан; ручной UI smoke после установки |
+
+Новый неизвестный хост не становится блокирующим автоматически. Для него сначала повторяются
+raw initialize/list/read/call и модельная оценка.
+
+## Протокольное доказательство main
+
+Артефакт: `docs/evidence/2026-09-11-main-wire-protocol.json`.
+
+- initialize: `@besales/mcp 0.46.0`, instructions 4123 символа / 6532 UTF-8 байта;
+- capabilities: tools, resources, prompts;
+- tools/list: 253 уникальных имени, 418380 байт;
+- resources/list: 38; каждый URI реально прочитан и снабжён SHA-256;
+- prompts/list: 5;
+- пустой `besales_agent_create` отклонён MCP кодом `-32602` до HTTP: отсутствуют
+  `platform_id`, `name`, а `model_lane` не входит в `CHEAP|STANDARD|DEEP`;
+- wire schema сохраняет required, UUID format, enums, вложенные объекты и
+  `const: true` + `type: boolean`.
+
+Скрипт повторения: `yarn build && yarn host:probe bin/besales-mcp.js <output.json>`.
+
+## Протокольное доказательство v2 beta
+
+Артефакт в v2 checkout: `docs/evidence/2026-09-11-v2-wire-protocol.json`.
+
+- initialize: `@besales/mcp 1.0.0-beta.1`, instructions 4122 символа / 6538 UTF-8 байт;
+- tools/list: 213 уникальных имён, 322105 байт; resources/list: 38; prompts/list: 5;
+- все resources прочитаны, representative schemas сохранены, пустой `besales_agent_create`
+  отклонён кодом `-32602` до API теми же обязательными полями;
+- снимок собран из v2 MCP `912a70a`; API-зависимые main tools в него не копировались.
+
+## Что видит модель
+
+У установленной до hardening main-версии Codex App было 215 активных tools. Старый сервер
+добавлял полный текст инструкций в описание каждого tool: 22385 символов у одного описания,
+4747836 символов суммарно. Это подтверждённый дефект версии, а не лимит MCP.
+
+Новая версия передаёт инструкции один раз через initialize. В первых 2048 символах, которые
+оставляет проверенный Claude Code, находятся:
+
+1. `besales_workspace_current` и выбор компании по названию;
+2. overview → точечный platform context;
+3. `besales_help_search` → `besales_help_get`;
+4. запрет одинакового повторного read и конкретный следующий шаг;
+5. запрет секретов в чате и начало правила подтверждений.
+
+Глубокие правила после этой границы остаются доступны через тот же registry ресурсов и
+`besales_help_search` / `besales_help_get`; модель не зависит от UI resources конкретного хоста.
+
+Повторная проверка model-eval 2026-09-11 отозвала прежний сравнительный PASS:
+все 15 baseline-прогонов были заблокированы политикой approvals хоста до выполнения fixture.
+Сопоставимого baseline нет; улучшение времени, токенов или успешности не доказано.
+Current отдельно дал 14/15 успешных маршрутов и чтение справки в 12/15 на пяти fixture-сценариях
+(`gpt-5.6-luna`, reasoning `low`, три повтора). Это не проверка production API или всех workflows.
+Scorer пересчитывает метрики из исходных calls/events и учитывает только успешные ответы;
+approval-blocked read не считается мутацией. UPD-048 открыт до сопоставимой серии.
+Raw JSONL сохранён в `docs/evidence/model-eval-2026-09-11/`.
+
+Claude Code debug подтвердил stdio connection и capabilities tools/resources/prompts, а также
+точный лимит instructions 2048. Модельный ответ не получен: аккаунт вернул 429 weekly limit до
+первого token. Это ограничение хоста/аккаунта, не ошибка MCP; raw protocol и command discovery
+остаются валидны. В Claude Code prompts появляются как
+`/mcp__besales__besales_setup_agent` и аналогичные команды. Обычный текстовый запрос остаётся
+основным и полностью эквивалентным входом.
+
+## Подключения и дубли
+
+Наблюдавшиеся «3 сервера / 642 записи» не являются тремя случайными копиями в одном каталоге:
+
+- Codex имеет один `besales`;
+- Claude Code имеет один `besales`;
+- Claude Desktop имеет два purpose-specific сервера для разных workspace.
+
+Удалять их автоматически нельзя: это уничтожило бы выбор компании. Случайным дублем считается
+только повтор одного executable, API URL и workspace pin внутри одного host. Миграция:
+
+1. оставить по одному имени на уникальную тройку executable/API/workspace;
+2. обновить executable на проверенный пакет;
+3. перезапустить host и вызвать `besales_workspace_current`;
+4. удалить старую запись вручную лишь после успешного smoke новой.
+
+Профиль `BESALES_MCP_TOOLSETS` уменьшает поверхность одного сервера и одинаково ограничивает
+list и call; help возвращает скрытые совпадения отдельно, не выдавая их за вызываемые. Профиль не
+заменяет workspace pin и не объединяет разные компании.
+
+## Scopes
+
+| Линия | Запрашивает MCP | Поддерживает API | Фактически выдаёт |
+|---|---|---|---|
+| main | `mcp:* mcp:platform-setup mcp:funnel-test read:campaigns launch:campaigns read:contacts write:operators` | тот же ratchet-набор | consent-набор с учётом прав пользователя; exchange возвращает `scopes` и `dropped_scopes` |
+| v2 beta | `mcp:* mcp:platform-setup read:contacts` | та же тройка; `read:platform-setup` входит в composite read | consent выдаёт только поддержанный v2-набор |
+
+`besales_workspace_current.effective_scopes` берётся из конкретного выбранного credential.
+Union других ключей workspace не используется. 403 сохраняет названный API недостающий scope;
+reconnect добавляет права и не должен сужать прежние. Main и beta не копируют scope-set друг
+друга.
+
+## Установка, обновление, отзыв
+
+Поддержанный пользовательский путь сейчас — local stdio и browser OAuth:
+
+1. host запускает `npx -y @besales/mcp@<проверенная-версия>` либо pinned локальный executable;
+2. `besales-mcp connect` открывает browser consent; секрет в чат не копируется;
+3. `besales-mcp status` и `besales_workspace_current` показывают подключение;
+4. обновление: поменять версию/executable, перезапустить host, повторить raw smoke;
+5. reconnect нужен для протухшего credential или новых scopes, а не для неоднозначного выбора;
+6. отзыв выполняется в настройках подключения, затем проверяется 401 именно этого workspace.
+
+Keytar остаётся частью local distribution и хранит ключи в системном credential store. Remote
+HTTP/OAuth не вводится в этом инкременте: для него нет ратифицированной модели размещения,
+tenant routing и миграции локальных ключей. Возвращаться к нему следует, когда появится
+server-side host и отдельный threat model. Перенос аккаунта выполняется новым browser connect;
+credential store не копируется между машинами.
+
+## Выпуск
+
+- Аддитивные tools/resources/prompts совместимы в minor main и beta build.
+- Новые обязательные поля, default limits и форма результата требуют отдельного rollout.
+- `BESALES_MCP_RESULT_ENVELOPE=on` включает одинаковые text/structuredContent и outputSchema;
+  default остаётся off один совместимый релиз.
+- main и `1.0.0-beta.1` не публикуются на один dist-tag.
+- Публикация и деплой в этот документ не входят. После публикации обязателен smoke реально
+  установленного пакета после полного restart host; локальный worktree smoke его не заменяет.
+
+Официальное отображение prompts в Claude Code: MCP prompt становится командой
+`/mcp__<server>__<prompt>`; resources доступны через `@server:uri`. Источник:
+https://code.claude.com/docs/en/mcp

package/docs/host-setup.md

@@ -80,9 +80,18 @@ node bin/besales-mcp.js connect          # workspace B (re-login in the browser
 node bin/besales-mcp.js connections      # list all connections, marks the active one
 ```
 
+The connection index includes the workspace name and a masked account label.
+`besales_workspace_current` refreshes missing or day-old labels through the
+lightweight `/auth/mcp-context` endpoint and reports `current`, `cached`, `stale`,
+or `unknown` with `label_updated_at` and a safe refresh reason. This migrates
+legacy entries without six full overview calls. Reconnecting also refreshes
+credentials and labels, but does not choose between several unpinned workspaces.
+
 Workspace-level tools default to the session's workspace; users should not be
-asked to provide `workspace_id`. Pin a session with `BESALES_WORKSPACE_ID` in the
-host's `env` block, or set the global default with `besales-mcp use <workspaceId>`.
+asked to find or type `workspace_id`. Show the names returned by
+`besales_workspace_current`, then pass the selected UUID to `besales_workspace_use`.
+Pin a session with `BESALES_WORKSPACE_ID` in the host's `env` block, or set the
+global default with `besales-mcp use <workspaceId>`.
 See the package README "Multiple Workspaces" section for the full precedence.
 
 For MCP protocol smoke without live auth, use the local mock API:
@@ -120,12 +129,17 @@ BESALES_API_BASE_URL=http://localhost:3000/api/v2 \
 BESALES_API_BASE_URL=http://localhost:3000/api/v2 \
   yarn dlx @modelcontextprotocol/inspector --cli --method resources/list \
   node bin/besales-mcp.js
+
+BESALES_API_BASE_URL=http://localhost:3000/api/v2 \
+  yarn dlx @modelcontextprotocol/inspector --cli --method prompts/list \
+  node bin/besales-mcp.js
 ```
 
 Expected:
 
-- 145 tools are listed.
-- 31 resources are listed.
+- 248 tools are listed.
+- 38 resources are listed.
+- 5 optional task prompts are listed.
 - `besales://concepts/external-execution` opens.
 - A direct tool, for example `besales_icp_create`, reaches `ai-aniomaly`.
 - An external pair returns instructions and accepts submit.
@@ -230,6 +244,8 @@ are present, then run:
 
 1. One direct tool (`besales_icp_create`).
 2. One external pair (`*_get_instructions` then matching `*_submit`).
+3. A natural-language help request through `besales_help_search`, followed by one section through
+   `besales_help_get`. This check is required when the host does not expose resources to the model.
 
 For the ICP analysis pair, `besales_icp_analysis_submit` personas must include
 `segment_id`. Use either an existing ICP segment id or the `id` of a segment in
@@ -243,7 +259,7 @@ session may need an app/session restart before new tools appear.
 Codex App can defer MCP tool schemas until the model searches for them. This is
 host behavior, not a `besales-mcp` server problem: `codex mcp list/get besales`
 and MCP Inspector `tools/list` are still the source checks for whether the
-server is installed and exposing all 145 tools.
+server is installed and exposing all 248 tools.
 
 User-facing prompts must stay natural. Users should ask for the business action,
 for example:
@@ -264,7 +280,7 @@ Use this matrix for local validation before staging/prod checks.
 
 | Host | Config check | Protocol check | Direct tool | External pair |
 |---|---|---|---|---|
-| MCP Inspector | command launches | 145 tools / 31 resources | `besales_icp_create` | instructions -> submit |
+| MCP Inspector | command launches | 248 tools / 38 resources / 5 prompts | `besales_icp_create` | instructions -> submit |
 | Claude Desktop | config JSON has `besales` | server connected | `besales_icp_create` | instructions -> submit |
 | Claude Code | `claude mcp list` has `besales` | `/mcp` connected | `besales_icp_create` | instructions -> submit |
 | Codex CLI | `codex mcp list` has `besales` | new session sees tools | `besales_icp_create` | instructions -> submit |

package/docs/operation-coverage.md

@@ -0,0 +1,114 @@
+# Покрытие пользовательских операций
+
+Снимок main: 2026-09-11. Единица — пользовательская операция, а не страница UI. Статусы:
+**full** — есть MCP read/write и проверка; **partial** — часть пути требует UI или нет полного
+lifecycle; **missing API** — безопасного `/api/v2` контракта нет; **intentional** — действие
+сознательно не публикуется.
+
+## Матрица
+
+| Область / операция | MCP | API `/api/v2` | Scope / эффект | Проверка | Статус и решение |
+|---|---|---|---|---|---|
+| workspace / platform / agents | overview, context sections, agent search/get/create/update | есть | setup scopes; read/write | повторный get/context | full |
+| prompt / ICP / sandbox | direct + 7 external pairs + lifecycle | есть | read/write/spend | lint, version, run status/findings | full; draft-bound sandbox см. отдельное решение |
+| knowledge / workbook | CRUD, page read, classification, archive, reindex status | есть | read/write | fingerprint, get/status | full |
+| CRM / pipelines / fields | setup, list/get/upsert, mapping, operators CRM | есть | setup scopes; read/write | health/get/list | full; CRM operator не workspace operator |
+| data sources / 1С | setup/status/list/health/catalog/roles/vectorize | есть | setup scopes; health пишет status | status/health/catalog | partial: catalogs API без cursor |
+| follow-up | sequences, step stats, reactions, funnel test | есть | read/write/spend | list/stats/run status | full для текущего API |
+| outgoing waves / scheduler | preview/import/status, schedules, cohorts, analytics | есть | campaign scopes; spend | status/analytics | partial: несколько legacy lists без cursor |
+| incoming analytics | summary/topics/speed/money/cycle/quality | есть, делегирует UI service | `read:analytics`, read | те же DTO и canonical totals | full для агрегатов; person drill-down отдельно |
+| funnel analytics | meta/summary/cohorts | есть, делегирует UI service | `read:analytics`, read | тот же view/period/grain, что UI | full для основных агрегатов |
+| custom reports | list/get/run | есть | `read:analytics`, read | report definition + grandTotal | full для чтения; person drill-down отдельно |
+| AI ledger / costs | summary/tasks/breakdown | есть, делегирует `AiUsageService` | `read:analytics`, read | ledger totals + unpricedEvents | full для чтения; прайс модели не замена ledger |
+| operational overview | цепочки, расписания, jobs, action errors, условная operator queue | есть | `read:analytics`; queue ещё `read:conversations` | due/heartbeat + drill-down | full для сводки; детальные chats/operators ниже |
+| contacts | search/detail/diagnostics + dialogue transcript | list/detail/messages/state/history есть | contacts/conversations, read | detail/history/diagnostics | full для read-only работы |
+| chats / operator queue | dialogue query/transcript + paginated queue | есть | `read:conversations` | status + PlatformWorkLog evidence | full для чтения и поиска |
+| workspace operators / assignment | list/get/set | есть | read conversations / отдельный `write:operators` | CAS + повторный assignment get | full; CRM operators не смешиваются |
+| message campaigns | waves/scheduler покрывают GetCourse/Wazzup flows | общего transport-neutral v2 adapter нет | campaign read/manage/spend | preview/status/analytics | partial; не смешивать с telephony campaigns |
+| templates / audiences | Wazzup templates only | generic v2 API отсутствует | future campaign scopes | list/get | missing API, P2 |
+| telephony | trigger actions и voice billing не равны управлению | trunks/numbers/calls API есть | read/write telephony | validate/get/call status | partial, P2 MCP definitions |
+| dialogue topics | нет | v2 adapter отсутствует | future conversations read/write | list/get | missing API, P2 |
+| satisfaction | нет | v2 adapter отсутствует | future analytics read | canonical UI query | missing API, P2 |
+| arbitrary message send | нет | внутренние routes есть | внешний side effect | delivery receipt | intentional: не публиковать без отдельного auth/threat model |
+| raw secrets / internal admin | нет | internal only | destructive/security | browser/admin audit | intentional |
+| длительная задача MCP | create/list/get/update/close/delete | локальный owner, API не нужен | workspace-scoped local write | version CAS + fresh object reads | full на одной машине; межмашинного sync нет |
+
+«9 analytics endpoints» не подтверждается контрактом как девять MCP-ready операций. После
+проверки main содержит 12 read-only маршрутов incoming/funnel/AI-ledger, три маршрута custom
+reports и отдельный набор broadcast analytics. Они имеют разные зерно, права и семантику и не
+объединяются одним счётчиком.
+
+### Зависимости переноса аналитики в ветку v2
+
+Ветка v2 проверена отдельно 2026-09-11. В ней отсутствуют доменные сервисы и HTTP-контракты,
+которым делегируют main-адаптеры: `InboundAnalyticsService`, `FunnelAnalyticsService`,
+`AiUsageService` и `CustomReportsService`. Поэтому main MCP definitions не копируются в v2 до
+появления источника данных: оболочка без backend вернула бы пользователю неработающие tools.
+
+| Операция main | Что требуется в v2 до переноса | Критерий готовности |
+|---|---|---|
+| incoming analytics | canonical summary/topics/speed/money/cycle/quality service + `/api/v2` adapter | одинаковые period/timezone filters и totals с UI fixture |
+| funnel analytics | canonical meta/summary/cohorts service + `/api/v2` adapter | сохранены `view`, `grain`, cohort/period/entry и пустые интервалы |
+| AI ledger | immutable usage ledger query + `/api/v2` adapter | `unpricedEvents` и unknown usage не превращаются в ноль |
+| custom reports | definition list/get/run domain + `/api/v2` adapter | run использует сохранённую схему отчёта и возвращает canonical `grandTotal` |
+
+Для каждого блока v2 дополнительно нужны `read:analytics` в auth/OpenAPI/runtime constants,
+route-map generation, scope parity tests и protocol snapshot. До выполнения всех условий статус
+v2 для этих операций — `missing API`, а не частичное покрытие.
+
+## Пагинация и полнота
+
+| Класс list/read | Состояние | Правило клиента |
+|---|---|---|
+| ICP, sandbox runs, agents, variables, dialogues, audits | cursor | передавать query; идти до пустого cursor; page не равна парку |
+| knowledge docs/QA/websites/tables | page + limit | сохранять page/total/hasMore API; не обрезать конвертом |
+| files/tracked clicks | offset + limit | завершать по total/returned count |
+| wave contacts | cursor/limit | contact page не заменяет весь run |
+| CRM pipelines/stages | bounded provider/domain list, API cursor нет | не усекать; при превышении бюджета fail-closed |
+| follow-up step stats/reactions | агрегат по шагам/типам, API cursor нет | не объявлять неизвестный total точным |
+| datasource catalogs, Wazzup templates, feedback sheets | API cursor нет | технический gap; result не считать полным при `_mcpTruncated` |
+| cohorts, schedules, mailing variants | API cursor нет | технический gap; сужать фильтрами, где они есть |
+
+`assertCompleteList` запрещает использовать legacy unpaged ответ как полный, когда API вернул
+cursor/hasMore, а caller не запросил страницу. GET-параметры строятся через `URLSearchParams` в
+path; `ApiToolRequest` не имеет отдельного query и молча потерял бы параметры.
+
+## Замещающие записи
+
+Четыре snapshot-класса защищены `neverTruncate`: trigger actions/platform context, agent variable
+overrides, follow-up config и CRM field mapping. Agent/context имеют sections и detail tools.
+Если полный снимок недоступен, MCP возвращает исполнимый отказ и не выполняет replace. Проверки
+версии/`expected_content` сохраняются; page/sample/stale fingerprint не принимаются за полный
+набор.
+
+## Принятые продуктовые решения
+
+- Incoming/funnel analytics и AI ledger имеют отдельные API contracts и MCP tools. Broadcast
+  totals не используются как заменитель; unknown/unpriced остаются отдельными.
+- Workspace operator queue строится по `PlatformWorkLog`, а не по текущему snapshot status.
+- Generic templates/audiences, topics и satisfaction отложены до появления scoped v2 adapter.
+- Telephony публикуется отдельным профилем после проверки recording/transcript PII и spend;
+  существующие телефонные trigger actions не считаются покрытием.
+- Composite prompt edit не добавляется: одиночный `prompt_batch_start` уже даёт durable run,
+  idempotency, skippedCount и resume; сначала всё равно нужен полный prompt read.
+
+### Оставшиеся области интерфейса
+
+Проверено по main API 2026-09-11. Решение «отложено» означает конкретную недостающую границу,
+а не исчезновение области из MCP-плана.
+
+| Область | Что уже есть | Чего не хватает | Решение сейчас | Условие пересмотра |
+|---|---|---|---|---|
+| message campaigns | GetCourse/Wazzup waves, cold welcome, scheduler, cohorts и broadcast analytics | единого v2 CRUD/lifecycle для transport-neutral кампании, шаблона и аудитории | не публиковать фиктивный generic tool; продолжать поддержанные специализированные маршруты | scoped v2 adapter с preview, idempotency, pause/cancel/status и delivery verification для каждого транспорта |
+| templates | чтение Wazzup templates в рамках Wazzup wave | общего template list/get/CRUD API и канонической схемы переменных разных каналов | оставить Wazzup-чтение внутри его маршрута | v2 API отделяет channel template от message body, проверяет approval/media/variables и даёт безопасный preview |
+| audiences | файловые когорты и контакты конкретных wave/import flows | самостоятельного audience list/get/definition API с доказуемой полнотой нет | не выдавать импортный файл за сохранённую аудиторию | cursor API, источник/версия выборки, expected count и повторная проверка перед spend |
+| telephony | v2 API для trunks/numbers/calls/call lists/voice agents/telephony campaigns; trigger-actions могут начать звонок | отдельной MCP-поверхности и проверенного профиля для recording/transcript PII, spend и feature flags нет | отложить как самостоятельный профиль; телефонные trigger-actions не считать полным покрытием | threat model, scopes `read:telephony`/`write:telephony`, redaction/retention, spend confirmation и lifecycle eval готовы вместе |
+| dialogue topics | внутренний v1 CRUD, channel assignment и async backfill | scoped `/api/v2` adapter, MCP read/write и status/cancel contract отсутствуют | отложить, не вести модель к внутреннему URL | v2 read/write scopes, cursor list, channel ownership и retained backfill lifecycle |
+| satisfaction | внутренние v1 summary/list и capture/dispatch domain | scoped `/api/v2` analytics adapter и MCP read contract отсутствуют | отложить до read-only adapter; автоматический dispatch наружу не публиковать | period/timezone filters, response-mode/status semantics и unknown totals совпадают с UI fixtures |
+
+## Проверка параметров вариантов аналитики
+
+`besales_funnel_analytics_get`: meta принимает только platform, cohorts не принимает view
+(всегда cohort), summary поддерживает view. `besales_ai_costs_get`: group_by/page/limit
+доступны только для breakdown. Неприменимые параметры отвергаются до HTTP; фильтр не
+отбрасывается молча. Проверка: `src/tools/definitions/analytics.spec.ts`.

package/docs/pii-policy.md

@@ -0,0 +1,46 @@
+# Политика PII в Besales MCP
+
+Дата инвентаризации: 2026-09-11. Секреты и PII — разные контуры: browser handoff не отдаёт
+credentials модели, но разрешённые рабочие данные могут оказаться в транскрипте хоста.
+
+## Инвентарь
+
+| Поверхность | Возможные данные | Зачем нужны | Политика |
+|---|---|---|---|
+| 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 кампаний; страницы; не эхоить весь вход после записи |
+| 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 бэкенда наружу не проходят |
+
+## Правила
+
+1. Tenant/workspace/object ownership проверяет API. Локальный MCP не расширяет scope и не
+   объединяет права нескольких ключей.
+2. Поиск и list возвращают идентичность и краткое состояние. Текст диалога, полный prompt,
+   evidence и контакты читаются отдельным явным вызовом.
+3. Для анализа без нужды в идентичности используется анонимизация/псевдонимизация. Когда задача
+   требует доставку конкретному человеку или разбор конкретного сообщения, удаление ID разрушило
+   бы разрешённую функцию; доступ ограничивается scope и минимальным ответом.
+4. MCP не пишет raw dialogue, contact list или findings в локальный progress/task payload.
+   Допустимы только IDs созданных сущностей, агрегаты, checkpoints и согласованные ограничения.
+5. Host transcript и telemetry находятся под retention-политикой выбранного хоста. MCP не может
+   удалить уже переданный ему текст; поэтому перед полным чтением описания предупреждают о PII,
+   а оператор выбирает корпоративный host/retention. Экспорт в сторонний файл выполняется только
+   по явной просьбе.
+6. Ошибка не должна удалять полезную безопасную диагностику: `serviceAccountEmail`, operation ID,
+   missing scope и remediation сохраняются. Сырые stack, токены, webhookSecret, apiKey и headers
+   удаляются.
+7. Локальные логи маскируют email/телефоны/ключи; тесты проверяют вложенные объекты, массивы и
+   ошибки, а не только top-level поля.
+
+## 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
+только осознанно, понимая отзыв прежнего.

package/docs/response-size-budget.md

@@ -0,0 +1,150 @@
+# Бюджет размера ответов
+
+Сколько на самом деле весят ответы инструментов, какой потолок из этого следует и почему
+у части инструментов потолка нет вовсе.
+
+Единица везде — **байты UTF-8** (`Buffer.byteLength`). Считать длину строки нельзя:
+`String.length` меряет единицы UTF-16, и на кириллице ошибается вдвое.
+
+## Зачем это нужно
+
+Ответ инструмента целиком попадает в контекст модели, которая его вызвала. Один ответ
+на несколько сотен килобайт вытесняет из контекста всё остальное — включая инструкции,
+по которым модель должна была работать. До замера потолок назначать нельзя: цена байта
+в токенах различается **в 2,5 раза** (плотный список идентификаторов ≈ 2 байта на токен,
+русский текст ≈ 4–5), поэтому «круглое число на глаз» означает либо мёртвый предохранитель,
+либо срабатывание на штатных ответах.
+
+## Как замерялось
+
+Прогон только на чтение по инструментам с методом GET на четырёх живых воркспейсах,
+190 успешных ответов. Инструменты, чей адрес в v2 переехал и на живом бэкенде не отвечает,
+измерялись отгруженным мостом: данные те же, меняется только адрес.
+
+Из прогона исключены два GET-инструмента, которые вопреки методу меняют состояние:
+проверка живости источника данных (успех переводит источник в активное состояние) и
+список операторов CRM с включённой пересинхронизацией.
+
+## Распределение
+
+| Доля ответов | Вес |
+|---|---|
+| половина | до 1 КБ |
+| три четверти | до 6 КБ |
+| 90 % | до 31 КБ |
+| 95 % | до 51 КБ |
+| 99 % | до 620 КБ |
+| максимум | **7,96 МБ** |
+
+Компактный JSON против отформатированного: медиана **−16 %**, на самых тяжёлых ответах
+до **−35 %**. Экономия реальная, но она не спасает: ответ на 8 МБ остаётся неработоспособным
+и после сжатия.
+
+## Самые тяжёлые ответы
+
+| Инструмент | Максимум | Из чего состоит |
+|---|---|---|
+| снимок канала (`platform_context_get`) | **7 959 506** | 40 агентов × ~197 КБ; у каждого системный промпт 143 КБ (72 % веса) и триггеры 54 КБ |
+| аналитика рассылок (`broadcast_analytics_get`) | **1 340 671** | `data` 897 КБ + `totals` 437 КБ |
+| когорты рассылок (`broadcast_cohorts_list`) | **634 625** | `items` 634 КБ, постранично не разбивается |
+| сценарии ICP (`icp_scenarios_list`) | 119 181 | голый массив без конверта |
+| карта полей CRM (`crm_field_mapping_get`) | 77 597 | `available_fields` 77 КБ, а сам снимок для записи (`current_mappings`) — 2 байта |
+| воронки CRM (`crm_pipeline_list`) | 74 523 | `items` |
+| список агентов (`agent_list`) | 73 859 | `data` |
+| кандидаты оплат | 52 348 | `items`, 30 строк |
+| вопросы-ответы базы знаний | 42 793 | `qa_pairs` |
+| выборка диалогов | 33 747 | `data`, 50 строк |
+| стенограмма диалога | 33 672 | `turns` 18,8 КБ **и** `transcriptMarkdown` 11,3 КБ — одно и то же содержимое дважды |
+
+Ресурсы (справочники, отдаются целиком одним чтением): 37 файлов, медиана 4 КБ,
+максимум **104 836** байт — принципы промптинга. Инструкции сервера, уходящие при каждом
+подключении, после выноса подробностей в resources/help — 5 112 байт (3 278 символов).
+
+## Три класса и потолки
+
+### 1. Обычные ответы — 64 КБ
+
+Покрывает 95 % замеренных ответов с запасом. Всё, что не попало в два класса ниже.
+
+### 2. Отчёты, которые можно сузить — 64 КБ с выбрасыванием строк
+
+Аналитика и когорты рассылок. У обоих есть параметры сужения (период, канал, срез),
+поэтому подсказка «сузьте запрос» — правда, а не выдумка. Выбрасываются именно строки
+данных, по пути, а не «самое тяжёлое поле».
+
+### 3. Снимки для замещающей записи — потолка нет, есть отказ
+
+Четыре чтения, чей ответ модель отправляет обратно как «полный набор»:
+
+| Чтение | Запись, замещающая набор целиком |
+|---|---|
+| снимок канала | правка триггера с заменой действий |
+| переопределения переменных агента | обновление агента |
+| список цепочек дожима с конфигом | сохранение цепочки |
+| карта полей CRM | сохранение карты с заменой |
+
+Молча усечённый снимок здесь означает **безвозвратную потерю**: модель добросовестно
+пришлёт назад неполный набор, и непрочитанное будет удалено. Автоматического возврата
+у этих операций нет. Поэтому обрезка запрещена, а при превышении возвращается отказ
+с указанием, чем сузить запрос.
+
+Тот же запрет — на инструменты, у которых постраничная выдача уже работает
+(стенограмма, выборка диалогов, контакты волны): конверт подменил бы исправный механизм
+тихой потерей.
+
+**Порог отказа — 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`.
+Замещающая правка по-прежнему требует полного снимка относящейся к ней секции.
+
+## Как это включается
+
+Потолок включается переменной окружения `BESALES_MCP_RESULT_ENVELOPE=on` и по умолчанию
+**выключен**. Причина — установки: пакет рекомендуется запускать без пина версии, поэтому
+правка доезжает до всех сама, посреди рабочих сессий. Один релиз выключенным, включение —
+следующим. Компактная сериализация работает всегда: она меняет только пробелы.
+
+В том же совместимом флаге включается MCP `outputSchema`. При включении каждый успешный
+ответ получает одинаковый JSON в `content[].text` и `structuredContent`; массив
+оборачивается в `{ "items": [...] }`, скаляр — в `{ "value": ... }`. Поэтому SDK-хост
+проверяет реально возвращаемую форму, а старые клиенты до переключения флага продолжают
+получать прежний текстовый контракт.
+
+Путь после успешного API-ответа считается уже состоявшейся операцией. Если mapper,
+политика размера или сериализация ломаются после ответа на мутацию, MCP возвращает
+неошибочную квитанцию с доступными `id`/`operationId`/`runId`/`jobId` (включая вложенные
+поля) и маркером `_mcpPostprocessingFailed` либо `_mcpFormattingFailed`. Повторять такую
+мутацию нельзя. У чтения ошибка постобработки остаётся обычной ошибкой и допускает новый
+вызов.
+
+Политика объявляется у самого инструмента:
+
+- `neverTruncate` — обрезать нельзя, при превышении отказ;
+- `droppablePaths` — что разрешено выбросить, путём (`agents[].baseSystemPrompt` снимает
+  поле у каждого элемента массива); объявляется только для того, что читается **отдельным**
+  инструментом, иначе это потеря, а не сжатие;
+- `maxResultBytes` — свой потолок инструмента;
+- `narrowingHint` — чем сузить запрос; ставится только там, где сужать действительно есть чем.
+
+Списка «неприкосновенных путей» намеренно нет: выбрасывается ровно перечисленное, всё
+остальное неприкосновенно по построению. Второй список был бы полем, которое никто не читает.
+
+Маркеры в ответе начинаются с `_mcp`: у бэкенда есть собственные признаки усечения с другим
+смыслом, и совпадение имён их бы перемешало.
+
+## Когда пересматривать
+
+Если предохранитель начнёт срабатывать на штатных ответах — **поднимать потолок, а не
+выключать проверку**. Перед изменением чисел прогон замера повторяется: числа выше
+получены на конкретных воркспейсах и стареют вместе с данными.