@besales/mcp 0.48.0 → 1.0.0-beta.2

package/dist/tools/definitions/agent-design.js

@@ -1,6 +1,29 @@
+import { icpImportSourceSchema, legacyIcpImportConfigSchema } from './icp-import-source.js';
 import { z } from 'zod';
-import { analysisModeSchema, anyObjectSchema, buildListQuery, compactMetadata, compactObject, defineTool, generatedScenarioSchema, icpAnalysisPersonaSchema, icpAnalysisSegmentSchema, optionalAnyObjectSchema, outcomeSchema, promptAnalysisStageOutputSchema, promptGenerationStageOutputSchema, sandboxFindingSchema, simulationFindingSchema, uuidSchema, withInstructions, } from './shared.js';
+import { assertCompleteList } from '../incomplete-list.js';
+import { PROMPT_LANGUAGE_CODE_MAX_LENGTH } from './prompt-authoring.constants.js';
+import { ICP_SCENARIOS_MAX_PAGE_SIZE, analysisModeSchema, anyObjectSchema, buildListQuery, compactMetadata, compactObject, defineTool, generatedScenarioSchema, icpAnalysisPersonaSchema, icpAnalysisSegmentSchema, knowledgeSpaceIdSchema, optionalAnyObjectSchema, outcomeSchema, promptAnalysisStageOutputSchema, promptGenerationStageOutputSchema, sandboxFindingSchema, simulationFindingSchema, uuidSchema, withInstructions, } from './shared.js';
 const SANDBOX_TERMINAL_STATUSES = new Set(['COMPLETED', 'FAILED', 'CANCELLED']);
+const ICP_CONTINUATION_INSTRUCTIONS = 'continuationState: AVAILABLE — остаток можно продолжить; FORWARDED — уже создан следующий прогон; EXPIRED — остаток устарел; NONE — продолжения нет. remainderExpiredAt — момент удаления старого остатка уборкой, null — уборка ещё не удаляла строки. ICP_INGEST_CONTINUATION_EXPIRED (409): остаток выборки устарел — начните новый импорт. Не повторяй продолжение автоматически; новый импорт запускай по решению человека с новым request_key и gdpr_confirmed=true.';
+const AUDIO_DATE_FIELDS = {
+    bitrix_openlines: { startDate: 'createdFrom', endDate: 'createdTo' },
+    onlinepbx_direct: { startDate: 'startedFrom', endDate: 'startedTo' },
+};
+function audioSourceConfig(sourceType, config) {
+    if (config === undefined)
+        return undefined;
+    const fields = AUDIO_DATE_FIELDS[sourceType ?? ''];
+    if (fields === undefined)
+        return config;
+    const result = { ...config };
+    for (const [oldName, newName] of Object.entries(fields)) {
+        if (Object.hasOwn(result, oldName)) {
+            result[newName] = result[oldName];
+            delete result[oldName];
+        }
+    }
+    return result;
+}
 function enhanceSandboxStatus(response) {
     if (!response || typeof response !== 'object' || Array.isArray(response)) {
         return response;
@@ -35,9 +58,7 @@ export const agentDesignTools = [
             workspace_id: uuidSchema.optional(),
             name: z.string(),
             description: z.string().optional(),
-            source: z
-                .enum(['from_dialogues', 'from_files', 'from_scratch'])
-                .default('from_scratch'),
+            source: z.enum(['from_dialogues', 'from_files', 'from_scratch']).default('from_scratch'),
         }),
         createRequest: (input) => ({
             path: `/workspaces/${input.workspace_id}/icp`,
@@ -51,102 +72,192 @@ export const agentDesignTools = [
     defineTool({
         name: 'besales_icp_import_dialogues',
         // Имя проверки из имени операции не выводится: суффиксы не парные.
-        verifyWithToolName: 'besales_icp_import_status',
+        verifyWithToolName: 'besales_icp_import_start_result',
         sideEffect: 'spend',
-        requiredFields: ['icp_id'],
+        requiredFields: ['icp_id', 'request_key', 'gdpr_confirmed'],
+        /** Канонический источник и обе прежние формы используют один keyed-приём. */
         schema: z
             .object({
             icp_id: uuidSchema,
-            /**
-             * mode='text' (default) — импорт сохранённых текстовых диалогов из CRM history.
-             * mode='audio' — batch audio path через transcription-service: тянем call recordings
-             *   из источника (amocrm_leads / xlsx_upload / onlinepbx_direct), прогоняем через
-             *   Yandex SpeechKit STT, создаём IcpDialogueSample из транскрипта.
-             */
+            request_key: uuidSchema,
+            source: icpImportSourceSchema.optional(),
             mode: z.enum(['text', 'audio']).default('text'),
-            // --- Text mode (legacy CRM history) ---
             crm_connection_id: uuidSchema.optional(),
-            outcome_filter: z.array(outcomeSchema).default(['won', 'lost']),
-            days_ago: z.number().int().min(1).max(730).default(180),
-            anonymize: z.boolean().default(true),
-            gdpr_confirmed: z.boolean().optional(),
-            // --- Audio mode (Phase 4 + Track B onlinePBX) ---
+            outcome_filter: z.array(outcomeSchema).min(1).optional(),
+            days_ago: z.number().int().min(1).max(730).optional(),
+            gdpr_confirmed: z.literal(true),
+            anonymize: z.literal(true).optional(),
             audio_source_type: z
-                .enum(['amocrm_leads', 'xlsx_upload', 'onlinepbx_direct', 'bitrix_openlines'])
+                .enum([
+                'bitrix_open_lines',
+                'amocrm_calls',
+                'onlinepbx_calls',
+                'xlsx_upload',
+                'bitrix_openlines',
+                'amocrm_leads',
+                'onlinepbx_direct',
+            ])
                 .optional(),
+            audio_source_config: legacyIcpImportConfigSchema.optional(),
+            continuation_run_id: z.string().uuid().optional(),
             /**
-             * Конфиг источника аудио — shape зависит от audio_source_type:
-             *   - amocrm_leads:     { crmConnectionId, leadIds[], defaultOutcome? }
-             *   - xlsx_upload:      { storedFileId, crmConnectionId }  (xlsx загрузи через POST /v2/files)
-             *   - onlinepbx_direct: { startDate, endDate, minDurationSec?=60, direction?='all',
-             *                         matchToCrm?=true, crmConnectionId?, defaultOutcome?='unknown',
-             *                         dryRun?=false, trunkId? } — звонки из onlinePBX за период,
-             *                         опц. матчинг к AmoCRM по телефону → outcome. dryRun=true →
-             *                         только подсчёт (status=DRY_RUN, totalRefs=count) без запуска STT.
-             *   - bitrix_openlines: { crmConnectionId, startDate, endDate, categoryId?, dryRun? } —
-             *                         ТЕКСТОВЫЕ диалоги из Bitrix open-lines (сделки за период), без STT.
-             * NB: xlsx_drive (Google Drive) НЕ поддерживается бэкендом (MVP) — backend → 400.
+             * Язык распознавания записей звонков этой ветки.
+             *
+             * Набор ЗАКРЫТЫЙ и совпадает с набором сателлита распознавания — тем же, что у
+             * отгруженного контракта. Не задан — определение по звуку. Сервер отвергает значение вне
+             * набора: сателлит привёл бы незнакомое к автоопределению молча, и опечатка выглядела бы
+             * как принятая настройка.
              */
-            audio_source_config: optionalAnyObjectSchema,
             language: z.enum(['ru-RU', 'uz-UZ', 'kk-KZ', 'auto']).optional(),
         })
             .superRefine((value, ctx) => {
+            if (value.source !== undefined) {
+                if (value.audio_source_type !== undefined ||
+                    value.audio_source_config !== undefined ||
+                    value.crm_connection_id !== undefined ||
+                    value.outcome_filter !== undefined ||
+                    value.days_ago !== undefined)
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ['source'],
+                        message: 'Выбери одну форму источника',
+                    });
+                return;
+            }
             if (value.mode === 'audio') {
-                if (!value.audio_source_type || !value.audio_source_config) {
+                const config = value.audio_source_config;
+                const fields = AUDIO_DATE_FIELDS[value.audio_source_type ?? ''];
+                if (config !== undefined && fields !== undefined) {
+                    for (const [oldName, newName] of Object.entries(fields)) {
+                        if (Object.hasOwn(config, oldName) && Object.hasOwn(config, newName)) {
+                            ctx.addIssue({
+                                code: z.ZodIssueCode.custom,
+                                path: ['audio_source_config', oldName],
+                                message: `Пришли оба имени audio_source_config.${oldName} и audio_source_config.${newName}: оставьте одно`,
+                            });
+                        }
+                    }
+                }
+                if (value.audio_source_type === undefined) {
                     ctx.addIssue({
                         code: z.ZodIssueCode.custom,
-                        message: 'audio_source_type и audio_source_config обязательны при mode=audio',
+                        message: 'audio_source_type обязателен при mode=audio',
                         path: ['audio_source_type'],
                     });
                 }
-            }
-            else {
-                if (!value.crm_connection_id || value.gdpr_confirmed !== true) {
+                if (value.audio_source_config === undefined) {
                     ctx.addIssue({
                         code: z.ZodIssueCode.custom,
-                        message: 'crm_connection_id и gdpr_confirmed обязательны при mode=text',
-                        path: ['crm_connection_id'],
+                        message: 'audio_source_config обязателен при mode=audio',
+                        path: ['audio_source_config'],
                     });
                 }
-            }
-        }),
-        createRequest: (input) => {
-            if (input.mode === 'audio') {
-                return {
-                    method: 'POST',
-                    path: `/icp/audio-import-runs`,
-                    body: compactObject({
-                        icpProfileId: input.icp_id,
-                        sourceType: input.audio_source_type,
-                        sourceConfig: input.audio_source_config,
-                        language: input.language,
-                    }),
+                const normalized = {
+                    ...audioSourceConfig(value.audio_source_type, value.audio_source_config),
+                    kind: {
+                        bitrix_openlines: 'bitrix_open_lines',
+                        amocrm_leads: 'amocrm_calls',
+                        onlinepbx_direct: 'onlinepbx_calls',
+                    }[value.audio_source_type ?? ''] ?? value.audio_source_type,
                 };
+                const parsed = icpImportSourceSchema.safeParse(normalized);
+                if (!parsed.success)
+                    ctx.addIssue({
+                        code: z.ZodIssueCode.custom,
+                        path: ['audio_source_config'],
+                        message: 'Неверный отбор источника',
+                    });
+                return;
             }
-            return {
-                path: `/icp/${input.icp_id}/samples/import-from-crm`,
-                body: {
-                    crmConnectionId: input.crm_connection_id,
-                    outcomeFilter: input.outcome_filter,
-                    ageFilter: { daysAgo: input.days_ago },
-                    anonymize: input.anonymize,
-                    gdprConfirmed: input.gdpr_confirmed,
-                },
-            };
-        },
-        enhanceResponse: (response, input) => {
-            if (input.mode === 'audio') {
-                return withInstructions(response, [
-                    'Audio import — асинхронный. Получи runId из response.',
-                    'onlinepbx_direct + dryRun=true → response.status=DRY_RUN, totalRefs=число звонков ' +
-                        'после фильтра (Run НЕ создан). Подтверди объём и повтори с dryRun=false для импорта.',
-                    'Опрашивай статус через besales_icp_import_status каждые 30-60 сек.',
-                    'Терминальные статусы: COMPLETED, PARTIAL, FAILED.',
-                    'При PARTIAL — часть items expired/failed, но успешные диалоги уже в IcpDialogueSample.',
-                ]);
+            if (value.crm_connection_id === undefined) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: 'crm_connection_id обязателен при mode=text',
+                    path: ['crm_connection_id'],
+                });
             }
-            return response;
-        },
+            if (value.gdpr_confirmed !== true) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: 'gdpr_confirmed должен быть true для импорта диалогов',
+                    path: ['gdpr_confirmed'],
+                });
+            }
+        }),
+        createRequest: (input) => ({
+            path: '/icp/' + input.icp_id + '/import-runs',
+            body: compactObject({
+                requestKey: input.request_key,
+                gdprConfirmed: input.gdpr_confirmed,
+                source: input.source ??
+                    (input.mode === 'audio'
+                        ? {
+                            ...audioSourceConfig(input.audio_source_type, input.audio_source_config),
+                            kind: {
+                                bitrix_openlines: 'bitrix_open_lines',
+                                amocrm_leads: 'amocrm_calls',
+                                onlinepbx_direct: 'onlinepbx_calls',
+                            }[input.audio_source_type ?? ''] ?? input.audio_source_type,
+                        }
+                        : {
+                            kind: 'stored_crm_dialogues',
+                            crmConnectionId: input.crm_connection_id,
+                            outcomeFilter: input.outcome_filter,
+                            daysAgo: input.days_ago,
+                        }),
+                transcriptionLanguage: input.language,
+                continuationRunId: input.continuation_run_id,
+            }),
+        }),
+        enhanceResponse: (response, input) => (input.source === undefined
+            ? input.mode === 'audio'
+            : input.source.kind !== 'stored_crm_dialogues')
+            ? withInstructions(response, [
+                ICP_CONTINUATION_INSTRUCTIONS,
+                'При потерянном ответе вызови besales_icp_import_start_result с теми же icp_id/request_key. NOT_FOUND_UNKNOWN не доказывает отказ: повтори исходное намерение с тем же ключом. Ингест асинхронный: перечисление диалогов прошло, содержимое каждого добывается в фоне. Возьми runId из ответа и опрашивай besales_icp_import_status раз в 30-60 сек.',
+                'Неизвестный род источника сервер отвергает, перечисляя построенные в поле availableSourceTypes ответа. Это и есть авторитетный список — угадывать по описанию не нужно.',
+                'sourceCoverage=null означает: полнота источника не измерялась. sourceCoverage.complete=false означает ограничение источника; собственный предел прогона отдельно указан в truncated.',
+                'WINDOW: источник прочитан по coveredTo; следующий запуск начни с этой границы, сохранив requestedTo. PAGES: received из declaredTotal (null — число неизвестно); coveredFrom — самая старая прочитанная дата, информационная граница.',
+                'Bitrix24: при truncated=true передай continuation_run_id из continuationRunId запуска или статуса с прежними настройками: добери сохранённый остаток выборки независимо от пропусков и отказов первых 500. Для продолжения нужны новый request_key и true. Если ответ потерян, повтори те же request_key и continuation_run_id: получишь созданный прогон и восстановишь его задания. Для следующей порции используй курсор ответа продолжения. Повтор ошибок запускается отдельно без continuation_run_id. Затем продолжай с audio_source_config.continuationStart из ограничения PAGES, сохранив прежние даты и категорию; createdTo=coveredFrom не гарантирует добор сделок с одинаковой датой. Если список портала изменился между запусками, повтори исходное окно и проверь покрытие.',
+                'headTruncatedCount — число импортированных диалогов с обрезанным началом; null означает, что это не измерялось. ICP_INGEST_SOURCE_RESPONSE_UNREADABLE означает неизвестную форму ответа источника: повтор без исправления источника не поможет.',
+                'Диалог без опознанного человека не импортируется: образец корпуса стирается через контакт, и без контакта стирать было бы нечем.',
+                'Язык распознавания задаётся полем language (ru-RU / uz-UZ / kk-KZ / auto) и применяется ко всему прогону. Не задан — определение по звуку; для узбекских звонков задавать стоит явно.',
+            ])
+            : withInstructions(response, [
+                ICP_CONTINUATION_INSTRUCTIONS,
+                'При потерянном ответе вызови besales_icp_import_start_result с теми же icp_id/request_key. NOT_FOUND_UNKNOWN не доказывает отказ: повтори исходное намерение с тем же ключом.',
+                'mode=text требует request_key, crm_connection_id и gdpr_confirmed=true; импортируются сохранённые текстовые диалоги CRM.',
+                'Обезличивание обязательно. Для каждой новой работы нужны новый request_key UUID и явный gdpr_confirmed=true; повтор ключа возвращает прежний run.',
+            ]),
+    }),
+    defineTool({
+        name: 'besales_icp_import_start_result',
+        sideEffect: 'none',
+        requiredFields: ['icp_id', 'request_key'],
+        schema: z.object({ icp_id: uuidSchema, request_key: uuidSchema }),
+        createRequest: (input) => ({
+            path: '/icp/' + input.icp_id + '/import-runs/start-result',
+            body: { requestKey: input.request_key },
+        }),
+        enhanceResponse: (response) => withInstructions(response, [ICP_CONTINUATION_INSTRUCTIONS]),
+    }),
+    defineTool({
+        name: 'besales_icp_import_history',
+        sideEffect: 'none',
+        requiredFields: ['icp_id'],
+        schema: z.object({
+            icp_id: uuidSchema,
+            cursor: z.string().max(512).optional(),
+            limit: z.number().int().min(1).max(100).optional(),
+        }),
+        createRequest: (input) => ({
+            method: 'GET',
+            path: '/icp/' +
+                input.icp_id +
+                '/import-runs' +
+                buildListQuery({ cursor: input.cursor, limit: input.limit }),
+        }),
+        enhanceResponse: (response) => withInstructions(response, [ICP_CONTINUATION_INSTRUCTIONS]),
     }),
     defineTool({
         name: 'besales_icp_import_status',
@@ -159,6 +270,13 @@ export const agentDesignTools = [
             method: 'GET',
             path: `/icp/audio-import-runs/${input.run_id}`,
         }),
+        enhanceResponse: (response) => withInstructions(response, [
+            ICP_CONTINUATION_INSTRUCTIONS,
+            'sourceCoverage=null означает: полнота источника не измерялась. sourceCoverage.complete=false означает ограничение источника; собственный предел прогона отдельно указан в truncated.',
+            'WINDOW: источник прочитан по coveredTo; следующий запуск начни с этой границы, сохранив requestedTo. PAGES: received из declaredTotal (null — число неизвестно); coveredFrom — самая старая прочитанная дата, информационная граница.',
+            'Bitrix24: при truncated=true передай continuation_run_id из continuationRunId запуска или статуса с прежними настройками: добери сохранённый остаток выборки независимо от пропусков и отказов первых 500. Если ответ продолжения потерян или очередь отказала, повтори прежний continuation_run_id: получишь созданный прогон и восстановишь его задания. Для следующей порции используй курсор ответа продолжения. Повтор ошибок запускается отдельно без continuation_run_id. Затем продолжай с audio_source_config.continuationStart из ограничения PAGES, сохранив прежние даты и категорию; createdTo=coveredFrom не гарантирует добор сделок с одинаковой датой. Если список портала изменился между запусками, повтори исходное окно и проверь покрытие.',
+            'headTruncatedCount — число импортированных диалогов с обрезанным началом; null означает, что это не измерялось. ICP_INGEST_SOURCE_RESPONSE_UNREADABLE означает неизвестную форму ответа источника: повтор без исправления источника не поможет.',
+        ]),
     }),
     defineTool({
         name: 'besales_icp_analysis_get_instructions',
@@ -261,14 +379,29 @@ export const agentDesignTools = [
         requiredFields: ['icp_id'],
         schema: z.object({
             icp_id: uuidSchema,
+            // ⚠️ Без умолчания: раньше отказ по размеру был отказом БЕЗ ВЫХОДА — сузить набор было
+            // нечем. Умолчание же сделало бы усечённый набор неотличимым от «сценариев больше нет».
+            limit: z.number().int().min(1).max(ICP_SCENARIOS_MAX_PAGE_SIZE).optional(),
+            cursor: z.string().min(1).optional(),
         }),
-        createRequest: (input) => ({
-            method: 'GET',
-            path: `/icp/${input.icp_id}/scenarios`,
+        createRequest: (input) => {
+            const query = new URLSearchParams();
+            if (input.limit !== undefined)
+                query.set('limit', String(input.limit));
+            if (input.cursor)
+                query.set('cursor', input.cursor);
+            const suffix = query.size > 0 ? `?${query.toString()}` : '';
+            return { method: 'GET', path: `/icp/${input.icp_id}/scenarios${suffix}` };
+        },
+        enhanceResponse: (response, input) => assertCompleteList(response, {
+            pageRequested: input.limit !== undefined || input.cursor !== undefined,
+            toolName: 'besales_icp_scenarios_list',
+            howToPage: `Позовите снова с limit (до ${ICP_SCENARIOS_MAX_PAGE_SIZE}) и продолжайте по cursor, пока он не станет пустым.`,
         }),
     }),
     defineTool({
         name: 'besales_icp_sample_messages',
+        carriesCustomerData: true,
         sideEffect: 'none',
         requiredFields: ['sample_id'],
         schema: z.object({
@@ -285,6 +418,12 @@ export const agentDesignTools = [
         requiredFields: ['agent_id'],
         schema: z.object({
             agent_id: uuidSchema,
+            output_language: z
+                .string()
+                .regex(/^[a-z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$/u)
+                .max(PROMPT_LANGUAGE_CODE_MAX_LENGTH)
+                .describe('Язык результата: ru/en/es/id/uz и язык внешнего бота вне пятёрки (например kk). Не задан — язык бота, затем пространства. Не связан с style_hints.language.')
+                .optional(),
             icp_profile_id: uuidSchema.optional(),
             business_context: optionalAnyObjectSchema,
             style_hints: z
@@ -292,7 +431,7 @@ export const agentDesignTools = [
                 formality: z.enum(['formal', 'casual', 'friendly']).optional(),
                 verbosity: z.enum(['concise', 'balanced', 'detailed']).optional(),
                 // Язык РАССУЖДЕНИЯ стадий генерации (ru/en) — НЕ язык итогового промпта.
-                // Язык промпта = то, что ты пишешь в final_content (узбекский и т.д.).
+                // Язык результата задаёт output_language, иначе сервер сохраняет язык бота.
                 language: z.enum(['ru', 'en']).default('ru'),
                 message_direction: z.enum(['INBOUND', 'OUTBOUND']).optional(),
             })
@@ -301,6 +440,7 @@ export const agentDesignTools = [
         createRequest: (input) => ({
             path: `/agents/${input.agent_id}/prompt/generate/instructions`,
             body: compactObject({
+                outputLanguage: input.output_language,
                 sourceType: input.icp_profile_id ? 'icp_full' : 'business_context_only',
                 icpProfileId: input.icp_profile_id,
                 businessContext: input.business_context,
@@ -316,9 +456,10 @@ export const agentDesignTools = [
         }),
         enhanceResponse: (response) => withInstructions(response, [
             'Перед генерацией сверься с besales://docs/prompt-anatomy (лимит длины + что система добавляет сама) и besales://docs/prompt-principles (человечность/анти-AI-tell + sales-плейбук + раздел C: майнить реальные диалоги операторов по этапам); форму и тактику бери из этих ресурсов, не из догадок.',
+            'Используй возвращённые input и authoringContext во всех стадиях; покажи directionWarnings пользователю. Необязательное поле icpPortraitOmission означает, что сервер намеренно не включил портрет аудитории: сообщи об этом пользователю и используй доступные материалы. Сервер уже вывел направление из назначения. Явный message_direction меняет нейтральный сценарий; реактивация требует OUTBOUND.',
             'Выполни 4 stages prompt generation локально: structure_builder, industry_validator, prompt_tester, finalizer.',
             'Каждая stage должна вернуть JSON по своей schema. Финальный compiled prompt положи в final_content.',
-            'Язык итогового промпта = содержимое final_content: пиши его на языке бота (узбекский, казахский и т.д.). style_hints.language (ru/en) задаёт лишь язык рассуждения стадий, не язык промпта.',
+            'Язык результата задан отдельно в output_language, иначе сервер сохраняет язык бота (узбекский, казахский и другие языки вне интерфейсной пятёрки), затем пространства. Соблюдай возвращённый languageContext во всех черновиках и final_content. style_hints.language (ru/en) задаёт только язык служебного рассуждения. Перед применением покажи заданный язык и проверь текст.',
             'После stages вызови besales_prompt_generate_submit с stages, final_content и metadata.',
         ]),
     }),
@@ -365,17 +506,25 @@ export const agentDesignTools = [
         schema: z.object({
             agent_id: uuidSchema,
             version_id: uuidSchema,
+            source_language: z
+                .string()
+                .regex(/^[a-z]{2,3}(?:-[a-zA-Z0-9]{2,8})*$/u)
+                .max(PROMPT_LANGUAGE_CODE_MAX_LENGTH)
+                .describe('Язык проверяемого текста. Если не передан, берётся язык бота, затем пространства. Не переводит весь черновик.')
+                .optional(),
             modes: z.array(analysisModeSchema).default(['grammar', 'structure', 'contradictions']),
         }),
         createRequest: (input) => ({
             path: `/agents/${input.agent_id}/prompt/analyze/instructions`,
             body: {
                 versionId: input.version_id,
+                ...(input.source_language === undefined ? {} : { sourceLanguage: input.source_language }),
                 modes: input.modes,
             },
         }),
         enhanceResponse: (response) => withInstructions(response, [
             'Выполни static analysis stages локально: grammar, industry, structure, aggregation.',
+            'Сохрани язык проверяемого текста: returned languageContext задаёт язык замечаний и предлагаемых правок. Не переводи весь черновик; original, targetText и anchorText сохраняй дословно.',
             'Собери итоговый список issues без дублей и с severity.',
             'После анализа вызови besales_prompt_analyze_submit с aggregated_issues.',
         ]),
@@ -423,7 +572,7 @@ export const agentDesignTools = [
             }),
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Промпт активирован. Перед запуском проверь 3 вещи: 1) greeting — besales_behavior_update.greeting, замени дефолтный «Привет!/Hello» на язык аудитории текстом, БЕЗ кнопок (greeting_buttons — лишь по явному запросу); для INBOUND именно оно открывает диалог; 2) knowledge привязан к каналу; 3) прогон besales_sandbox_run_start.',
+            'Промпт активирован. Перед запуском проверь 3 вещи: 1) greeting — besales_behavior_update.greeting, замени дефолтный «Привет!/Hello» на язык аудитории полем text, БЕЗ кнопок (buttons — лишь по явному запросу); секции у нового канала нет, поэтому первая запись обязана нести text, buttons, keyboard_type и popup_delay_seconds целиком; для INBOUND именно оно открывает диалог; 2) knowledge привязан к каналу; 3) прогон besales_sandbox_run_start.',
         ]),
     }),
     defineTool({
@@ -432,6 +581,9 @@ export const agentDesignTools = [
         requiredFields: ['agent_id'],
         schema: z.object({
             agent_id: uuidSchema,
+            // Прогон по ещё не активированному тексту промпта: проверка кандидата ДО того, как он
+            // станет промптом агента. Без поля кандидата проверить нечем — приходилось бы активировать
+            // черновик на живом агенте.
             candidate_prompt: z.string().min(10).max(100_000).optional(),
             scenario_ids: z.array(uuidSchema).optional(),
             options: z
@@ -473,11 +625,8 @@ export const agentDesignTools = [
             }),
         }),
         verifyWithToolName: 'besales_sandbox_run_get',
-        enhanceResponse: (response, input) => withInstructions(response, [
+        enhanceResponse: (response) => withInstructions(response, [
             'Сохрани id прогона как run_id. Проверяй только этот прогон через besales_sandbox_run_get.',
-            input.candidate_prompt
-                ? 'Проверяется неактивированный candidate_prompt. Он не меняет работающего агента; активировать результат можно только отдельным prompt commit/finalize после проверки актуальности hash.'
-                : 'Проверяется активный промпт агента. testedConfiguration в detail фиксирует его hash/version на момент постановки.',
             'Первую проверку делай через 10–30 секунд; повторяй, пока status не станет COMPLETED, FAILED или CANCELLED.',
         ]),
     }),
@@ -579,6 +728,9 @@ export const agentDesignTools = [
             path: `/agents/${input.agent_id}/sandbox/runs/${input.run_id}/findings/${input.operation_id}/submit`,
             body: {
                 findings: input.findings.map((finding) => compactObject({
+                    // ⛔ Оба написания принимаются на входе, наружу уходит канон сервера. Поля
+                    // перечислены ЯВНО: сборка тела — вторая точка потери, где незнакомое поле исчезает
+                    // молча, уже пережив схему.
                     scenarioId: finding.scenarioId ?? finding.scenario_id,
                     category: finding.category,
                     severity: finding.severity,
@@ -672,8 +824,8 @@ export const agentDesignTools = [
             .object({
             agent_id: uuidSchema,
             operation_id: uuidSchema,
-            knowledge_space_id: uuidSchema.optional(),
-            knowledgeSpaceId: uuidSchema.optional(),
+            knowledge_space_id: knowledgeSpaceIdSchema.optional(),
+            knowledgeSpaceId: knowledgeSpaceIdSchema.optional(),
             qa_pairs: z
                 .array(z.object({
                 question: z.string(),
@@ -728,7 +880,7 @@ export const agentDesignTools = [
         }),
         enhanceResponse: (response) => withInstructions(response, [
             'Выполни stage scenario_builder локально и верни структурированный JSON.',
-            'Уточни у пользователя целевой режим sandbox: изолированный агент (single_agent) или полный workflow с роутером (workflow). Для workflow добавь сценарии, провоцирующие смену агента — сдвиг темы/intent в ходе диалога.',
+            'Без вопроса запускай обычный прогон: mode=single_agent и client_mode=scripted (умолчания схемы) — это дешёвый, воспроизводимый прогон для регрессии и проверки кандидата промпта до публикации (candidate_prompt). Перед запуском спроси пользователя одним коротким вопросом с ценой в одну фразу только если нужен client_mode=simulated (LLM играет клиента — дороже и каждый раз по-разному), оба режима клиента (= два прогона) либо mode=workflow (все агенты канала через роутер — шире и дороже). Для workflow добавь сценарии, провоцирующие смену агента — сдвиг темы/intent в ходе диалога.',
             'Каждый scenario — sandbox-готовый мультитёрн диалог: МИНИМУМ 4 turns (submit с меньшим количеством вернёт 400), начинать ОБЯЗАТЕЛЬНО с role="client".',
             'Реплики client пиши КОРОТКО, как в мессенджере (обычно 3-15 слов, можно фрагментами/одним словом) — реальные клиенты не пишут эссе; стиль бери из languageStyle сегмента/persona.',
             'segment_ids должны ссылаться только на icpContext.segments[].id; не выдумывай UUID.',
@@ -756,11 +908,12 @@ export const agentDesignTools = [
                     name: scenario.name,
                     description: scenario.description,
                     segmentIds: scenario.segment_ids,
-                    // ⚠️ `expect` перечислен ЯВНО: реплики пересобираются по списку полей, и забытый
-                    // ключ не ломает ни сборку, ни схему — ожидания просто не доехали бы до backend.
                     situations: scenario.situations.map((situation) => ({
                         role: situation.role,
                         text: situation.text,
+                        // ⚠️ `expect` перечислен ЯВНО: реплики пересобираются по списку полей, и забытая
+                        // рубрика исчезла бы молча — сценарий доехал бы до сервера без проверок, а доля
+                        // прохождения считалась бы по пустому набору.
                         expect: situation.expect,
                     })),
                 })),
@@ -786,7 +939,10 @@ export const agentDesignTools = [
         requiredFields: ['agent_id', 'graph'],
         schema: z.object({
             agent_id: uuidSchema,
-            preamble: z.string().optional(),
+            // `null` принимается наравне с отсутствием: чтение отдаёт `preamble: null`, и круг
+            // «прочитал → поправил граф → отправил тем же телом» обязан замыкаться. Соседние
+            // необязательные поля графа устроены так же.
+            preamble: z.string().nullable().optional(),
             graph: z.object({
                 stages: z.array(z.object({ id: z.string(), name: z.string() })),
                 nodes: z.array(z.object({