@besales/mcp 0.48.0 → 1.0.0-beta.4

package/dist/tools/definitions/platform-setup-wave.js

@@ -0,0 +1,1079 @@
+import { withAgentModelNotice } from './agent-model-notice.js';
+import { z } from 'zod';
+import { assertCompleteList } from '../incomplete-list.js';
+import { withProjectedRoutingRules } from './routing-condition-projection.js';
+import { CHANNEL_AGENTS_MAX_PAGE_SIZE, compactObject, defineTool, uuidSchema, withInstructions, } from './shared.js';
+import { WAVE_TRANSPORTS } from './follow-up.js';
+import { WAVE_RUN_WELCOME_PAUSE_INSTRUCTION, WAVE_WELCOME_PAUSE_INSTRUCTION, } from './getcourse-wave-welcome.messages.js';
+// Помощники долгих прогонов волны GetCourse. Перенесены ДОСЛОВНО из отгружаемой линии пакета
+// (`src/tools/definitions/getcourse-wave.ts`): инструменты уже стоят у клиентов, и любое
+// расхождение формы здесь — молчаливое расхождение контракта.
+const waveFunnelSchema = z.string().max(200).describe('Передавай код школьной воронки fNN либо метку с этим кодом (f11 — ДБО). Без кода название образует отдельный ключ воронки. Не подставляй когорту, сегмент или подпись запуска: для них segment и cohort_label; продукт — product_code.');
+const normalizedWaveTransports = new Set(WAVE_TRANSPORTS.map((name) => name.toUpperCase()));
+const waveChannelsSchema = z.array(z.string()).min(1).superRefine((values, ctx) => {
+    // Как в API: проверяем нормализованное множество, отправляем исходное написание.
+    const normalized = new Set(values.map((value) => value.trim().toUpperCase()));
+    if (normalized.size > WAVE_TRANSPORTS.length) {
+        ctx.addIssue({ code: 'custom', message: 'Не больше 10 различных транспортов после нормализации' });
+    }
+    values.forEach((value, index) => {
+        if (!normalizedWaveTransports.has(value.trim().toUpperCase())) {
+            ctx.addIssue({ code: 'custom', path: [index], message: 'Неизвестный транспорт GetCourse' });
+        }
+    });
+}).describe('Полный перечень транспортов: Site, Email, SMS, Telegram, Facebook, VK, Chatium, WhatsApp, Viber, MAX. Проверяется множество после trim, приведения регистра и удаления дублей: от 1 до 10 транспортов. В API уходит исходное написание; API нормализует сам.');
+const BROADCAST_SEGMENT_DESCRIPTION_MAX_LENGTH = 4000;
+/** Предел поиска имени на серверной границе. */
+const CHANNEL_AGENT_QUERY_MAX_LENGTH = 120;
+const UNCERTAIN_WAVE_OUTCOME_INSTRUCTION = 'UNKNOWN и FAILED с неопределённым внешним исходом жёстко блокируются между волнами: repeat-режим и dedup_window_days=0 их не обходят. Повтор допустим только для FAILED, который подтверждённо возник до внешней отправки; остальные случаи требуют отдельного ручного разбора исхода.';
+const getCourseWaveContactSchema = z.object({
+    contact_id: z.string(),
+    deal_id: z.string().optional(),
+    transport: z.string().optional(),
+    dialog_id: z.string().optional(),
+    email: z.string().email().max(320).optional(),
+    phone: z.string().max(64).optional(),
+    first_name: z.string().max(200).optional(),
+    last_name: z.string().max(200).optional(),
+    lead_last_active_at: z.string().datetime({ offset: true }).optional(),
+    segment_entered_at: z.string().datetime({ offset: true }).optional(),
+});
+/**
+ * Два идентификатора человека в строке прогона — разные вещи, и выдача прогона — основание для переотправки. Карточка
+ * в поле номера ученика не пройдёт построчную проверку цифр: человеку ничего не уйдёт, а шаг станет отказом.
+ */
+export const WAVE_RUN_CONTACT_IDS_INSTRUCTION = 'contactId — карточка контакта Besales (UUID), getcourseUserId — номер ученика GetCourse. Для повторной отправки в contact_id подставляй getcourseUserId, не contactId.';
+const mapGetCourseWaveContact = (contact) => compactObject({
+    getcourseUserId: contact.contact_id,
+    dealId: contact.deal_id,
+    transport: contact.transport,
+    dialogId: contact.dialog_id,
+    email: contact.email,
+    phone: contact.phone,
+    firstName: contact.first_name,
+    lastName: contact.last_name,
+    leadLastActiveAt: contact.lead_last_active_at,
+    segmentEnteredAt: contact.segment_entered_at,
+});
+export const platformSetupWaveTools = [
+    defineTool({
+        name: 'besales_workspace_overview',
+        sideEffect: 'none',
+        closedWorld: true,
+        requiredFields: [],
+        defaultWorkspaceId: true,
+        schema: z.object({
+            workspace_id: uuidSchema.optional(),
+        }),
+        createRequest: (input) => ({
+            method: 'GET',
+            path: `/workspaces/${input.workspace_id}/overview`,
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Single-shot snapshot всего workspace: platforms (с agentsCount), ICP profiles (с segments/samples counts), feedback sheets, MCP connections summary.',
+            'Используй ПЕРВЫМ когда user задаёт open-ended вопросы вида "что у меня есть?" / "покажи мою настройку" — заменяет N round-trips.',
+            '`setupCompleteness` — readiness-сигнал «что недоделано»: channelsConnected/Pending, crmConnected, hasAnchorAgent, hasKnowledge, knowledgeLinkedToChannel, hasTriggers/Followups, hasIcp, lastSandboxRunAt, suggestedNextPhase. Используй suggestedNextPhase как мягкий hint следующего фокуса (не приказ); продолжай настройку с него, а не с нуля.',
+            'После overview перейди на drill-down: `besales_platform_context_get` для конкретной платформы, `besales_agent_list` для агентов внутри неё.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_workspace_navigate',
+        sideEffect: 'none',
+        closedWorld: true,
+        requiredFields: ['intent'],
+        defaultWorkspaceId: true,
+        resultPolicy: {
+            neverTruncate: true,
+            narrowingHint: 'Передайте известные platform_id, agent_id, contact_id или task_id; если requiredUserInput непуст, уточните перечисленные поля у пользователя.',
+        },
+        schema: z
+            .object({
+            workspace_id: uuidSchema.optional(),
+            intent: z.enum([
+                'CREATE_BOT',
+                'IMPROVE_AGENT',
+                'DIAGNOSE_CONTACT',
+                'AUDIT_DIALOGUES',
+                'CAMPAIGN_REPORT',
+                'CONNECT_CRM',
+                'CONNECT_DATASOURCE',
+                'CONFIGURE_FOLLOWUP',
+                'CONTINUE_TASK',
+                'FREEFORM',
+            ]),
+            bot_type: z.enum(['FAQ', 'SALES', 'BOOKING', 'OUTBOUND', 'SUPPORT', 'UNKNOWN']).optional(),
+            platform_id: uuidSchema.optional(),
+            agent_id: uuidSchema.optional(),
+            contact_id: uuidSchema.optional(),
+            task_id: uuidSchema.optional(),
+            question: z.string().trim().min(2).max(500).optional(),
+        })
+            .strict(),
+        createRequest: (input) => ({
+            method: 'POST',
+            path: `/workspaces/${input.workspace_id}/navigation`,
+            body: compactObject({
+                intent: input.intent,
+                botType: input.bot_type,
+                channelId: input.platform_id,
+                agentId: input.agent_id,
+                contactId: input.contact_id,
+                taskId: input.task_id,
+                question: input.question,
+            }),
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'next.tool и next.arguments — один адресный следующий шаг; placeholders перечислены в requiredUserInput и не должны угадываться.',
+            'Сохранённый overview — evidence только на момент ответа. Перед записью перечитай выбранный объект, а после записи выполни next.verifyWith.',
+            'CREATE_BOT учитывает bot_type: FAQ не требует ICP/CRM автоматически, SALES/BOOKING/OUTBOUND требуют ICP и условий до доказательства готовности.',
+            'FREEFORM возвращает help route и не запускает обязательный шестишаговый мастер.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_platform_context_get',
+        sideEffect: 'none',
+        requiredFields: ['platform_id'],
+        // Снимок для замещающей записи: из него берут текущий набор действий триггера перед
+        // besales_trigger_upsert(replace_actions), а неполный снимок молча удалит непрочитанное.
+        // Системные промпты агентов выбрасываются первыми — на крупном канале это до 72 % веса,
+        // и читаются они отдельными инструментами besales_prompt_*.
+        resultPolicy: {
+            neverTruncate: true,
+            droppablePaths: ['agents[].baseSystemPrompt'],
+            narrowingHint: 'Снимок канала отдаётся целиком и на канале с десятками агентов не помещается в ответ. Работайте по одному агенту: besales_agent_list для перечня, besales_prompt_patch_get для промпта.',
+        },
+        schema: z.object({
+            platform_id: uuidSchema,
+            // Срез снимка: без него на канале с десятками агентов ответ не помещается вовсе.
+            // `agent_summaries` отдаёт агентов БЕЗ промптов, `agents_full` — целиком.
+            sections: z
+                .array(z.enum([
+                'platform',
+                'agent_summaries',
+                'agents_full',
+                'router',
+                'behavior',
+                'follow_up',
+                'pipeline_settings',
+                'readiness',
+            ]))
+                .min(1)
+                .optional(),
+        }),
+        createRequest: (input) => {
+            const suffix = input.sections === undefined
+                ? ''
+                : `?sections=${encodeURIComponent(input.sections.join(','))}`;
+            return {
+                method: 'GET',
+                path: `/channels/${input.platform_id}/setup/context${suffix}`,
+            };
+        },
+        enhanceResponse: (response) => withInstructions(withProjectedRoutingRules(response), [
+            'Use this sanitized context first for Platform Setup Bridge flows.',
+            'Read readiness flags, then call targeted mutation tools. Do not ask the user for workspace_id.',
+            'Prompt content changes still go through besales_prompt_* tools and besales_prompt_finalize.',
+            'У правил роутинга «по значению переменной» рядом с сырым condition лежат condition_logic и conditions[] — именно их принимает besales_routing_rule_upsert. Внутри условия набор значений (variable_values) и его первое значение (variable_value) описывают ОДНО и то же: правь набор, а одиночное значение приводи в соответствие либо не присылай вовсе.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_trigger_action_catalog_get',
+        sideEffect: 'none',
+        closedWorld: true,
+        requiredFields: ['platform_id'],
+        resultPolicy: {
+            neverTruncate: true,
+            narrowingHint: 'Полный каталог не помещается в ответ. Повторите вызов с action_type для одного действия.',
+        },
+        schema: z.object({
+            platform_id: uuidSchema,
+            action_type: z.string().trim().min(1).optional(),
+        }),
+        createRequest: (input) => ({
+            method: 'GET',
+            path: `/channels/${input.platform_id}/setup/trigger-action-catalog` +
+                (input.action_type ? `?actionType=${encodeURIComponent(input.action_type)}` : ''),
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Каталог построен из канонического Zod union, карты wire-имён и реестра runtime handlers.',
+            'runtimeAvailable=false означает реальный блокер исполнения; не создавай такой шаг до появления handler.',
+            'Для записи используй minimalExample и scope мутации из ответа, затем выполни verification.',
+            'Строка в Google-таблицу (GOOGLE_SHEETS_APPEND_ROW): попроси человека открыть таблицу на редактирование адресу ' +
+                'serviceAccount.email из этого пункта; serviceAccount.configured=false — действие исполниться не сможет.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_agent_list',
+        sideEffect: 'none',
+        closedWorld: true,
+        requiredFields: ['platform_id'],
+        // Перечень парка, по которому запускают массовую правку промптов. Усечённый список здесь —
+        // не «неполный ответ», а раскатка на ЧАСТЬ агентов с отчётом об успехе.
+        resultPolicy: { neverTruncate: true },
+        schema: z.object({
+            platform_id: uuidSchema,
+            // ⚠️ Без умолчания: без этих ручек отказ по размеру был бы отказом БЕЗ ВЫХОДА — сузить
+            // перечень было нечем. Умолчание же превратило бы отказ в тихую раскатку на часть парка.
+            limit: z.number().int().min(1).max(CHANNEL_AGENTS_MAX_PAGE_SIZE).optional(),
+            cursor: z.string().min(1).optional(),
+            // Поиск без учёта регистра по имени или отображаемому имени агента.
+            query: z.string().trim().min(1).max(CHANNEL_AGENT_QUERY_MAX_LENGTH).optional(),
+        }),
+        createRequest: (input) => {
+            const query = new URLSearchParams();
+            if (input.limit !== undefined)
+                query.set('limit', String(input.limit));
+            if (input.cursor)
+                query.set('cursor', input.cursor);
+            if (input.query)
+                query.set('query', input.query);
+            const suffix = query.size > 0 ? `?${query.toString()}` : '';
+            return {
+                method: 'GET',
+                path: `/channels/${input.platform_id}/agents${suffix}`,
+            };
+        },
+        enhanceResponse: (response, input) => withAgentModelNotice(assertCompleteList(response, {
+            pageRequested: input.limit !== undefined || input.cursor !== undefined,
+            toolName: 'besales_agent_list',
+            howToPage: `Позовите снова с limit (до ${CHANNEL_AGENTS_MAX_PAGE_SIZE}) и продолжайте по nextCursor, пока он не станет пустым.`,
+        })),
+    }),
+    defineTool({
+        name: 'besales_agent_get',
+        enhanceResponse: withAgentModelNotice,
+        sideEffect: 'none',
+        requiredFields: ['agent_id'],
+        // Ответ — снимок агента для замещающей правки: ПОЛНЫЙ базовый промпт (до 100 000 символов, то есть до ~200 КБ
+        // кириллицей) и конфигурации. Сузить его нечем, а общий порог отказа снимков отвечал бы отказом на штатном
+        // агенте с длинным промптом.
+        resultPolicy: {
+            neverTruncate: true,
+            maxResultBytes: 400_000,
+            narrowingHint: 'Параметров для сужения у этого снимка нет: промпт и конфигурации агента читаются целиком. Если он не помещается даже в свой потолок, сократите базовый промпт агента.',
+        },
+        schema: z.object({
+            agent_id: uuidSchema,
+        }),
+        createRequest: (input) => ({
+            method: 'GET',
+            path: `/agents/${input.agent_id}`,
+        }),
+    }),
+    defineTool({
+        name: 'besales_agent_readiness_get',
+        sideEffect: 'none',
+        closedWorld: true,
+        requiredFields: ['agent_id'],
+        // Вердикт считается по КАЖДОЙ привязке, и усечённый список привязок выдал бы непроверенные каналы за
+        // проверенные. Сузить ответ нечем: размер растёт с числом каналов агента (десятки привязок с адресными
+        // пунктами missing[] по-русски), поэтому потолок свой и заведомо выше общего.
+        resultPolicy: {
+            neverTruncate: true,
+            maxResultBytes: 400_000,
+            narrowingHint: 'Параметров для сужения у проверки готовности нет: она считается по всем привязкам агента сразу. Если ответ не помещается даже в свой потолок, у агента аномально много привязок к каналам — уберите лишние.',
+        },
+        schema: z.object({ agent_id: uuidSchema }).strict(),
+        createRequest: (input) => ({
+            method: 'GET',
+            path: `/agents/${input.agent_id}/readiness`,
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Сейчас готовность всегда отвечает NOT_PROVEN: API не фиксирует версии зависимых настроек (поведение канала, маршрутизация, триггеры, навыки, содержимое знаний, ICP, переменные, пост-обработчики, настройки привязки агента к каналу), и повтор песочницы этого не снимает. Не обещай пользователю READY.',
+            'Ответ двухуровневый. Верхний missing — все шаги: сначала пункты агента (промпт, ICP, версия, пространства знаний), затем пункты каждой привязки с названием канала; bindings[].missing — те же шаги одного канала. Верхние gates — сводка по каналу песочницы (sandboxChannelId), а готовность считается по КАЖДОЙ привязке. Выполни адресные пункты обоих уровней и перечитай; promptAndAgentCurrent=true означает только актуальность промпта и записи агента.',
+            'passRate не является quality. Нужны COMPLETED, свежая конфигурация, findings и qualityRate не ниже policy.minQualityRate; прогон по кандидату промпта готовность не доказывает. Проверки ожиданий сценариев — отдельная ось: checksRate — доля пройденных проверок (сумма по сценариям прогона), пусто — у реплик нет машинных ожиданий; нужно не ниже policy.minChecksRate. Пункт о проверках закрывается ожиданиями, но добавление expectations вердикт не меняет.',
+            'crmAuthorization=NOT_EVALUATED не подтверждает живой доступ к CRM; проверяй его отдельной проверкой подключения, если CRM нужна сценарию.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_agent_variable_overrides_get',
+        sideEffect: 'none',
+        requiredFields: ['platform_id', 'agent_id'],
+        // Снимок для замещающей записи: besales_agent_update меняет набор перезаписей ЦЕЛИКОМ.
+        //
+        // ⛔ Сузить его НЕЧЕМ — набор неделим по построению, и отказ здесь был единственным
+        // отказом во всём мосту БЕЗ ВЫХОДА: не помещается — значит агента нельзя безопасно
+        // обновить вовсе. Поэтому свой потолок вместо общего плюс сказанное вслух, что делать.
+        resultPolicy: {
+            neverTruncate: true,
+            maxResultBytes: 400_000,
+            narrowingHint: 'Этот снимок неделим: он вход замещающей записи besales_agent_update. Если он не помещается даже в свой потолок, у агента аномально много перезаписей — сократите их набор, иначе безопасное обновление агента невозможно.',
+        },
+        schema: z.object({
+            platform_id: uuidSchema,
+            agent_id: uuidSchema,
+        }),
+        createRequest: (input) => ({
+            method: 'GET',
+            path: `/agents/${input.agent_id}/variable-overrides`,
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Read-only: текущие unified variable overrides v2-агента.',
+            'Читай ПЕРЕД besales_agent_update: поля agent_workspace_variable_overrides / agent_variable_overrides заменяют набор ЦЕЛИКОМ (delete отсутствующих + upsert присланных). Чтобы не затереть уже выставленную перезапись (напр. registration_link), переотправь её вместе с новыми.',
+            'Пустой набор означает, что агент наследует defaultValue переменных.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_getcourse_departments_list',
+        sideEffect: 'none',
+        requiredFields: ['platform_id'],
+        schema: z.object({
+            platform_id: uuidSchema,
+        }),
+        createRequest: (input) => ({
+            method: 'GET',
+            path: `/channels/${input.platform_id}/getcourse/departments`,
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Живой список отделов GetCourse Inbox школы ({ id, title }): спрашивается у школы в момент вызова.',
+            'department.id — значение target_department_id для маршрутизации диалогов по отделам.',
+            'Записать выбранный отдел: besales_platform_settings_update с getcourse_settings.target_department_id. Запись идёт слиянием и соседние настройки не трогает; null выключает маршрутизацию.',
+            'Отдел ЖИВЫХ ЛЮДЕЙ — отдельная настройка getcourse_settings.operator_department_id: туда уезжает диалог при передаче человеку, null выключает передачу. Отделы обязаны различаться: одинаковые значения бэкенд отвергает, иначе авто-маршрутизация клала бы диалог прямо в очередь сотрудников.',
+            'Пустой массив означает, что отделов у школы нет. Сбой обращения к школе приходит ошибкой 502, пустым списком он не притворяется.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_getcourse_wave_import',
+        sideEffect: 'spend',
+        requiredFields: ['platform_id', 'crm_id', 'channels', 'contacts'],
+        defaultWorkspaceId: true,
+        schema: z
+            .object({
+            workspace_id: uuidSchema.optional(),
+            platform_id: uuidSchema,
+            crm_id: uuidSchema,
+            launch_type: z.enum(['status', 'board', 'group']).optional(),
+            channels: waveChannelsSchema,
+            funnel: waveFunnelSchema.optional(),
+            segment: z.string().max(200).optional(),
+            // Предел 4000 совпадает с сервером и опубликованной схемой инструмента.
+            segment_description: z.string().max(BROADCAST_SEGMENT_DESCRIPTION_MAX_LENGTH).optional(),
+            cohort_label: z.string().max(200).optional(),
+            mailing_variant_id: uuidSchema.optional(),
+            message_variant: z.string().max(120).optional(),
+            found_count: z.number().int().min(0).max(10_000_000).optional(),
+            product_code: z
+                .string()
+                .trim()
+                .max(100)
+                .regex(/^[^\s/]+$/, 'product_code: без пробелов и «/»')
+                .optional(),
+            product_name: z.string().max(200).optional(),
+            deal_fields: z
+                .record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()]))
+                .optional(),
+            pipeline_id: z.number().int().nonnegative().optional(),
+            status_id: z.number().int().nonnegative().optional(),
+            group_id: z.number().int().nonnegative().optional(),
+            contacts: z
+                .array(z.object({
+                contact_id: z.string(),
+                deal_id: z.string().optional(),
+                transport: z.string().optional(),
+                dialog_id: z.string().optional(),
+                email: z.string().email().max(320).optional(),
+                phone: z.string().max(64).optional(),
+                first_name: z.string().max(200).optional(),
+                last_name: z.string().max(200).optional(),
+                lead_last_active_at: z.string().datetime({ offset: true }).optional(),
+                segment_entered_at: z.string().datetime({ offset: true }).optional(),
+            }))
+                .min(1)
+                .max(500),
+            confirm: z.boolean().optional(),
+            check_messenger_presence: z.boolean().optional(),
+            dedup_window_days: z.number().int().min(0).max(365).optional(),
+            dedup_scope: z.enum(['any', 'same_funnel']).optional(),
+            preflight: z
+                .object({
+                enabled: z.boolean().optional(),
+                product_title: z.string().max(500).optional(),
+                product_match_key: z.string().max(500).optional(),
+                offer_id: z.number().int().nonnegative().optional(),
+                other_product_active_deal_mode: z.enum(['warn', 'block', 'ignore']).optional(),
+            })
+                .optional(),
+        })
+            .refine((input) => input.segment_description === undefined || Boolean(input.segment?.trim()), {
+            message: 'segment_description требует непустой segment',
+            path: ['segment_description'],
+        }),
+        createRequest: (input) => ({
+            method: 'POST',
+            path: `/workspaces/${input.workspace_id}/getcourse-waves/import`,
+            body: compactObject({
+                channelId: input.platform_id,
+                crmId: input.crm_id,
+                launchType: input.launch_type,
+                transports: input.channels,
+                funnel: input.funnel,
+                segment: input.segment,
+                segmentDescription: input.segment_description,
+                cohortLabel: input.cohort_label,
+                mailingVariantId: input.mailing_variant_id,
+                messageVariant: input.message_variant,
+                foundCount: input.found_count,
+                productCode: input.product_code,
+                productName: input.product_name,
+                dealFields: input.deal_fields,
+                pipelineId: input.pipeline_id,
+                statusId: input.status_id,
+                groupId: input.group_id,
+                dedupWindowDays: input.dedup_window_days,
+                dedupScope: input.dedup_scope,
+                contacts: input.contacts?.map((c) => compactObject({
+                    getcourseUserId: c.contact_id,
+                    dealId: c.deal_id,
+                    transport: c.transport,
+                    dialogId: c.dialog_id,
+                    email: c.email,
+                    phone: c.phone,
+                    firstName: c.first_name,
+                    lastName: c.last_name,
+                    leadLastActiveAt: c.lead_last_active_at,
+                    segmentEnteredAt: c.segment_entered_at,
+                })),
+                confirm: input.confirm,
+                checkMessengerPresence: input.check_messenger_presence,
+                preflight: input.preflight
+                    ? compactObject({
+                        enabled: input.preflight.enabled,
+                        productTitle: input.preflight.product_title,
+                        productMatchKey: input.preflight.product_match_key,
+                        offerId: input.preflight.offer_id,
+                        otherProductActiveDealMode: input.preflight.other_product_active_deal_mode,
+                    })
+                    : undefined,
+            }),
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Запуск outbound-волны GetCourse: Шаг 1 (импорт контактов + пин сделок) → Шаг 2 (отправка). По умолчанию launch_type=status (простановка полей → «Процесс» GetCourse шлёт welcome).',
+            'БЕЗ confirm=true — DRY-RUN: вернётся { kind: "PREVIEW", totalContacts, withDeal, mode, channels, parseErrors, sample }, НИЧЕГО не отправляется и не пишется. Покажи summary пользователю и запускай реально только с confirm=true.',
+            'channels — значения GetCourseTransport: "VK" | "Telegram" | "MAX" | "SMS" | "Email" | "Site" (для аналитики «Канал волны»).',
+            'funnel — канонический ключ/название БИЗНЕС-воронки. Не передавай сюда имя файла, batch/resend или дату запуска. cohort_label — человекочитаемое имя конкретного запуска волны.',
+            'contacts[].segment_entered_at — точный ISO-момент попадания контакта в сегмент. contacts[].lead_last_active_at — только legacy/последняя активность; не используй её как замену segment_entered_at.',
+            'launch_type=status требует deal_fields = { "<числовой fieldId GetCourse>": значение } (одинаковые на всю волну). board требует pipeline_id+status_id, group — group_id.',
+            'preflight (default enabled=true) — pre-send гейт перед каждой строкой Шага 2: блокирует контакт, если уже есть активная/оплаченная сделка по этому продукту или проверка GetCourse упала. Передавай product_title/product_match_key или funnel; если контекста продукта нет вообще, backend отклонит запуск до создания job.',
+            'confirm=true ставит волну в очередь и СРАЗУ возвращает { kind: "STARTED", waveJobId, mode, totalContacts, parseErrors }: HTTP не ждёт ни одной фазы. Опрашивай waveJobId через besales_getcourse_wave_status до ТЕРМИНАЛЬНОГО статуса — COMPLETED или FAILED (оба терминальны; на FAILED прекращай поллинг, повторный опрос ничего не изменит).',
+            'check_messenger_presence (default TRUE): отсеивает контакты без мессенджера (Telegram/Max/VK) — они не импортируются и не уходят в волну. Проверка = API-вызов на каждый контакт (кроме тех, о ком свежий ответ школы уже есть), но идёт ВНУТРИ джоба, а не в HTTP-запросе, поэтому большая когорта запуск не роняет по таймауту; число отсеянных читается из preflight.noMessengerSkipped в статусе. Выключать её стоит только когда заранее прогнан backfill POST /api/v2/.../chat-users/import/getcourse-refresh-messengers.',
+            'dedup_window_days (default 30, 0–365) и dedup_scope (default any | same_funnel): any учитывает любую прошлую волну, same_funnel — ту же каноническую бизнес-воронку (legacy batch/resend-суффиксы игнорируются). 0 = выключить дедуп полностью — только для осознанного повторного запуска.',
+            WAVE_WELCOME_PAUSE_INSTRUCTION,
+            'В dry-run поле ledByOtherSchoolChannel.count считает людей, чей живой адрес ведёт другой канал той же школы. Адрес на канале загрузки для них не создаётся. Строка получателя и новая строка сделки записываются за ведущим каналом человека. Существующая строка сделки остаётся за каналом первой волны; деньги и зачёт оплаты читают канал строки сделки.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_getcourse_wave_status',
+        sideEffect: 'none',
+        requiredFields: ['job_id'],
+        defaultWorkspaceId: true,
+        schema: z.object({
+            workspace_id: uuidSchema.optional(),
+            job_id: uuidSchema,
+        }),
+        createRequest: (input) => ({
+            method: 'GET',
+            path: `/workspaces/${input.workspace_id}/getcourse-waves/${input.job_id}`,
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Статус ОДНОГО durable-джоба волны: status (PROCESSING | COMPLETED | FAILED), phase (PREFLIGHT | CONTACT_IMPORT | DEAL_MOVE — фаза, на которой джоб сейчас), mode (STATUS | BOARD | GROUP), счётчики total/processed/success/failed/blocked/skipped, errorReasons (первые построчные причины), metadata (created/unverified/welcomed/welcomeSkipped/welcomeSkippedAgentPaused/welcomeFailed/segmentWriteFailed), welcomeSkippedAgentPaused (count/labels/rows) и preflight-агрегаты.',
+            WAVE_WELCOME_PAUSE_INSTRUCTION,
+            'Терминальных статусов ДВА: COMPLETED и FAILED. FAILED — волна остановлена целиком (сорвался предохранитель по доле ошибок либо джоб упал), остаток строк НЕ обработан; поллинг прекращай, автоматически не перезапускай — часть внешних эффектов уже произведена.',
+            'blocked — это НЕ ошибка: контакт намеренно не тронут (обычно уже есть активная или оплаченная сделка по тому же продукту). Считать blocked неудачей — вводить оператора в заблуждение; неудачи только в failed + errorReasons (нет сделки, поле вне «Предложения» заказа и т.п.).',
+            'phase объясняет, на чём стоит волна: PREFLIGHT — проверки до отправки, CONTACT_IMPORT — импорт контактов и пин сделок, DEAL_MOVE — собственно Шаг 2. Долгий PROCESSING в DEAL_MOVE нормален: между строками стоят паузы.',
+            'preflight.blocked/errors — контакты, которым НЕ отправляли; BroadcastRecipient для них не создаётся, поэтому received в аналитике не раздувается. preflight.warnings — число ПРОВЕРОК, несущих хотя бы одно предупреждение, а не число предупреждений.',
+            'ledByOtherSchoolChannel.count — число людей, которых ведёт другой канал той же школы. Строка получателя и новая строка сделки записываются за ведущим каналом человека. Существующая строка сделки остаётся за каналом первой волны; деньги и зачёт оплаты читают канал строки сделки.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_getcourse_contacts_import',
+        sideEffect: 'write',
+        // Имя проверки не выводится из имени запуска: у статуса другой корень (`contact_import`).
+        verifyWithToolName: 'besales_getcourse_contact_import_status',
+        requiredFields: ['platform_id', 'contacts'],
+        defaultWorkspaceId: true,
+        schema: z
+            .object({
+            workspace_id: uuidSchema.optional(),
+            platform_id: uuidSchema,
+            // ⛔ У строки — только размер. Смысл (цифры в номерах, адрес почты, известный транспорт)
+            // сервер проверяет ПОСТРОЧНО и возвращает в parseErrors; проверка смысла здесь отвергала
+            // весь список из-за одной ячейки, и годные контакты не заводились вовсе.
+            contacts: z
+                .array(z
+                .object({
+                contact_id: z.string().min(1).max(20),
+                deal_id: z.string().max(20).optional(),
+                dialog_id: z.string().max(20).optional(),
+                transport: z.string().max(64).optional(),
+                email: z.string().max(320).optional(),
+                phone: z.string().max(64).optional(),
+                first_name: z.string().max(200).optional(),
+                last_name: z.string().max(200).optional(),
+            })
+                .strict())
+                .min(1)
+                .max(5000),
+            check_messenger_presence: z.boolean().optional(),
+            // Значения проверяет сервер (регистр не значим); здесь — только размер: транспортов десять.
+            channels: z.array(z.string().min(1).max(64)).max(WAVE_TRANSPORTS.length).optional(),
+        })
+            .strict(),
+        createRequest: (input) => ({
+            method: 'POST',
+            path: `/workspaces/${input.workspace_id}/getcourse-contact-imports`,
+            body: compactObject({
+                channelId: input.platform_id,
+                contacts: input.contacts.map((contact) => compactObject({
+                    getcourseUserId: contact.contact_id,
+                    dealId: contact.deal_id,
+                    dialogId: contact.dialog_id,
+                    transport: contact.transport,
+                    email: contact.email,
+                    phone: contact.phone,
+                    firstName: contact.first_name,
+                    lastName: contact.last_name,
+                })),
+                checkMessengerPresence: input.check_messenger_presence,
+                transports: input.channels,
+            }),
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Импорт НИЧЕГО не отправляет: он только заводит или обновляет контакты школы в базе платформы, чтобы по ним можно было запускать отправку.',
+            'Импорт идёт фоном. Ответ: jobId — ключ опроса; queuedContacts — сколько контактов поставлено; parseErrors — строки, отбракованные разбором (position — номер контакта в присланном списке, message — причина: номер не цифрами, неверная почта, неизвестный транспорт, дубль). Одна битая строка НЕ отвергает список — остальные ставятся; пустая ячейка — это «значения нет», а не ошибка. Опрашивай besales_getcourse_contact_import_status с этим jobId до терминального статуса.',
+            'Уже существующий контакт не дублируется — опознание идёт по ключам склейки. Повторный импорт того же списка безопасен.',
+            'check_messenger_presence (по умолчанию true): контакт, до которого не достать, не заводится. Проверка — обращение к школе на каждый контакт, кроме тех, о ком свежий ответ школы уже есть: ответ о человеке без карточки помнится (срок — настройка канала reachability_ttl_days) и повторно не спрашивается. На тысячах строк импорт идёт заметно дольше.',
+            'channels — каналы, которыми запуск собирается писать (SITE, EMAIL, SMS, TELEGRAM, FACEBOOK, VK, CHATIUM, WHATSAPP, VIBER, MAX; регистр не значим). Судятся только каналы, включённые у канала школы. Названы — человек не заводится, лишь если недостижим НИ ОДНИМ из них: мессенджеры по привязкам школы, почта по адресу у школы, SMS и WhatsApp по номеру; транспорт, указанный в строке контакта, считается доказанным. Не названы — нужен хотя бы один привязанный мессенджер Telegram/MAX/VK. Названы, но ни один не включён у канала школы — импорт отвергается (422 LAUNCH_CHANNELS_NOT_AVAILABLE): этим подключением никого не достать.',
+            '409 — в воркспейсе уже идёт другой импорт или волна (гейт «один активный импорт» общий), это не сбой: дождись завершения и повтори. 400 — ни одной годной строки, причины в parseErrors.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_getcourse_contact_import_status',
+        sideEffect: 'none',
+        requiredFields: ['job_id'],
+        defaultWorkspaceId: true,
+        schema: z
+            .object({
+            workspace_id: uuidSchema.optional(),
+            job_id: uuidSchema,
+        })
+            .strict(),
+        createRequest: (input) => ({
+            method: 'GET',
+            path: `/workspaces/${input.workspace_id}/getcourse-contact-imports/${input.job_id}`,
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'status: PROCESSING — идёт; COMPLETED — все строки обработаны без отказов; PARTIAL — завершён, но у части строк отказ (сверь failedCount и errors); FAILED — импорт остановлен аварией, строки, до которых он не дошёл, не обработаны; CANCELLED — остановлен. Терминальны все, кроме PROCESSING.',
+            'successCount — заведено или обновлено; skippedNoMessenger — не заведены, потому что у контакта нет мессенджера (это не ошибка); failedCount — отказы строк, включая отбракованные разбором; errors — первые причины отказов.',
+            'Инструмент читает только задачи импорта контактов: номер задачи другого вида даёт 404. Статус волны — besales_getcourse_wave_status.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_getcourse_wave_run_start',
+        sideEffect: 'spend',
+        requiredFields: ['platform_id', 'crm_id', 'channels', 'contacts'],
+        defaultWorkspaceId: true,
+        schema: z
+            .object({
+            workspace_id: uuidSchema.optional(),
+            platform_id: uuidSchema,
+            crm_id: uuidSchema,
+            launch_key: uuidSchema.optional(),
+            dry_run_hash: z
+                .string()
+                .regex(/^[0-9a-f]{64}$/)
+                .optional(),
+            launch_type: z.literal('status').optional(),
+            channels: waveChannelsSchema,
+            funnel: waveFunnelSchema.optional(),
+            segment: z.string().max(200).optional(),
+            segment_description: z.string().max(BROADCAST_SEGMENT_DESCRIPTION_MAX_LENGTH).optional(),
+            cohort_label: z.string().max(200).optional(),
+            mailing_variant_id: uuidSchema.optional(),
+            message_variant: z.string().max(120).optional(),
+            found_count: z.number().int().min(0).max(10_000_000).optional(),
+            product_code: z
+                .string()
+                .trim()
+                .max(100)
+                .regex(/^[^\s/]+$/, 'product_code: без пробелов и «/»')
+                .optional(),
+            product_name: z.string().max(200).optional(),
+            deal_fields: z
+                .record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()]))
+                .optional(),
+            contacts: z.array(getCourseWaveContactSchema).min(1).max(5000),
+            confirm: z.boolean().optional(),
+            check_messenger_presence: z.boolean().optional(),
+            dedup_window_days: z.number().int().min(0).max(365).optional(),
+            dedup_scope: z.enum(['any', 'same_funnel']).optional(),
+            preflight: z
+                .object({
+                enabled: z.boolean().optional(),
+                product_title: z.string().max(500).optional(),
+                product_match_key: z.string().max(500).optional(),
+                offer_id: z.number().int().nonnegative().optional(),
+                other_product_active_deal_mode: z.enum(['warn', 'block', 'ignore']).optional(),
+            })
+                .optional(),
+            chunk_size: z.number().int().min(1).max(500).optional(),
+            explicit_confirmation: z.literal(true).optional(),
+            confirmation_reason: z.string().optional(),
+        })
+            .refine((input) => input.segment_description === undefined || Boolean(input.segment?.trim()), {
+            message: 'segment_description требует непустой segment',
+            path: ['segment_description'],
+        })
+            .refine((input) => !input.confirm || input.explicit_confirmation === true, {
+            message: 'Реальный запуск требует explicit_confirmation=true: отправка волны необратима',
+            path: ['explicit_confirmation'],
+        })
+            .refine((input) => !input.confirm || Boolean(input.launch_key), {
+            message: 'confirm=true требует стабильный launch_key UUID',
+            path: ['launch_key'],
+        })
+            .refine((input) => !input.confirm || Boolean(input.dry_run_hash), {
+            message: 'confirm=true требует dry_run_hash из предыдущего dry-run',
+            path: ['dry_run_hash'],
+        }),
+        createRequest: (input) => ({
+            method: 'POST',
+            path: `/workspaces/${input.workspace_id}/getcourse-wave-runs`,
+            body: compactObject({
+                channelId: input.platform_id,
+                crmId: input.crm_id,
+                launchKey: input.launch_key,
+                dryRunHash: input.dry_run_hash,
+                launchType: input.launch_type,
+                transports: input.channels,
+                funnel: input.funnel,
+                segment: input.segment,
+                segmentDescription: input.segment_description,
+                cohortLabel: input.cohort_label,
+                mailingVariantId: input.mailing_variant_id,
+                messageVariant: input.message_variant,
+                foundCount: input.found_count,
+                productCode: input.product_code,
+                productName: input.product_name,
+                dealFields: input.deal_fields,
+                contacts: input.contacts?.map(mapGetCourseWaveContact),
+                confirm: input.confirm,
+                checkMessengerPresence: input.check_messenger_presence,
+                dedupWindowDays: input.dedup_window_days,
+                dedupScope: input.dedup_scope,
+                preflight: input.preflight
+                    ? compactObject({
+                        enabled: input.preflight.enabled,
+                        productTitle: input.preflight.product_title,
+                        productMatchKey: input.preflight.product_match_key,
+                        offerId: input.preflight.offer_id,
+                        otherProductActiveDealMode: input.preflight.other_product_active_deal_mode,
+                    })
+                    : undefined,
+                chunkSize: input.chunk_size,
+            }),
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Durable-прогон сам режет когорту на куски и отправляет их последовательно, сам ждёт освобождения лока импорта и переживает рестарт сервиса. Опрашивай ОДИН прогон через besales_getcourse_wave_run_status, не собирай волну вручную.',
+            WAVE_RUN_WELCOME_PAUSE_INSTRUCTION,
+            'mailing_variant_id — ID именованного «Варианта рассылки» из besales_broadcast_mailing_variant_list/create. Backend tenant-scoped проверяет активность и сохраняет связь для фильтра аналитики.',
+            'БЕЗ confirm=true — DRY-RUN: возвращается проверка, но прогон НЕ создаётся и ничего не отправляется.',
+            'Реальный запуск требует confirm=true, explicit_confirmation=true, launch_key и dry_run_hash из последнего dry-run. Сгенерируй launch_key один раз на намерение и повторяй ТОТ ЖЕ ключ при сетевом ретрае.',
+            'rowsWithoutSegmentEntry — сколько СТРОК присланного списка пришли без contacts[].segment_entered_at: это строки, а не люди. Таким строкам прогон ставит момент своего запуска, и аналитика по дате входа в сегмент положит их в день запуска, а не в день настоящего входа. Если в dry-run число больше нуля — ОСТАНОВИСЬ: назови его человеку и спроси, запускать так или сначала дополнить даты. null — число не считалось (прогон создан до появления счётчика).',
+            'Поддерживается ТОЛЬКО launch_type=status. Для board/group используй старый besales_getcourse_wave_import.',
+            'HTTP 409 означает, что на платформе уже идёт активный прогон: в ответе есть его runId — не создавай новую волну, опрашивай этот runId.',
+            'Статус прогона отдаёт только агрегаты. Полный построчный разбор получай через besales_getcourse_wave_run_contacts с курсорной пагинацией.',
+            'Dry-run показывает ledByOtherSchoolChannel.count: столько людей ведёт другой канал той же школы. Адрес на канале загрузки не создаётся. Строка получателя и новая строка сделки записываются за ведущим каналом человека. Существующая строка сделки остаётся за каналом первой волны; деньги и зачёт оплаты читают канал строки сделки.',
+            'Исходы контактов: SENT — отправлено; SKIPPED — дедуп, нет мессенджера или preflight заблокировал; FAILED — построчная ошибка; UNKNOWN — исход НЕИЗВЕСТЕН: кусок был прерван, но отправка могла состояться.',
+            UNCERTAIN_WAVE_OUTCOME_INSTRUCTION,
+        ]),
+    }),
+    defineTool({
+        name: 'besales_getcourse_wave_run_status',
+        sideEffect: 'none',
+        requiredFields: ['run_id'],
+        defaultWorkspaceId: true,
+        schema: z.object({
+            workspace_id: uuidSchema.optional(),
+            run_id: uuidSchema,
+        }),
+        createRequest: (input) => ({
+            method: 'GET',
+            path: `/workspaces/${input.workspace_id}/getcourse-wave-runs/${input.run_id}`,
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Это единый агрегированный статус durable-прогона: он сам последовательно обрабатывает куски, ждёт лок импорта и продолжает после рестарта сервиса. Не собирай и не запускай куски вручную.',
+            WAVE_RUN_WELCOME_PAUSE_INSTRUCTION,
+            'Статус содержит только агрегаты. Для полного построчного разбора используй besales_getcourse_wave_run_contacts с курсорной пагинацией.',
+            'ledByOtherSchoolChannel.count — число людей, которых ведёт другой канал той же школы. Строка получателя и новая строка сделки записываются за ведущим каналом человека. Существующая строка сделки остаётся за каналом первой волны; деньги и зачёт оплаты читают канал строки сделки.',
+            'SENT — отправлено; SKIPPED — дедуп, нет мессенджера или блокировка preflight; FAILED — построчная ошибка; UNKNOWN — исход НЕИЗВЕСТЕН после прерванного куска, отправка могла состояться.',
+            UNCERTAIN_WAVE_OUTCOME_INSTRUCTION,
+        ]),
+    }),
+    defineTool({
+        name: 'besales_getcourse_wave_run_contacts',
+        carriesCustomerData: true,
+        sideEffect: 'none',
+        requiredFields: ['run_id'],
+        defaultWorkspaceId: true,
+        // Курсорная выдача уже работает; вдобавок построчный разбор волны — основание для
+        // переотправки, и усечённый он привёл бы к повторной отправке живым людям.
+        resultPolicy: {
+            neverTruncate: true,
+            narrowingHint: 'Уменьшите limit, фильтруйте по status и идите по страницам через cursor.',
+        },
+        schema: z.object({
+            workspace_id: uuidSchema.optional(),
+            run_id: uuidSchema,
+            status: z.enum(['PENDING', 'CLAIMED', 'SENT', 'SKIPPED', 'FAILED', 'UNKNOWN']).optional(),
+            cursor: uuidSchema.optional(),
+            limit: z.number().int().min(1).max(500).optional(),
+        }),
+        createRequest: (input) => {
+            const params = new URLSearchParams();
+            if (input.status)
+                params.set('status', input.status);
+            if (input.cursor)
+                params.set('cursor', input.cursor);
+            if (input.limit !== undefined)
+                params.set('limit', String(input.limit));
+            const query = params.toString();
+            return {
+                method: 'GET',
+                path: `/workspaces/${input.workspace_id}/getcourse-wave-runs/${input.run_id}/contacts${query ? `?${query}` : ''}`,
+            };
+        },
+        enhanceResponse: (response) => withInstructions(response, [
+            'Полный построчный разбор durable-прогона. Продолжай курсорную пагинацию по nextCursor до конца; агрегированный besales_getcourse_wave_run_status строк контактов не возвращает.',
+            'Фильтр status: PENDING | CLAIMED | SENT | SKIPPED | FAILED | UNKNOWN. SKIPPED означает дедуп, отсутствие мессенджера или блокировку preflight; FAILED — построчную ошибку.',
+            'UNKNOWN означает, что исход НЕИЗВЕСТЕН: кусок был прерван, но отправка могла состояться.',
+            WAVE_RUN_CONTACT_IDS_INSTRUCTION,
+            UNCERTAIN_WAVE_OUTCOME_INSTRUCTION,
+        ]),
+    }),
+    defineTool({
+        name: 'besales_getcourse_wave_run_cancel',
+        sideEffect: 'write',
+        requiredFields: ['run_id'],
+        defaultWorkspaceId: true,
+        schema: z.object({
+            workspace_id: uuidSchema.optional(),
+            run_id: uuidSchema,
+        }),
+        createRequest: (input) => ({
+            method: 'POST',
+            path: `/workspaces/${input.workspace_id}/getcourse-wave-runs/${input.run_id}/cancel`,
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Отмена запрещает прогону заявлять новые куски И останавливает идущий кусок: внешних вызовов он больше не делает, оставшиеся в куске люди сообщение не получают. Уже отправленное вернуть нельзя. После отмены опроси besales_getcourse_wave_run_status.',
+            'Для полного построчного результата используй besales_getcourse_wave_run_contacts с курсорной пагинацией; статус прогона отдаёт только агрегаты.',
+            'UNKNOWN — исход НЕИЗВЕСТЕН после прерванного куска, отправка могла состояться.',
+            UNCERTAIN_WAVE_OUTCOME_INSTRUCTION,
+        ]),
+    }),
+    defineTool({
+        name: 'besales_getcourse_wave_run_batch_start',
+        sideEffect: 'spend',
+        requiredFields: ['batch_key', 'platform_id', 'crm_id', 'segments'],
+        defaultWorkspaceId: true,
+        schema: z
+            .object({
+            workspace_id: uuidSchema.optional(),
+            batch_key: z.string(),
+            platform_id: uuidSchema,
+            crm_id: uuidSchema,
+            segments: z
+                .array(z
+                .object({
+                // Имя поля обязано совпадать с WaveLaunchParamsDto.launchType: у бэкенда
+                // включён forbidNonWhitelisted, поэтому лишний ключ роняет весь батч в 400.
+                launch_type: z.literal('status').optional(),
+                contacts: z.array(getCourseWaveContactSchema).min(1).max(2000),
+                channels: waveChannelsSchema,
+                deal_fields: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()])),
+                funnel: waveFunnelSchema.optional(),
+                segment: z.string().max(200).optional(),
+                segment_description: z
+                    .string()
+                    .max(BROADCAST_SEGMENT_DESCRIPTION_MAX_LENGTH)
+                    .optional(),
+                cohort_label: z.string().max(200).optional(),
+                mailing_variant_id: uuidSchema.optional(),
+                message_variant: z.string().max(120).optional(),
+                found_count: z.number().int().min(0).max(10_000_000).optional(),
+                product_code: z
+                    .string()
+                    .trim()
+                    .max(100)
+                    .regex(/^[^\s/]+$/, 'product_code: без пробелов и «/»')
+                    .optional(),
+                product_name: z.string().max(200).optional(),
+                preflight: z
+                    .object({
+                    enabled: z.boolean().optional(),
+                    product_title: z.string().max(500).optional(),
+                    product_match_key: z.string().max(500).optional(),
+                    offer_id: z.number().int().nonnegative().optional(),
+                    other_product_active_deal_mode: z.enum(['warn', 'block', 'ignore']).optional(),
+                })
+                    .optional(),
+                check_messenger_presence: z.boolean().optional(),
+                dedup_window_days: z.number().int().min(1).max(365).optional(),
+                dedup_scope: z.enum(['any', 'same_funnel']).optional(),
+                chunk_size: z.number().int().min(1).max(500).optional(),
+            })
+                .strict()
+                .refine((segment) => segment.segment_description === undefined || Boolean(segment.segment?.trim()), {
+                message: 'segment_description требует непустой segment',
+                path: ['segment_description'],
+            }))
+                .min(1)
+                .max(10)
+                .refine((segments) => segments.reduce((total, segment) => total + segment.contacts.length, 0) <= 5000, {
+                message: 'В батче может быть не более 5000 контактов суммарно',
+            }),
+            confirm: z.boolean().optional(),
+            explicit_confirmation: z.literal(true).optional(),
+            confirmation_reason: z.string().optional(),
+        })
+            .refine((input) => !input.confirm || input.explicit_confirmation === true, {
+            message: 'Реальный запуск требует explicit_confirmation=true: отправка волны необратима',
+            path: ['explicit_confirmation'],
+        }),
+        createRequest: (input) => ({
+            method: 'POST',
+            path: `/workspaces/${input.workspace_id}/getcourse-wave-runs/batch`,
+            body: compactObject({
+                batchKey: input.batch_key,
+                channelId: input.platform_id,
+                crmId: input.crm_id,
+                segments: input.segments.map((segment) => compactObject({
+                    launchType: segment.launch_type,
+                    contacts: segment.contacts.map(mapGetCourseWaveContact),
+                    transports: segment.channels,
+                    dealFields: segment.deal_fields,
+                    funnel: segment.funnel,
+                    segment: segment.segment,
+                    segmentDescription: segment.segment_description,
+                    cohortLabel: segment.cohort_label,
+                    mailingVariantId: segment.mailing_variant_id,
+                    messageVariant: segment.message_variant,
+                    foundCount: segment.found_count,
+                    productCode: segment.product_code,
+                    productName: segment.product_name,
+                    preflight: segment.preflight
+                        ? compactObject({
+                            enabled: segment.preflight.enabled,
+                            productTitle: segment.preflight.product_title,
+                            productMatchKey: segment.preflight.product_match_key,
+                            offerId: segment.preflight.offer_id,
+                            otherProductActiveDealMode: segment.preflight.other_product_active_deal_mode,
+                        })
+                        : undefined,
+                    checkMessengerPresence: segment.check_messenger_presence,
+                    dedupWindowDays: segment.dedup_window_days,
+                    dedupScope: segment.dedup_scope,
+                    chunkSize: segment.chunk_size,
+                })),
+                confirm: input.confirm,
+            }),
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Очередь исполняет сегменты ПОСЛЕДОВАТЕЛЬНО: в один момент на платформе идёт только один прогон. Опрашивай ОДИН besales_getcourse_wave_run_batch_status, не собирай сегменты и их статусы вручную.',
+            WAVE_RUN_WELCOME_PAUSE_INSTRUCTION,
+            'Для каждого сегмента mailing_variant_id — ID именованного «Варианта рассылки» из besales_broadcast_mailing_variant_list/create. Перед запуском backend повторно tenant-scoped проверяет активность всех вариантов под транзакционным lock.',
+            'batch_key сгенерируй ОДИН раз на попытку и ПЕРЕИСПОЛЬЗУЙ при ретрае: это ключ идемпотентности. Повтор с тем же ключом вернёт существующий батч; новый ключ создаст ВТОРУЮ копию кампании, которую дедуп не остановит.',
+            'Если повторить тот же batch_key с ИЗМЕНЁННЫМ составом сегментов, сервер вернёт HTTP 409 «ключ занят другим составом». Не меняй состав при ретрае — сначала прочитай статус существующего батча.',
+            'HTTP 400 отклоняет батч до запуска, если контакт есть в двух сегментах, пересекается с незавершённым прогоном платформы или ему уже отправляли за последние 30 дней. В ответе будут пары contactId + сегменты либо конфликтующий runId; исправь состав, а не обходи проверку новым ключом.',
+            'Два подряд отказавших сегмента ставят батч на паузу. Продолжай только через besales_getcourse_wave_run_batch_resume после проверки причин отказов.',
+            'rowsWithoutSegmentEntry — сколько СТРОК пришли без contacts[].segment_entered_at: это строки, а не люди. В dry-run число стоит у каждого сегмента, в ответе запуска — сумма и разбивка segments[] по сегментам. Таким строкам прогон ставит момент своего запуска, и аналитика по дате входа в сегмент положит их в день запуска. Если хоть у одного сегмента число больше нуля — ОСТАНОВИСЬ: назови сегменты и числа человеку и спроси, запускать так или сначала дополнить даты. null — число не считалось (прогон создан до появления счётчика).',
+            UNCERTAIN_WAVE_OUTCOME_INSTRUCTION,
+            'БЕЗ confirm=true — DRY-RUN: батч не создаётся и ничего не отправляется. Реальный запуск дополнительно требует MCP-only explicit_confirmation=true; это поле в HTTP-запрос не передаётся.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_getcourse_wave_run_batch_status',
+        sideEffect: 'none',
+        requiredFields: ['batch_id'],
+        defaultWorkspaceId: true,
+        schema: z.object({
+            workspace_id: uuidSchema.optional(),
+            batch_id: uuidSchema,
+        }),
+        createRequest: (input) => ({
+            method: 'GET',
+            path: `/workspaces/${input.workspace_id}/getcourse-wave-runs/batches/${input.batch_id}`,
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Это ЕДИНСТВЕННЫЙ агрегированный статус очереди: она запускает сегменты последовательно и держит только один прогон на платформу. Опрашивай этот batch-status, а не статусы сегментов вручную.',
+            WAVE_RUN_WELCOME_PAUSE_INSTRUCTION,
+            'Если батч на паузе после двух подряд отказавших сегментов, сначала проверь причины, затем снимай паузу только besales_getcourse_wave_run_batch_resume.',
+            UNCERTAIN_WAVE_OUTCOME_INSTRUCTION,
+        ]),
+    }),
+    defineTool({
+        name: 'besales_getcourse_wave_run_batch_cancel',
+        sideEffect: 'write',
+        requiredFields: ['batch_id'],
+        defaultWorkspaceId: true,
+        schema: z.object({
+            workspace_id: uuidSchema.optional(),
+            batch_id: uuidSchema,
+        }),
+        createRequest: (input) => ({
+            method: 'POST',
+            path: `/workspaces/${input.workspace_id}/getcourse-wave-runs/batches/${input.batch_id}/cancel`,
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Отмена останавливает очередь батча; после неё опроси ОДИН besales_getcourse_wave_run_batch_status, не собирая сегменты вручную.',
+            UNCERTAIN_WAVE_OUTCOME_INSTRUCTION,
+        ]),
+    }),
+    defineTool({
+        name: 'besales_getcourse_wave_run_batch_resume',
+        sideEffect: 'spend',
+        requiredFields: ['batch_id'],
+        defaultWorkspaceId: true,
+        schema: z.object({
+            workspace_id: uuidSchema.optional(),
+            batch_id: uuidSchema,
+        }),
+        createRequest: (input) => ({
+            method: 'POST',
+            path: `/workspaces/${input.workspace_id}/getcourse-wave-runs/batches/${input.batch_id}/resume`,
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Снимает паузу батча, которую вызывают два подряд отказавших сегмента. После resume опрашивай ОДИН besales_getcourse_wave_run_batch_status: очередь продолжит сегменты последовательно, один прогон на платформу.',
+            UNCERTAIN_WAVE_OUTCOME_INSTRUCTION,
+        ]),
+    }),
+    defineTool({
+        name: 'besales_wazzup_templates_list',
+        sideEffect: 'none',
+        requiredFields: ['platform_id'],
+        defaultWorkspaceId: true,
+        schema: z.object({
+            workspace_id: uuidSchema.optional(),
+            platform_id: uuidSchema,
+        }),
+        createRequest: (input) => ({
+            method: 'GET',
+            path: `/workspaces/${input.workspace_id}/wazzup-waves/templates/${input.platform_id}`,
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Шаблоны WABA платформы Wazzup: templateGuid, title, status модерации Meta, bodyText, variableCount (сколько значений переменных нужно), usable + unsupportedReasons.',
+            'В волне используй ТОЛЬКО шаблоны с usable=true. Остальные либо не одобрены Meta, либо содержат медиа-заголовок / переменную в URL-кнопке — там значения ушли бы не в те слоты.',
+            'variableCount считается по МАКСИМАЛЬНОМУ индексу {{n}}: «{{1}} … {{2}} … {{1}}» — это 2 значения, а не 3.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_wazzup_wave_import',
+        sideEffect: 'spend',
+        requiredFields: ['platform_id', 'template_guid', 'contacts'],
+        defaultWorkspaceId: true,
+        schema: z
+            .object({
+            workspace_id: uuidSchema.optional(),
+            platform_id: uuidSchema,
+            template_guid: z.string().trim().max(100),
+            template_values: z.array(z.string()).max(20).optional(),
+            contacts: z
+                .array(z.object({
+                phone: z.string().trim().max(32),
+                name: z.string().max(200).optional(),
+            }))
+                .min(1)
+                .max(500),
+            funnel: z.string().max(200).optional(),
+            segment: z.string().max(200).optional(),
+            product_code: z
+                .string()
+                .trim()
+                .max(100)
+                .regex(/^[^\s/]+$/, 'product_code: без пробелов и «/»')
+                .optional(),
+            product_name: z.string().max(200).optional(),
+            cohort_label: z.string().max(200).optional(),
+            confirm: z.boolean().optional(),
+            /**
+             * Обязателен ВМЕСТЕ с confirm=true: волна необратима и платна (каждый WABA-шаблон
+             * тарифицируется Meta). Dry-run (без confirm) подтверждения не требует.
+             *
+             * ⚠️ Это гейт СЛОЯ МОСТА, а не серверного контракта: на сервер он не уходит вовсе.
+             * Его назначение — не дать AI-оператору запустить платную рассылку мимоходом, одним
+             * флагом. Тот же приём защищает удаление одной строки знаний; рассылка пятисот
+             * платных шаблонов не может быть защищена слабее.
+             */
+            explicit_confirmation: z.literal(true).optional(),
+            confirmation_reason: z.string().optional(),
+        })
+            .refine((input) => !input.confirm || input.explicit_confirmation === true, {
+            message: 'Реальный запуск волны требует explicit_confirmation=true: сообщения платные и необратимые',
+            path: ['explicit_confirmation'],
+        }),
+        createRequest: (input) => ({
+            method: 'POST',
+            path: `/workspaces/${input.workspace_id}/wazzup-waves/import`,
+            body: compactObject({
+                channelId: input.platform_id,
+                templateGuid: input.template_guid,
+                templateValues: input.template_values,
+                funnel: input.funnel,
+                segment: input.segment,
+                productCode: input.product_code,
+                productName: input.product_name,
+                cohortLabel: input.cohort_label,
+                contacts: input.contacts?.map((c) => compactObject({ phone: c.phone, name: c.name })),
+                confirm: input.confirm,
+            }),
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Волна WhatsApp через Wazzup: одобренный WABA-шаблон уходит по когорте телефонов. Ответы получателей обрабатывает AI-агент платформы, волна видна в «Аналитике рассылок» (канал WhatsApp).',
+            'БЕЗ confirm=true — DRY-RUN: прогоняется ПОЛНЫЙ preflight (платформа, живой WABA-канал, шаблон, число значений) и возвращается previewText — НИ ОДНО сообщение не отправляется. Покажи previewText пользователю и запускай реально только с confirm=true.',
+            'Реальный запуск требует ОДНОВРЕМЕННО confirm=true и explicit_confirmation=true — второе ставится только после явного согласия пользователя на отправку платных сообщений.',
+            'КАЖДОЕ маркетинговое сообщение WhatsApp ПЛАТНОЕ, а Meta ограничивает число уникальных получателей в сутки (на старте 250, дальше растёт после верификации бизнеса). Не запускай большие когорты без явного согласия пользователя.',
+            'template_guid бери из besales_wazzup_templates_list (только usable=true). Длина template_values обязана совпасть с variableCount шаблона, иначе запуск отклонят.',
+            'Повторная отправка ТОГО ЖЕ шаблона тому же контакту в течение суток пропускается автоматически (защита от двойного списания). Другой шаблон той же когорте не блокируется.',
+            'Пропускаются контакты, остановившие бота, ждущие оператора и заблокированные — они попадут в skipped, а не в failed.',
+            'В ответе confirm-запуска — jobId. Опрашивай его через besales_wazzup_wave_status до status=COMPLETED (отправки идут с паузами).',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_wazzup_wave_status',
+        sideEffect: 'none',
+        requiredFields: ['job_id'],
+        defaultWorkspaceId: true,
+        schema: z.object({
+            workspace_id: uuidSchema.optional(),
+            job_id: uuidSchema,
+        }),
+        createRequest: (input) => ({
+            method: 'GET',
+            path: `/workspaces/${input.workspace_id}/wazzup-waves/${input.job_id}`,
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Статус волны WhatsApp: status (PROCESSING|COMPLETED), processedRows, sent/failed/skipped, errors (построчные причины).',
+            'skipped — сознательные пропуски, а unknownOutcome — отдельный неопределённый исход. Для завершённой волны сумма sent+failed+skipped+unknownOutcome равна числу обработанных строк.',
+            'Доставка приходит вебхуками WhatsApp и живёт ОТДЕЛЬНО от исхода отправки: delivered/read/deliveryFailed + deliveryErrors (коды). Докладывай их вместе с sent — «отправлено» означает лишь, что Wazzup принял сообщение.',
+            'delivered и deliveryFailed взаимоисключающи; read — подмножество delivered. unknownOutcome также включает ответ успеха без message ID; автоматически такие строки НЕ переотправляются. Диапазон возможных расходов: sent .. sent+unknownOutcome.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_wazzup_wave_cancel',
+        sideEffect: 'write',
+        requiredFields: ['job_id'],
+        defaultWorkspaceId: true,
+        schema: z.object({
+            workspace_id: uuidSchema.optional(),
+            job_id: uuidSchema,
+        }),
+        createRequest: (input) => ({
+            method: 'POST',
+            path: `/workspaces/${input.workspace_id}/wazzup-waves/${input.job_id}/cancel`,
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Отмена скоупится воркспейсом и идемпотентна. cancelled=true означает, что остановка была запрошена; уже завершённая волна не откатывает отправленные сообщения.',
+            'После отмены опрашивай besales_wazzup_wave_status до status=COMPLETED.',
+        ]),
+    }),
+];
+//# sourceMappingURL=platform-setup-wave.js.map