@besales/mcp 0.48.0 → 1.0.0-beta.4

package/dist/tools/definitions/follow-up.js

@@ -1,405 +1,248 @@
 import { z } from 'zod';
-import { buildListQuery, defineTool, uuidSchema, withInstructions, } from './shared.js';
+import { crmStagePoolMessage } from './crm-stage-pool.messages.js';
+import { assertCompleteList } from '../incomplete-list.js';
+import { FOLLOWUP_SEQUENCES_MAX_PAGE_SIZE, buildListQuery, defineTool, uuidSchema, withInstructions, } from './shared.js';
 /**
- * Схема конфига реактивационной цепочки.
+ * Календарная дата разреза. Время суток здесь бессмысленно: сутки считаются в поясе канала.
  *
- * ⚠️ Ключи ВНУТРИ `config` — camelCase, в отличие от snake_case параметров тулов: `config`
- * уходит в тело запроса БЕЗ преобразования, а рантайм читает `anchorMode`/`anchorVariable`/
- * `slotGroup`. Назвать их в snake_case значило бы сохранить конфиг, который рантайм не
- * прочитает: календарный шаг молча стал бы обычным offset-шагом.
+ * Проверяется не только форма, но и СУЩЕСТВОВАНИЕ дня: `2026-02-31` форму проходит, а приведение
+ * к дате на стороне базы роняет весь запрос. Отказ здесь понятнее отказа оттуда.
+ */
+const calendarDateSchema = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/u)
+    .refine((value) => {
+    // Разбор ISO-строки, а НЕ `Date.UTC(год, месяц, день)`: второй трактует год меньше 100 как
+    // 19xx, и `0099-01-01` — существующая дата — отвергался бы как несуществующая.
+    const parsed = new Date(`${value}T00:00:00.000Z`);
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === value;
+}, 'Такой календарной даты не существует');
+/** Момент С часовым поясом: момент без пояса сервер отвергает, иначе его читал бы пояс процесса. */
+const momentWithOffsetSchema = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,6})?)?(?:Z|[+-]\d{2}:\d{2})$/u)
+    .refine((value) => !Number.isNaN(Date.parse(value)), 'Такого момента не существует');
+/**
+ * Граница периода статистики шагов: дата `ГГГГ-ММ-ДД` (сутки в поясе канала, у конца включается весь день) — форма
+ * отгруженного инструмента — либо момент с часовым поясом.
+ */
+const stepStatsBoundSchema = z.union([calendarDateSchema, momentWithOffsetSchema]);
+/**
+ * Закрытый набор горизонтов сравнительной метрики. Свободное число позволяло бы подобрать окно
+ * под нужный ответ, поэтому один и тот же список держат и сервер, и мост.
+ */
+export const REACTION_HORIZONS = [30, 60, 90, 180, 360, 720, 1440];
+export const REACTION_RUN_WINDOW_DAYS = [1, 3, 5, 7, 14];
+const reactionRunWindowSchema = z.union([
+    z.literal(REACTION_RUN_WINDOW_DAYS[0]),
+    z.literal(REACTION_RUN_WINDOW_DAYS[1]),
+    z.literal(REACTION_RUN_WINDOW_DAYS[2]),
+    z.literal(REACTION_RUN_WINDOW_DAYS[3]),
+    z.literal(REACTION_RUN_WINDOW_DAYS[4]),
+]);
+const reactionHorizonSchema = z.union([
+    z.literal(REACTION_HORIZONS[0]),
+    z.literal(REACTION_HORIZONS[1]),
+    z.literal(REACTION_HORIZONS[2]),
+    z.literal(REACTION_HORIZONS[3]),
+    z.literal(REACTION_HORIZONS[4]),
+    z.literal(REACTION_HORIZONS[5]),
+    z.literal(REACTION_HORIZONS[6]),
+]);
+/**
+ * Метки транспорта волны — ровно те, что живут в перечислении базы и приходят в
+ * `dimensions.transports` ответа. Регистр ВЕРХНИЙ и он несущий: сервер приводит фильтр к типу
+ * перечисления, поэтому посторонняя строка даёт отказ базы, а не пустой разрез.
  *
- * ⚠️ `.passthrough()` на каждом уровне обязателен по двум причинам: legacy-конфиги несут поля
- * вне этой схемы (`finalAction`, `maxCycleCount`, `webhookConfig`, …), и сама схема исполняется
- * на машине оператора — она обновляется независимо от бэкенда и не должна отвергать конфиг,
- * который бэкенд принял бы.
+ * ⛔ Отгруженная схема перечисляла их как `Telegram, WhatsApp, MAX, VK` — в v1.5 это работало,
+ * в v2 два значения из четырёх неверны. Списано с отгруженного описания без проверки против
+ * перечисления v2; поймали обе линии ворот.
  */
-const variableConditionSchema = z
-    .object({
-    variable: z.string().describe('Имя per-contact переменной'),
-    op: z.enum(['eq', 'neq', 'in']),
-    value: z
-        .union([z.string(), z.array(z.string())])
-        .describe("Строка для eq/neq, непустой массив непустых строк для 'in'"),
-})
-    .passthrough();
+// Этот набор сверяется с контрактом в wave-transports.spec.ts; трогая его, смотри туда.
+export const WAVE_TRANSPORTS = [
+    'SITE',
+    'EMAIL',
+    'SMS',
+    'TELEGRAM',
+    'FACEBOOK',
+    'VK',
+    'CHATIUM',
+    'WHATSAPP',
+    'VIBER',
+    'MAX',
+];
 /**
- * Сообщение шага. Поля перечислены поимённо не ради валидации, а ради ОБНАРУЖИМОСТИ: раньше
- * здесь стоял безымянный объект, и «как задать в шаге WABA-шаблон вместо текста» неоткуда было
- * узнать — форма не описана ни в схеме тула, ни в OpenAPI.
+ * Регистр приводится, а значение — нет.
  *
- * `.passthrough()` обязателен: конфиги несут поля вне этого списка (wabaVariableMapping и др.),
- * а схема живёт на машине оператора и обновляется независимо от бэкенда.
+ * Отгруженный клиент шлёт `Telegram`, и отказывать ему было бы поломкой работающего вызова:
+ * значение то же, отличается только написание. А вот незнакомый транспорт отвергается здесь же —
+ * иначе он дошёл бы до приведения к перечислению и обрушил весь запрос.
  */
-const followUpMessageConfigSchema = z
-    .object({
-    type: z
-        .string()
-        .nullish()
-        .describe("'text' — обычный текст в content; 'template' — ШАБЛОН WABA (Wazzup), тогда обязателен " +
-        "templateId; 'media' — вложения. Шаблон уходит и при ЗАКРЫТОМ 24-часовом окне " +
-        'переписки, обычный текст — нет (шаг молча ждёт реплики клиента)'),
-    content: z.string().nullish().describe('Текст для type=text'),
-    templateId: z
-        .string()
-        .nullish()
-        .describe('ID шаблона WABA. Берётся из besales_wazzup_templates_list — это id шаблона канала, ' +
-        'а не его имя'),
-    templateValues: z
-        .array(z.unknown())
-        .nullish()
-        .describe('Значения подстановок шаблона по порядку ({{1}}, {{2}}, …). Поддерживают переменные ' +
-        'контакта — они резолвятся перед отправкой'),
-    contentMode: z
-        .string()
-        .nullish()
-        .describe("'static' (по умолчанию) либо 'dynamic' — текст генерирует LLM"),
-    generationContext: z.string().nullish().describe('Инструкция LLM при contentMode=dynamic'),
-    fallbackContent: z.string().nullish().describe('Запасной текст, если генерация не удалась'),
-    attachments: z
-        .array(z.unknown())
-        .nullish()
-        .describe('Вложения: [{ storedFileId, caption? }]'),
-    buttons: z.array(z.unknown()).nullish(),
-    crmNote: z.string().nullish(),
-})
-    .passthrough();
-const reactivationStepSchema = z
-    .object({
-    stepType: z.enum(['message', 'webhook']).optional(),
-    scheduleMode: z
-        .enum(['offset', 'clock'])
-        .optional()
-        .describe("'clock' — время суток + сдвиг дней вместо задержки от последней активности"),
-    anchorMode: z
-        .enum(['last_inbound', 'variable'])
-        .optional()
-        .describe("'variable' — расписание считается от даты из переменной контакта (календарная цепочка)"),
-    anchorVariable: z
-        .string()
-        .optional()
-        .describe('Имя переменной с якорной датой. Обязательно при anchorMode=variable; переменная должна ' +
-        'существовать у платформы и НЕ быть константой'),
-    atTime: z.string().optional().describe('Время суток "HH:MM" для scheduleMode=clock'),
-    // ⚠️ Нижняя граница — зеркало бэкенда (`MIN_CLOCK_DAY_OFFSET = -7`): отрицательный сдвиг —
-    // касание ДО якоря («накануне эфира»). С `min(0)` MCP не мог пересохранить ни одну цепочку с
-    // такими шагами (21.09.2026: «Светлана» с шагами dayOffset -1 отвергалась целиком).
-    dayOffset: z
-        .number()
-        .int()
-        .min(-7)
-        .max(30)
-        .optional()
-        .describe('Сдвиг в днях от якоря для scheduleMode=clock; отрицательный — до якоря'),
-    validityMinutes: z
-        .number()
-        .optional()
-        .describe('Окно валидности слота. Крон ходит раз в 5 минут: окно меньше 5 минут он почти всегда пропустит'),
-    slotGroup: z
-        .string()
-        .optional()
-        .describe('Метка взаимоисключающих вариантов одного момента (first-match-wins). Варианты ОБЯЗАНЫ ' +
-        'идти в steps подряд: разнесённые по цепочке перестают быть взаимоисключающими'),
-    conditions: z
-        .array(variableConditionSchema)
-        .max(3)
-        .optional()
-        .describe('Условия на переменные контакта; не прошли — шаг пропускается'),
-    skipIfContactRepliedSincePreviousSlot: z.boolean().optional().describe("Не отправлять шаг, если клиент писал ПОСЛЕ предыдущего слота цепочки. Даёт правило «ответил — ближайшее касание пропускаем, через одно продолжаем»: ответ в 13:05 гасит касание в 16:00, а к 17:00 предыдущим слотом становится 16:00, ответ старше него — и цепочка идёт дальше. Прогресс при пропуске двигается, контакт не зависает. Только для календарного шага (scheduleMode=clock + anchorMode=variable): на остальных рантайм и так проверяет свежесть входящего, и флаг там отвергается."),
-    delayHours: z.number().optional(),
-    delayMinutes: z.number().optional(),
-    messageConfig: followUpMessageConfigSchema.optional(),
-    getcourse: z
-        .object({
-        delivery: z
-            .object({
-            mode: z.enum(['contact', 'all', 'explicit']),
-            transports: z
-                .array(z.enum([
-                'Site',
-                'Email',
-                'SMS',
-                'Telegram',
-                'Facebook',
-                'VK',
-                'Chatium',
-                'WhatsApp',
-                'Viber',
-                'MAX',
-            ]))
-                .optional()
-                .describe("Только для mode='explicit'; в остальных режимах бэкенд отвергнет поле"),
-        })
-            .passthrough()
-            .optional(),
-    })
-        .passthrough()
-        .optional()
-        .describe('Каналы отправки ШАГА, только GetCourse. По умолчанию (поля нет) набор решает состояние ' +
-        "контакта: ответил — ровно его канал, молчит — все его привязки. 'all' — привязки плюс " +
-        'канал ответа плюс Email/Сайт/Chatium; SMS в него НЕ входит (один текст на весь набор, ' +
-        "нужен свой короткий) и задаётся только через 'explicit' отдельным шагом. Пустое " +
-        'пересечение с разрешёнными каналами площадки — шаг пропускается, цепочка идёт дальше. ' +
-        'К шагу-вебхуку неприменимо'),
-})
-    .passthrough()
-    // ⚠️ Зеркалит правила бэкенда, чтобы промах ловился ЛОКАЛЬНО. Иначе вызов проходит нашу
-    // проверку, пользователь подтверждает запись, и только сервер отвечает 400 — самый дорогой
-    // момент, чтобы узнать про опечатку.
-    .superRefine((step, ctx) => {
-    const message = step.messageConfig;
-    const isDynamic = message?.contentMode === 'dynamic';
-    const hasAttachments = !!message?.attachments?.length;
-    if (message?.type === 'template' && !message.templateId) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ['messageConfig', 'templateId'],
-            message: 'Для type=template обязателен templateId (id шаблона из besales_wazzup_templates_list)',
-        });
-    }
-    if (message?.type === 'text' && !message.content && !isDynamic && !hasAttachments) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ['messageConfig', 'content'],
-            message: 'Для type=text обязателен content — кроме шага из одних вложений и contentMode=dynamic',
-        });
-    }
-    const delivery = step.getcourse?.delivery;
-    if (!delivery)
-        return;
-    if (step.stepType === 'webhook') {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ['getcourse', 'delivery'],
-            message: 'Набор каналов неприменим к шагу-вебхуку: он ничего не отправляет клиенту',
-        });
-        return;
-    }
-    if (delivery.mode !== 'explicit') {
-        if (delivery.transports !== undefined) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                path: ['getcourse', 'delivery', 'transports'],
-                message: `Список каналов допустим только при mode='explicit'; в режиме '${delivery.mode}' он был бы проигнорирован`,
-            });
-        }
-        return;
-    }
-    if (!delivery.transports?.length) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ['getcourse', 'delivery', 'transports'],
-            message: "Для mode='explicit' нужен непустой список каналов — иначе шаг не отправит ничего",
-        });
-        return;
-    }
-    // Один `commentText` на весь набор: длинный мессенджерный текст уехал бы в SMS целиком.
-    if (delivery.transports.includes('SMS') && delivery.transports.length > 1) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ['getcourse', 'delivery', 'transports'],
-            message: 'SMS нельзя смешивать с другими каналами: у отправки один текст на весь набор. Вынесите SMS отдельным шагом со своим коротким текстом',
-        });
-    }
-});
-export const reactivationConfigSchema = z
-    .object({
-    enabled: z.boolean().optional(),
-    filterMode: z
-        .enum(['status', 'eventType', 'variable'])
-        .optional()
-        .describe('БАЗОВЫЙ отбор контактов: по статусу CRM, по типу события платформы либо ' +
-        "'variable' = базового фильтра нет (отбор только по sequenceConditions). Условия по " +
-        'переменным ОРТОГОНАЛЬНЫ этому выбору и добавляются к нему через И — чтобы ветвить ' +
-        "цепочки по варианту рассылки, сохранив отбор по событию, бери 'eventType' и задай " +
-        "sequenceConditions, а НЕ 'variable'. Неизвестное значение НЕ включает ни один фильтр — " +
-        'цепочка уйдёт всем контактам канала, поэтому бэкенд отвергает такой конфиг'),
-    sequenceConditions: z
-        .array(variableConditionSchema)
-        .optional()
-        .describe('Условия принадлежности контакта цепочке, соединяются через И. Применяются при ЛЮБОМ ' +
-        "filterMode (при 'variable' обязателен и непуст, иначе цепочка не выберет никого). " +
-        'Ветвление по измерениям рассылки GetCourse: WAVE_MAILING_VARIANT — UUID варианта из ' +
-        'каталога воркспейса, а НЕ его имя («first-ver» будет отвергнут); WAVE_PRODUCT — код ' +
-        'продукта строчными без пробелов («dbo»); WAVE_FUNNEL — КЛЮЧ воронки (f-код «f11», ' +
-        'иначе вся строка строчными), а НЕ метка запуска («f11 — ВК NR ДБО» будет отвергнут); ' +
-        'WAVE_SEGMENT — имя сегмента. Значения проставляет запуск рассылки, у контакта без ' +
-        'рассылки их нет. ' +
-        'ВАЖНО: отдельные цепочки НЕ взаимоисключающи — прогресс изолирован по sequenceId, ' +
-        'поэтому безусловная «ловящая» цепочка рядом с eq A и eq B не подстрахует, а УДВОИТ ' +
-        'отправку. Набор цепочек обязан быть строгим разбиением: eq A, eq B и fallback ' +
-        'neq A AND neq B (у контакта без переменной eq/in → false, neq → true)'),
-    steps: z.array(reactivationStepSchema).min(1),
-    sessionTimeVariable: z.string().min(1).optional().describe("ИМЯ переменной контакта с ЧАСОМ события (ЧЧ:ММ), парное к anchorVariable шага, который задаёт ДАТУ. Нужно потому, что поле-якорь во внешней CRM хранит только дату, а разбор нормализует её в служебный ПОЛДЕНЬ: без этого поля агент в своём промпте видит «Эфир: 21.08.2026 12:00» при эфире в 19:00. Задаётся НА ЦЕПОЧКУ (час слота одинаков для всех касаний и всех дней — dayOffset сдвигает дату, не час). Хранится ИМЯ, а не сам час: цепочка отбирает контактов условием по этой же переменной, и вторая копия значения разошлась бы с отбором молча. На расписание НЕ влияет — его задают atTime шагов; поле читает только промпт агента. Значение у контакта вне ЧЧ:ММ игнорируется: печатается одна дата, выдуманный час не подставляется."),
-    sessionDayOffsets: z.array(z.number().int().min(0).max(30)).min(1).optional().describe("На каких dayOffset цепочки проходят САМИ эфиры ([0,1,2] — три дня подряд от якоря). Вывести из шагов нельзя: касания стоят и на днях без эфира (у вебинарной цепочки шаги занимают дни 0–5, а эфиров три — дни 4 и 5 это продажа), поэтому дни объявляются явно, как явно объявлено время в sessionTimeVariable. На расписание НЕ влияет — его задают atTime/dayOffset шагов; поле читает только промпт агента. Без объявления блок печатает ОДИН эфир по якорю: якорь несёт дату лишь ПЕРВОГО эфира, и на второй день агент видел «был вчера», не зная, что сегодня вечером эфир есть. Порядок задаёт нумерацию («эфир 2 из 3») и нормализуется по возрастанию."),
-    sessionDurationMinutes: z.number().int().positive().max(1440).optional().describe("Сколько минут длится эфир. Объявляется, ТОЛЬКО если длительность действительно известна: с ней блок промпта утверждает «идёт сейчас» и перестаёт это утверждать по её истечении, без неё — только «уже начался», то есть факт, который нельзя опровергнуть временем. Дефолта нет намеренно: подставленная длительность это утверждение о мире, сделанное за клиента, а такие утверждения агент пересказывает человеку. Читается только при объявленном sessionDayOffsets."),
-    contactVariablesOnSend: z
-        .record(z.string().min(1), z.string().min(1).max(500))
-        .refine((value) => Object.keys(value).length > 0 && Object.keys(value).length <= 10, {
-        message: 'от 1 до 10 переменных',
-    })
-        .optional()
-        .describe("Переменные, которые цепочка ЗАПИСЫВАЕТ контакту, как только РЕАЛЬНО отправила ему шаг-сообщение: { intro: \"это снова Светлана.\" }. Это «записка» для тех, кто будет писать человеку после цепочки. Рабочий пример — фраза знакомства: текст рассылки начинается с {intro}, у площадки рассылки объявлена КОНСТАНТА intro с обычной фразой («здравствуйте! Это Светлана, помощница…»), а цепочка персональной воронки пишет своим людям intro = «это снова Светлана…» — значение контакта в тексте рассылки побеждает умолчание, и человек после недели в воронке не получает знакомство заново. Настраивается НА ЦЕПОЧКУ, а не на шаг: шага, который доходит до всех, нет (лучший — 87 % людей), а запись на любом отправленном шаге покрывает 99 %. Пишется только после ПОДТВЕРЖДЁННОЙ отправки шага-сообщения (вебхук и неудавшаяся отправка не считаются); совпадающее значение повторно не пишется. Каждое имя обязано быть объявлено на площадке цепочки переменной КОНТАКТА (не константой) — иначе сохранение вернёт 400: при отправке опечатка была бы тихой. Не больше 10 переменных, значение — непустая строка до 500 символов (границы бэкенда MAX_CONTACT_VARIABLES_ON_SEND / MAX_CONTACT_VARIABLE_ON_SEND_VALUE_LENGTH)."),
-})
-    .passthrough();
+const waveTransportSchema = z.preprocess(
+// Регистр приводится ТОЛЬКО у чисто латинского слова. Приведение по Unicode принимает написания,
+// которых никто не объявлял: турецкая «ı» переходит в латинскую «I», и `SıTE` прошло бы как
+// `SITE`. Значение всё равно вышло бы верным, но принимать незаявленную форму — значит обещать
+// поведение, которого нет в контракте.
+(value) => (typeof value === 'string' && /^[a-z]+$/iu.test(value) ? value.toUpperCase() : value), z.enum(WAVE_TRANSPORTS));
+/**
+ * Потолок значений в одном фильтре. Столько же держит сервер: длинный `IN` вырождает план запроса.
+ *
+ * Отгруженная схема предела не объявляла, поэтому предел — ОСОЗНАННОЕ ужесточение против неё, и
+ * оно объявлено строками реестра отставания. Без него схема разрешала бы вызов, который сервер
+ * отвергает: инструмент обещал бы то, чего не может.
+ */
+const REACTION_FILTER_MAX_VALUES = 50;
 /**
- * Применяет типизированную схему к `config` ТОЛЬКО для реактивационных цепочек.
+ * Многозначный фильтр уходит ПОВТОРЯЮЩИМИСЯ параметрами (`?segment=a&segment=b`).
  *
- * Через `z.union([reactivationConfigSchema, anyObjectSchema])` это делать нельзя: второй вариант
- * принимает любой объект, поэтому union проходит всегда и ограничения (`steps.min(1)`,
- * `filterMode` enum) не срабатывают ни разу — типизация выглядит рабочей, но её нет.
+ * Список через запятую здесь непригоден: приёмная сторона приводит одиночное значение к массиву,
+ * поэтому строка `a,b` стала бы ОДНИМ значением с запятой внутри. Разрез вышел бы пустым при
+ * непустой цифре — и отказа при этом не было бы, была бы тихая ложь.
  *
- * @param input - Разобранный ввод тула
- * @param ctx - Контекст zod для добавления ошибок
+ * Пустой массив не добавляет ни одного параметра, то есть читается как «фильтра нет». Отвергать
+ * его нельзя: отгруженный инструмент такой вызов принимает, и отказ сломал бы работающего клиента.
  */
-export const refineFollowUpConfig = (input, ctx) => {
-    if (input.type !== 'INACTIVE_USER_REACTIVATION') {
-        return;
+function appendFilter(params, name, values) {
+    for (const value of values ?? []) {
+        params.append(name, value);
     }
-    const parsed = reactivationConfigSchema.safeParse(input.config);
-    if (parsed.success) {
-        return;
+}
+function buildReactionsQuery(input) {
+    const params = new URLSearchParams();
+    params.set('from', input.from);
+    params.set('to', input.to);
+    if (input.horizon_minutes !== undefined) {
+        params.set('horizonMinutes', String(input.horizon_minutes));
     }
-    for (const issue of parsed.error.issues) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            path: ['config', ...issue.path],
-            message: issue.message,
-        });
+    if (input.run_window_days !== undefined) {
+        params.set('runWindowDays', String(input.run_window_days));
     }
-};
-export const followUpSequenceListSchema = z.object({
-    platform_id: uuidSchema,
-    sequence_id: uuidSchema
-        .optional()
-        .describe('Вернуть одну цепочку вместе с полным конфигом'),
-    include_config: z
-        .boolean()
-        .optional()
-        .describe('Отдать конфиги всех цепочек. По умолчанию не отдаются — они объёмные'),
-});
-export const followUpStepStatsSchema = z.object({
-    platform_id: uuidSchema,
-    sequence_id: uuidSchema,
-    from: z.string().optional().describe('Начало окна, ISO-дата. По умолчанию 30 дней назад'),
-    to: z.string().optional().describe('Конец окна, ISO-дата. По умолчанию сейчас'),
-});
-/** Горизонты сравнения, разрешённые бэкендом. Свободное число он отвергает 400. */
-const REACTION_HORIZONS = [30, 60, 90, 180, 360, 720, 1440];
-export const followUpReactionsSchema = z.object({
-    platform_id: uuidSchema,
-    from: z.string().describe('Начало периода по дате отправки шага, YYYY-MM-DD (московские сутки)'),
-    to: z
-        .string()
-        .describe('Конец периода, YYYY-MM-DD. Период длиннее 366 суток бэкенд отвергает'),
-    sequence_id: z
-        .array(uuidSchema)
-        .optional()
-        .describe('Фильтр цепочек. НЕ влияет на атрибуцию: окно ответа всегда считается по полной шкале ' +
-        'касаний контакта, иначе цифра менялась бы от набора фильтров'),
-    horizon_minutes: z
-        .union([
-        z.literal(REACTION_HORIZONS[0]),
-        z.literal(REACTION_HORIZONS[1]),
-        z.literal(REACTION_HORIZONS[2]),
-        z.literal(REACTION_HORIZONS[3]),
-        z.literal(REACTION_HORIZONS[4]),
-        z.literal(REACTION_HORIZONS[5]),
-        z.literal(REACTION_HORIZONS[6]),
-    ])
-        .optional()
-        .describe('Горизонт сравнительной метрики (на ШАГЕ). По умолчанию 90'),
-    run_window_days: z
-        .union([z.literal(1), z.literal(3), z.literal(5), z.literal(7), z.literal(14)])
-        .optional()
-        .describe('Окно ПРОХОЖДЕНИЯ цепочки для метрики runs: ответил ли человек хоть раз за N дней от ' +
-        'входа. По умолчанию 1. Не путать с horizon_minutes — там единица касание, здесь ' +
-        'прохождение.'),
-    segment: z
-        .array(z.string())
-        .optional()
-        .describe('Сегменты волны. Доступные значения приходят в ответе (`dimensions.segments`); у канала ' +
-        'без рассылок их нет вообще'),
-    product: z.array(z.string()).optional().describe('Продукты волны (`dimensions.products`)'),
-    channel: z
-        .array(z.string())
-        .optional()
-        .describe('Транспорты волны (`dimensions.channels`), например Telegram/WhatsApp/MAX/VK'),
-});
+    if (input.only_replied_contacts !== undefined) {
+        params.set('onlyRepliedContacts', String(input.only_replied_contacts));
+    }
+    appendFilter(params, 'sequenceId', input.sequence_id);
+    appendFilter(params, 'segment', input.segment);
+    appendFilter(params, 'product', input.product);
+    appendFilter(params, 'transport', input.channel);
+    appendFilter(params, 'mailingVariantId', input.mailing_variant_id);
+    return `?${params.toString()}`;
+}
 export const followUpTools = [
     defineTool({
         name: 'besales_followup_sequence_list',
         sideEffect: 'none',
         requiredFields: ['platform_id'],
+        // Перечень цепочек канала: besales_followup_sequence_upsert заменяет конфигурацию целиком,
+        // и работать по неполному перечню — значит не увидеть цепочку, которую собирался править.
         resultPolicy: { neverTruncate: true },
-        schema: followUpSequenceListSchema,
-        // Параметры клеим в путь: транспорт (`ApiToolRequest`) знает только method/path/body, и
-        // отдельное поле `query` было бы молча выброшено — тул вернул бы 200 без учёта фильтров.
+        schema: z.object({
+            platform_id: uuidSchema,
+            sequence_id: uuidSchema.optional(),
+            include_config: z.boolean().optional(),
+            // ⚠️ Без умолчания: замещающая запись меняет конфигурацию цепочки целиком, и неполный
+            // перечень означает не увидеть цепочку, которую собирался править.
+            limit: z.number().int().min(1).max(FOLLOWUP_SEQUENCES_MAX_PAGE_SIZE).optional(),
+            cursor: z.string().min(1).optional(),
+        }),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/platforms/${input.platform_id}/follow-up/sequences${buildListQuery({
-                sequence_id: input.sequence_id,
-                include_config: input.include_config,
+            path: `/channels/${input.platform_id}/followup-sequences${buildListQuery({
+                sequenceId: input.sequence_id,
+                includeConfig: input.include_config,
+                limit: input.limit,
+                cursor: input.cursor,
             })}`,
         }),
-        enhanceResponse: (response) => withInstructions(response, [
-            'besales_followup_sequence_upsert заменяет config ЦЕЛИКОМ: прочитай конфиг здесь (sequence_id) и пришли ПОЛНЫЙ желаемый набор шагов, а не дельту.',
-            'Без sequence_id и include_config конфиги не отдаются — так список остаётся дешёвым по контексту.',
+        enhanceResponse: (response, input) => withInstructions(assertCompleteList(response, {
+            pageRequested: input.limit !== undefined || input.cursor !== undefined,
+            toolName: 'besales_followup_sequence_list',
+            howToPage: `Позовите снова с limit (до ${FOLLOWUP_SEQUENCES_MAX_PAGE_SIZE}) и продолжайте по cursor, пока он не станет пустым.`,
+        }), [
+            'Каждый элемент результата — WorkflowView follow-up цепочки канала; актуальная версия в latestVersion, исполняемые шаги — в latestVersion.steps.',
+            'latestVersion.steps — РЕЗУЛЬТАТ трансляции, а не вход besales_followup_sequence_upsert. Upsert принимает конфигурацию в форме v1.5 (steps/finalAction/filterMode/sequenceConditions), трансляция односторонняя, и обратной функции нет: скопировать сюда прочитанные шаги нельзя — запрос будет отклонён.',
+            'include_config=true возвращает type, trigger и config дословно; sequence_id включает конфигурацию автоматически. Для обзора используй limit; пустой список с sequence_id означает, что такой цепочки на канале нет.',
+            'config:null с FOLLOWUP_CONFIG_NOT_WRITTEN_BY_FORM означает, что версию записали общим редактором или клоном канала: сохрани всю цепочку формой дожимов, чтобы открыть чтение и точечную правку. FOLLOWUP_TRIGGER_CHANGED_OUTSIDE_FORM означает, что настройки изменили вне формы; сначала восстанови полную конфигурацию.',
+            'Для одной фразы используй besales_followup_step_message_set. При полной записи передай прочитанный config целиком.',
+            crmStagePoolMessage('hint'),
+            'Настройка «выключать дожимы у оплатившего» видна как triggerConfig.stop_on_payment = true. Upsert заменяет конфигурацию целиком: правя такую цепочку, передай config.stopOnPayment: true, иначе стоп выключится (журнал аудита цепочки фиксирует только факт смены настройки, без значений).',
+            'contactVariablesOnSend в строке цепочки — именованная записка; при полной правке передай её обратно в config.contactVariablesOnSend, иначе запись снимется.',
         ]),
     }),
     defineTool({
         name: 'besales_followup_step_stats',
         sideEffect: 'none',
         requiredFields: ['platform_id', 'sequence_id'],
-        schema: followUpStepStatsSchema,
+        schema: z.object({
+            platform_id: uuidSchema,
+            sequence_id: uuidSchema,
+            from: stepStatsBoundSchema.optional(),
+            to: stepStatsBoundSchema.optional(),
+        }),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/platforms/${input.platform_id}/follow-up/sequences/${input.sequence_id}/step-stats${buildListQuery({ from: input.from, to: input.to })}`,
+            path: `/channels/${input.platform_id}/followup-sequences/${input.sequence_id}/step-stats${buildListQuery({ from: input.from, to: input.to })}`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'wasSent=false НЕ означает «отправка не удалась»: SEND_FAILED пишется только если до fence не дошло (мьют, стадия CRM, тихий канал).',
-            'SHADOWED — вариант слота, который не оценивался, потому что слот уже закрыт отправкой другого варианта. Это не ошибка.',
-            'SENT_UNVERIFIED — отправка зависла после fence: исходом владеет recovery, повтор запрещён.',
-            'waitingUpperBound — ВЕРХНЯЯ оценка ожидающих: прогресс создаётся всем включённым цепочкам платформы без проверки sequenceConditions.',
-            'Окно по умолчанию — 30 дней; для более раннего периода передай from/to.',
+            'Ответ — объект: steps (шаги сообщения ТЕКУЩЕЙ версии по порядку, position с нуля, нулевые включены; удалённые шаги не показываются), contactsInChain, sequenceEnabled, применённое окно from/to и executionSteps. Единица счёта — попытка шага, а не человек.',
+            'По шагу: sent — доказанно ушло; sendFailed — не ушло (отказ канала, подавление доставки, запрет политики; закрытый срок переписки сюда не попадает — шаг ждёт); sentUnverified — канал мог принять, повтор запрещён: ни успех, ни отказ.',
+            'skipped — пропуски по причинам: ключ — код причины, человеку называй подпись label из byOutcome, а не код. «Не проверялось, время слота занял вариант выше» тоже здесь — это устройство слота, а не сбой.',
+            'failedConditions — технические ключи непрошедших условий: переменная, contact.<поле>, tag/tag:<имя> или служебное поле. Человеку называй label из byOutcome.variables; ключом не подменяй подпись.',
+            'waitingUpperBound — люди в идущих прогонах, чей следующий шаг сообщения — этот; не все его получат. Людей, кому цепочка ещё не запускалась, здесь нет — точная очередь ожидающих есть в отчёте воронки. contactsInChain — люди, у кого был прогон, плюс перенесённый прогресс прежней системы: после переключения число стартует почти с нуля.',
+            'sequenceEnabled = false — цепочка выключена: нули значат «остановлена», а не «никого нет».',
+            'Окно по умолчанию — последние 30 суток. from/to — дата ГГГГ-ММ-ДД (сутки в поясе канала, у конца включается весь последний день) или момент с часовым поясом; ответ называет применённое окно.',
+            'executionSteps — исполнение шагов любого вида по журналу прогонов (completed/failed/skipped и последний старт): так видно, что падает, например, шаг CRM.',
         ]),
     }),
     defineTool({
         name: 'besales_followup_reactions',
         sideEffect: 'none',
+        // Порядок обязательных полей повторяет отгруженную схему: паритет сверяется равенством
+        // массивов, а не множеств.
         requiredFields: ['platform_id', 'from', 'to'],
-        schema: followUpReactionsSchema,
+        schema: z
+            .object({
+            platform_id: uuidSchema,
+            from: calendarDateSchema,
+            to: calendarDateSchema,
+            sequence_id: z.array(uuidSchema).max(REACTION_FILTER_MAX_VALUES).optional(),
+            horizon_minutes: reactionHorizonSchema
+                .optional()
+                .describe('Горизонт сравнительной метрики, минуты. Набор закрыт. Если не передан, сервер подбирает горизонт по доле вырезанных касаний; выбранное значение и причину смотри в horizonMinutes и horizonReason ответа.'),
+            run_window_days: reactionRunWindowSchema.optional(),
+            only_replied_contacts: z.boolean().optional(),
+            segment: z.array(z.string()).max(REACTION_FILTER_MAX_VALUES).optional(),
+            product: z.array(z.string()).max(REACTION_FILTER_MAX_VALUES).optional(),
+            channel: z.array(waveTransportSchema).max(REACTION_FILTER_MAX_VALUES).optional(),
+            // Сверх отгруженной схемы: ответ отдаёт справочник dimensions.mailingVariants, и без
+            // фильтра он был бы носителем без читателя — значения видно, выбрать по ним нельзя.
+            // Входного asOf у моста нет. Сервер возвращает calculatedAt для раскрытия через API
+            // с тем же H и asOf; граница времени событий не фиксирует данные между запросами.
+            mailing_variant_id: z.array(uuidSchema).max(REACTION_FILTER_MAX_VALUES).optional(),
+        })
+            .strict(),
         createRequest: (input) => ({
             method: 'GET',
-            // ⚠️ Ключи query — camelCase, в отличие от snake_case параметров тула: этот эндпоинт
-            // разбирает их в DTO с `forbidNonWhitelisted`, и `sequence_id` вернул бы 400
-            // «property should not exist». Соседний `sequence_list` принимает snake_case потому, что
-            // его контроллер объявляет параметры поштучно, — на него ориентироваться нельзя.
-            path: `/platforms/${input.platform_id}/follow-up/reactions${buildListQuery({
-                from: input.from,
-                to: input.to,
-                sequenceId: input.sequence_id,
-                horizonMinutes: input.horizon_minutes,
-                runWindowDays: input.run_window_days,
-                segment: input.segment,
-                product: input.product,
-                channel: input.channel,
-            })}`,
+            path: `/channels/${input.platform_id}/followup-sequences/reactions${buildReactionsQuery(input)}`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Метрик ТРИ и они НЕ взаимозаменяемы (третья — runs, см. ниже). `replied` — операционная: у каждого шага СВОЁ окно (до следующего касания), поэтому шаг с суточным интервалом почти всегда выглядит лучше часового. Сравнивать шаги по ней НЕЛЬЗЯ.',
-            'Сравнивать шаги можно ТОЛЬКО по `horizonReplied` (равный горизонт) и ТОЛЬКО там, где `comparableReliable: true`.',
-            'comparableReliable=false означает, что доля ЗАВЫШЕНА, а не просто шумна: цензурирование информативно — следующий шаг уходит лишь к промолчавшим, поэтому выжившие обогащены ответившими. Замер: 67 % вырезанных дали 20,8 % против настоящих 5,5 %. Первое лечение — horizon_minutes КОРОЧЕ интервала между шагами.',
-            'Но у частых цепочек подходящего горизонта НЕ СУЩЕСТВУЕТ: у вебинарной цепочки 35 % касаний имеют следующий шаг раньше 15 минут, то есть их вырезает даже минимальный горизонт 30. Не подбирай горизонт бесконечно — переходи на метрику runs.',
-            'runs — ТРЕТЬЯ метрика и ДРУГАЯ единица: прохождение цепочки, а не касание. «Ответил ли хоть раз за run_window_days от входа». Вырезать там некого (все шаги внутри окна принадлежат этому же прохождению), поэтому частота пингов на неё не влияет. Отвечает «работает ли цепочка», а НЕ «какой шаг сработал» — текст шага по ней не оптимизируется.',
-            'runs.immature — прохождения, у которых окно ещё не вышло. Они НЕ входят в runs.started, то есть доля считается от созревших. Растёт окно — растёт и число незрелых: это размен по ВРЕМЕНИ, а не по выборке.',
-            'Сравнивать ВЕРСИИ одного шага (A/B текста) надо по replied, а не по horizonReplied: у версий одного шага пауза до следующего касания одинаковая, значит окно равное и сравнение честное.',
-            'Знаменатели разные: `replied` считается от `resolvedSent` (без ещё открытых окон), `horizonReplied` — от `comparableSent`. От `sent` не считается НИ ОДНА доля.',
-            '`horizonEngaged` — отреагировали ХОТЬ КАК-ТО в том же горизонте: ответили ИЛИ перешли по ссылке касания. Знаменатель тот же (`comparableSent`), разность `horizonEngaged - horizonReplied` — те, кто НЕ ответил, но кликнул. Молчание на текст ещё не значит, что касание не сработало.',
-            '⚠️ НЕ складывай `horizonReplied` и `linkClicked`: ответивший часто ещё и кликает, и сумма задваивает его. Объединение уже посчитано — это `horizonEngaged`. `linkClicked` отвечает на другой вопрос (CTR ссылки) и считается от `linkIssued` бессрочно, без горизонта.',
-            'Ответ атрибутируется РОВНО ОДНОМУ касанию — ближайшему предшествующему. Окно закрывают шаг любой цепочки, волна рассылки и реплика живого оператора.',
-            'Цепочки с `measurable: false` шагов не записывают вообще (LOST_CLIENTS): их отсутствие в byStep означает «не меряем», а не «не работает».',
-            'Пустые массивы в `dimensions` — у канала нет рассылок, срезы по сегменту/продукту/мессенджеру там недоступны в принципе.',
-            'anchorExactShare < 1 — у части строк время отправки записано пакетно (отставание секунды). На окне в десятки минут это меньше процента.',
+            'Зерно всех цифр — КАСАНИЕ (одна отправка контакту), а не человек: один контакт за период даёт столько строк, сколько раз мы ему писали.',
+            'Метрик ДВЕ и они несводимы. Операционная доля replied / resolvedSent считает только ответы в окне до СЛЕДУЮЩЕГО касания с потолком 72 часа, поэтому следует за длиной окна: у последнего шага цепочки окно всегда шире, и по ней шаги между собой сравнивать НЕЛЬЗЯ.',
+            'Реакция — живой ответ OR настоящий клик ссылки этого касания: horizonEngaged объединяет их без двойного счёта. horizonReplied отдельно считает только ответы; не складывай эти числители.',
+            'Сравнительная доля horizonEngaged / comparableSent использует horizonMinutes из ответа (selected H), один для всех строк. Без horizon_minutes сервер подбирает горизонт сам; причину показывает horizonReason. Все события и зрелость ограничены calculatedAt (asOf). У этого инструмента нет входа asOf и раскрытия строк: calculatedAt описывает снимок одного ответа и не закрепляет данные между HTTP-запросами.',
+            'Сравнивай только строки с comparableSent > 0 и comparableReliable=true. horizonReason=noData означает отсутствие зрелого пула; noReliableHorizon — нет надёжного горизонта. Ни noData, ни requested не разрешают сравнивать пустые группы.',
+            'censored — все необратимо прерванные окна; maturedCensored — только достигшие sentAt + H ≤ asOf. censoredShare = maturedCensored / (comparableSent + maturedCensored); при пустом пуле сервер возвращает 0, это не доказательство сравнимости. Не подставляй terminal censored в знаменатель.',
+            'ambiguous — ничьи: касание другого производителя в тот же момент. Они исключены и из числителей, и из знаменателя, поэтому attributableSent меньше sent ровно на ambiguous.',
+            'Равенства сервера: sent = ambiguous + attributableSent; attributableSent = comparableSent + censored + immature. Общей корзины scopeUnresolved нет. Прерванная строка сопоставимой уже не станет.',
+            'totals и runs не пересчитывай из строк моделью. runs имеет grain=passage и periodBasis=passageStartedAt, отдельное окно windowDays; с funnelId runs=null, runsUnavailableReason=funnelEntryGrain. Клик не является ответом агента и не создаёт глубокий диалог или оплату.',
+            'byDayStep — разрез сутки × шаг по всем выбранным цепочкам, включая выбор нескольких цепочек. Это может быть большой массив строк.',
+            'Условия шага называются техническим ключом contact.<поле>, tag/tag:<имя>; человекочитаемый label из byOutcome.variables служит подписью, а не ключом фильтра.',
+            'runs — отдельный блок прохождений. run_window_days выбирает окно ответа в сутках: 1, 3, 5, 7 или 14; по умолчанию 1. Отсутствие параметра не выключает блок.',
+            'only_replied_contacts оставляет в цифрах только контакты с живым входящим до снимка расчёта. Линза меняет состав строк, поэтому доли с ней и без неё несопоставимы; каталог dimensions и признак измеримости цепочки остаются общими.',
+            'sequences отдаёт ПОЛНЫЙ каталог цепочек воркспейса. measurable=false с unmeasurableReason=noTouchesInPeriod означает «в периоде касаний не было», а не «цепочка сломана» — чинить там нечего. Признак считается отдельно от разреза и фильтрами не искажается.',
+            'Разрезы segment/product/channel/mailingVariantId существуют только у каналов с рассылками; допустимые значения бери из dimensions ответа, а не выдумывай.',
+            'Незнакомый сегмент или продукт даёт пустой разрез, а вот незнакомый ТРАНСПОРТ отвергается: сервер приводит его к перечислению, и посторонняя строка уронила бы весь запрос. Метки транспорта — в верхнем регистре (TELEGRAM, WHATSAPP, MAX, VK), их же отдаёт dimensions.transports.',
+            'handedOff и crmStageMoved — исходы дожима помимо ответа в переписке. Переход сделки по стадиям измерим и там, где рассылок нет вовсе.',
+            'Период считается по дате отправки касания в поясе КАНАЛА; длиннее 366 суток сервер отвергает.',
         ]),
     }),
 ];