@besales/mcp 0.47.1 → 1.0.0-beta.2

package/dist/tools/definitions/crm-platform.js

@@ -1,267 +1,10 @@
+import { withEditVersionInstructions, editVersionInstruction } from './edit-version.js';
+import { setupInitOperationIdSchema } from './setup-init-operation.schema.js';
 import { z } from 'zod';
 import { assertCompleteList } from '../incomplete-list.js';
-import { MAX_FILE_UPLOAD_BYTES, VARIABLES_MAX_PAGE_SIZE, apiKeyPlatformTypeSchema, buildFileListQuery, buildVariableListQuery, buildVariableScopeQuery, compactObject, crmFieldMappingItemSchema, defineTool, mcpFileSourceSchema, oauthPlatformTypeSchema, optionalAnyObjectSchema, provisionableCrmTypeSchema, storedFileTypeSchema, uuidSchema, withInstructions, } from './shared.js';
+import { CRM_PIPELINES_MAX_PAGE_SIZE, MAX_FILE_UPLOAD_BYTES, apiKeyPlatformTypeSchema, buildFileListQuery, compactObject, crmFieldMappingItemSchema, defineTool, mcpFileSourceSchema, oauthPlatformTypeSchema, optionalAnyObjectSchema, provisionableCrmTypeSchema, storedFileTypeSchema, uuidSchema, withInstructions, } from './shared.js';
+export const CRM_OPERATOR_CHANGE_FIELDS = ['is_operator', 'is_sdr', 'workspace_member_id'];
 export const crmPlatformTools = [
-    // ============================================================
-    // v1.5 Increment 4a — Unified Variables API (5 tools, v2-shaped scope discriminator)
-    // ============================================================
-    // Backend wraps two v1 tables (WorkspaceVariable + CustomVariable) под единый MCP shape.
-    // При v2 cutover (spec 23) обе таблицы → один `variables` с тем же `scope` discriminator —
-    // MCP shape работает без изменений.
-    defineTool({
-        name: 'besales_variable_list',
-        sideEffect: 'none',
-        closedWorld: true,
-        requiredFields: ['scope'],
-        defaultWorkspaceId: true,
-        // По этому перечню строят условия правил. Отсутствующая в усечённом списке переменная
-        // неотличима от «значение не проставлено», и правило получается недостижимым.
-        resultPolicy: { neverTruncate: true },
-        schema: z
-            .object({
-            workspace_id: uuidSchema.optional(),
-            scope: z.enum(['WORKSPACE', 'CHANNEL']),
-            platform_id: uuidSchema.optional(),
-            filter: z.enum(['all', 'variables', 'constants']).optional(),
-            // ⚠️ Без дефолта. Сервер СВОЙ дефолт имеет (50), и до появления этих двух ручек
-            // перечень молча обрывался на пятидесятой строке, а способа дочитать не было вовсе.
-            limit: z.number().int().min(1).max(VARIABLES_MAX_PAGE_SIZE).optional(),
-            cursor: z.string().min(1).optional(),
-        })
-            .strict()
-            .superRefine((input, ctx) => {
-            if (input.scope === 'CHANNEL' && !input.platform_id) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: 'platform_id is required when scope=CHANNEL',
-                    path: ['platform_id'],
-                });
-            }
-            if (input.scope === 'WORKSPACE' && input.platform_id) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: 'platform_id is forbidden when scope=WORKSPACE',
-                    path: ['platform_id'],
-                });
-            }
-        }),
-        createRequest: (input) => ({
-            method: 'GET',
-            path: `/workspaces/${input.workspace_id}/variables${buildVariableListQuery(input.scope, input.platform_id, input.filter, input.limit, input.cursor)}`,
-        }),
-        enhanceResponse: (response, input) => withInstructions(assertCompleteList(response, {
-            // Страницу попросили явно — отказ неуместен: постраничный обход это и есть.
-            pageRequested: input.limit !== undefined || input.cursor !== undefined,
-            toolName: 'besales_variable_list',
-            howToPage: `Позовите снова с limit (до ${VARIABLES_MAX_PAGE_SIZE}) и продолжайте по nextCursor, пока он не станет пустым.`,
-        }), [
-            'WORKSPACE scope возвращает глобальные переменные workspace; CHANNEL — переменные указанной платформы.',
-            'CHANNEL требует platform_id; filter=variables исключает константы, filter=constants оставляет только их.',
-            'nextCursor в ответе означает, что показана НЕ вся выборка: дочитайте страницами.',
-        ]),
-    }),
-    defineTool({
-        name: 'besales_variable_create',
-        sideEffect: 'write',
-        closedWorld: true,
-        requiredFields: ['scope', 'name', 'type'],
-        defaultWorkspaceId: true,
-        schema: z
-            .object({
-            workspace_id: uuidSchema.optional(),
-            scope: z.enum(['WORKSPACE', 'CHANNEL']),
-            name: z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, {
-                message: 'name must be ASCII letters/digits/underscores; start with letter or _',
-            }),
-            description: z.string().optional(),
-            type: z.enum(['TEXT', 'NUMBER', 'FLOAT', 'BOOLEAN']),
-            // WORKSPACE-only
-            value: z.string().optional(),
-            // CHANNEL-only
-            platform_id: uuidSchema.optional(),
-            is_constant: z.boolean().optional(),
-            constant_value: z.string().optional(),
-        })
-            .strict()
-            .superRefine((input, ctx) => {
-            if (input.scope === 'WORKSPACE') {
-                if (input.platform_id) {
-                    ctx.addIssue({
-                        code: z.ZodIssueCode.custom,
-                        message: 'platform_id is forbidden when scope=WORKSPACE',
-                        path: ['platform_id'],
-                    });
-                }
-                if (input.is_constant !== undefined || input.constant_value !== undefined) {
-                    ctx.addIssue({
-                        code: z.ZodIssueCode.custom,
-                        message: 'is_constant and constant_value are forbidden when scope=WORKSPACE',
-                        path: ['is_constant'],
-                    });
-                }
-            }
-            else {
-                // CHANNEL
-                if (!input.platform_id) {
-                    ctx.addIssue({
-                        code: z.ZodIssueCode.custom,
-                        message: 'platform_id is required when scope=CHANNEL',
-                        path: ['platform_id'],
-                    });
-                }
-                if (input.value !== undefined) {
-                    ctx.addIssue({
-                        code: z.ZodIssueCode.custom,
-                        message: 'value is forbidden when scope=CHANNEL — use constant_value if isConstant=true',
-                        path: ['value'],
-                    });
-                }
-                if (input.is_constant === true && !input.constant_value) {
-                    ctx.addIssue({
-                        code: z.ZodIssueCode.custom,
-                        message: 'constant_value is required when scope=CHANNEL and is_constant=true',
-                        path: ['constant_value'],
-                    });
-                }
-            }
-        }),
-        createRequest: (input) => ({
-            method: 'POST',
-            path: `/workspaces/${input.workspace_id}/variables`,
-            body: compactObject({
-                scope: input.scope,
-                name: input.name,
-                description: input.description,
-                type: input.type,
-                value: input.value,
-                platformId: input.platform_id,
-                isConstant: input.is_constant,
-                constantValue: input.constant_value,
-            }),
-        }),
-        enhanceResponse: (response) => withInstructions(response, [
-            'name, scope, is_constant — immutable post-create (используй delete + create для смены).',
-            'WORKSPACE variables референсятся в шаблонах как {{{name}}} (triple braces), CHANNEL constants — {{name}} (double).',
-        ]),
-    }),
-    defineTool({
-        name: 'besales_variable_get',
-        sideEffect: 'none',
-        closedWorld: true,
-        requiredFields: ['variable_id', 'scope'],
-        defaultWorkspaceId: true,
-        schema: z
-            .object({
-            workspace_id: uuidSchema.optional(),
-            variable_id: uuidSchema,
-            scope: z.enum(['WORKSPACE', 'CHANNEL']),
-            platform_id: uuidSchema.optional(),
-        })
-            .strict()
-            .superRefine((input, ctx) => {
-            if (input.scope === 'CHANNEL' && !input.platform_id) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: 'platform_id is required when scope=CHANNEL',
-                    path: ['platform_id'],
-                });
-            }
-        }),
-        createRequest: (input) => ({
-            method: 'GET',
-            path: `/workspaces/${input.workspace_id}/variables/${input.variable_id}${buildVariableScopeQuery(input.scope, input.platform_id)}`,
-        }),
-    }),
-    defineTool({
-        name: 'besales_variable_update',
-        sideEffect: 'write',
-        closedWorld: true,
-        requiredFields: ['variable_id', 'scope'],
-        defaultWorkspaceId: true,
-        schema: z
-            .object({
-            workspace_id: uuidSchema.optional(),
-            variable_id: uuidSchema,
-            scope: z.enum(['WORKSPACE', 'CHANNEL']),
-            platform_id: uuidSchema.optional(),
-            description: z.string().optional(),
-            type: z.enum(['TEXT', 'NUMBER', 'FLOAT', 'BOOLEAN']).optional(),
-            // WORKSPACE-only (nullable для clear)
-            value: z.string().nullable().optional(),
-            // CHANNEL-only (nullable для clear)
-            constant_value: z.string().nullable().optional(),
-        })
-            .strict()
-            .superRefine((input, ctx) => {
-            if (input.scope === 'CHANNEL' && !input.platform_id) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: 'platform_id is required when scope=CHANNEL',
-                    path: ['platform_id'],
-                });
-            }
-            if (input.scope === 'WORKSPACE' && input.constant_value !== undefined) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: 'constant_value is forbidden when scope=WORKSPACE',
-                    path: ['constant_value'],
-                });
-            }
-            if (input.scope === 'CHANNEL' && input.value !== undefined) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: 'value is forbidden when scope=CHANNEL',
-                    path: ['value'],
-                });
-            }
-        }),
-        createRequest: (input) => ({
-            method: 'PATCH',
-            path: `/workspaces/${input.workspace_id}/variables/${input.variable_id}`,
-            body: compactObject({
-                scope: input.scope,
-                platformId: input.platform_id,
-                description: input.description,
-                type: input.type,
-                value: input.value,
-                constantValue: input.constant_value,
-            }),
-        }),
-    }),
-    defineTool({
-        name: 'besales_variable_delete',
-        sideEffect: 'write',
-        closedWorld: true,
-        requiredFields: ['variable_id', 'scope', 'explicit_confirmation'],
-        defaultWorkspaceId: true,
-        schema: z
-            .object({
-            workspace_id: uuidSchema.optional(),
-            variable_id: uuidSchema,
-            scope: z.enum(['WORKSPACE', 'CHANNEL']),
-            platform_id: uuidSchema.optional(),
-            explicit_confirmation: z.literal(true),
-        })
-            .strict()
-            .superRefine((input, ctx) => {
-            if (input.scope === 'CHANNEL' && !input.platform_id) {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: 'platform_id is required when scope=CHANNEL',
-                    path: ['platform_id'],
-                });
-            }
-        }),
-        createRequest: (input) => ({
-            method: 'DELETE',
-            path: `/workspaces/${input.workspace_id}/variables/${input.variable_id}`,
-            body: compactObject({
-                scope: input.scope,
-                platformId: input.platform_id,
-                explicitConfirmation: input.explicit_confirmation,
-            }),
-        }),
-    }),
     // ============================================================
     // v1.5 Increment 4b — CRM Pipelines (11 tools)
     // ============================================================
@@ -286,14 +29,21 @@ export const crmPlatformTools = [
             workspace_id: uuidSchema.optional(),
             crm_id: uuidSchema,
             include_deleted: z.boolean().optional(),
+            // ⚠️ Без умолчания: отказ по размеру был отказом БЕЗ ВЫХОДА — сузить перечень было нечем.
+            limit: z.number().int().min(1).max(CRM_PIPELINES_MAX_PAGE_SIZE).optional(),
+            cursor: z.string().min(1).optional(),
         })
             .strict(),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/crm/${input.crm_id}/pipelines${input.include_deleted !== undefined ? `?includeDeleted=${input.include_deleted}` : ''}`,
+            path: `/crm-connections/${input.crm_id}/pipelines?sync=true${input.include_deleted !== undefined ? `&includeDeleted=${input.include_deleted}` : ''}${input.limit !== undefined ? `&limit=${input.limit}` : ''}${input.cursor ? `&cursor=${encodeURIComponent(input.cursor)}` : ''}`,
         }),
-        enhanceResponse: (response) => withInstructions(response, [
-            'Триггерит sync с external CRM (AmoCRM/Bitrix24) при каждом вызове — best-effort, не блокирует list при failure.',
+        enhanceResponse: (response, input) => withInstructions(assertCompleteList(response, {
+            pageRequested: input.limit !== undefined || input.cursor !== undefined,
+            toolName: 'besales_crm_pipeline_list',
+            howToPage: `Позовите снова с limit (до ${CRM_PIPELINES_MAX_PAGE_SIZE}) и продолжайте по cursor, пока он не станет пустым.`,
+        }), [
+            'Перед list выполняется best-effort sync; ошибка провайдера не блокирует локальную выдачу.',
         ]),
     }),
     defineTool({
@@ -310,7 +60,7 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/crm/${input.crm_id}/pipelines/${input.pipeline_id}`,
+            path: `/crm-connections/${input.crm_id}/pipelines/${input.pipeline_id}`,
         }),
     }),
     defineTool({
@@ -333,7 +83,7 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'POST',
-            path: `/workspaces/${input.workspace_id}/crm/${input.crm_id}/pipelines`,
+            path: `/crm-connections/${input.crm_id}/pipelines`,
             body: compactObject({
                 name: input.name,
                 sort: input.sort,
@@ -353,11 +103,7 @@ export const crmPlatformTools = [
         name: 'besales_crm_pipeline_update',
         sideEffect: 'write',
         defaultWorkspaceId: true,
-        requiredFields: [
-            'crm_id',
-            'pipeline_id',
-            'acknowledge_external_side_effect',
-        ],
+        requiredFields: ['crm_id', 'pipeline_id', 'acknowledge_external_side_effect'],
         schema: z
             .object({
             workspace_id: uuidSchema.optional(),
@@ -373,7 +119,7 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'PATCH',
-            path: `/workspaces/${input.workspace_id}/crm/${input.crm_id}/pipelines/${input.pipeline_id}`,
+            path: `/crm-connections/${input.crm_id}/pipelines/${input.pipeline_id}`,
             body: compactObject({
                 name: input.name,
                 sort: input.sort,
@@ -384,7 +130,7 @@ export const crmPlatformTools = [
             }),
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Sync changes в external CRM (если поддерживается updatePipeline). Settings типа aiResponseMoveToStatus живут в PipelineSettings — обновляй через besales_pipeline_settings_update.',
+            'Sync changes в external CRM (если поддерживается updatePipeline). Settings типа aiResponseMoveToStatus живут в настройках воронок канала — обновляй через besales_pipeline_settings_update.',
         ]),
     }),
     defineTool({
@@ -408,7 +154,7 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'DELETE',
-            path: `/workspaces/${input.workspace_id}/crm/${input.crm_id}/pipelines/${input.pipeline_id}`,
+            path: `/crm-connections/${input.crm_id}/pipelines/${input.pipeline_id}`,
             body: {
                 explicitConfirmation: input.explicit_confirmation,
                 acknowledgeExternalSideEffect: input.acknowledge_external_side_effect,
@@ -432,24 +178,34 @@ export const crmPlatformTools = [
             workspace_id: uuidSchema.optional(),
             crm_id: uuidSchema,
             pipeline_id: z.number().int(),
+            // ⚠️ Без умолчания: недостающая стадия даёт недостижимое правило маршрутизации.
+            limit: z.number().int().min(1).max(CRM_PIPELINES_MAX_PAGE_SIZE).optional(),
+            cursor: z.string().min(1).optional(),
         })
             .strict(),
-        createRequest: (input) => ({
-            method: 'GET',
-            path: `/workspaces/${input.workspace_id}/crm/${input.crm_id}/pipelines/${input.pipeline_id}/statuses`,
+        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: `/crm-connections/${input.crm_id}/pipelines/${input.pipeline_id}/statuses${suffix}`,
+            };
+        },
+        enhanceResponse: (response, input) => assertCompleteList(response, {
+            pageRequested: input.limit !== undefined || input.cursor !== undefined,
+            toolName: 'besales_crm_pipeline_status_list',
+            howToPage: `Позовите снова с limit (до ${CRM_PIPELINES_MAX_PAGE_SIZE}) и продолжайте по cursor, пока он не станет пустым.`,
         }),
     }),
     defineTool({
         name: 'besales_crm_pipeline_status_create',
         sideEffect: 'write',
         defaultWorkspaceId: true,
-        requiredFields: [
-            'crm_id',
-            'pipeline_id',
-            'name',
-            'sort',
-            'acknowledge_external_side_effect',
-        ],
+        requiredFields: ['crm_id', 'pipeline_id', 'name', 'sort', 'acknowledge_external_side_effect'],
         schema: z
             .object({
             workspace_id: uuidSchema.optional(),
@@ -460,8 +216,16 @@ export const crmPlatformTools = [
             color: z.string().optional(),
             status_types: z.array(z.string()).optional(),
             is_editable: z.boolean().optional(),
+            is_system_managed: z
+                .boolean()
+                .optional()
+                .describe('Колонка ведётся платформой. Не помечена — автоматика в неё не заходит: бот молчит, оператор из неё не зовётся'),
             is_bot_active: z.boolean().optional(),
             is_operator_available: z.boolean().optional(),
+            is_terminal: z
+                .boolean()
+                .optional()
+                .describe('Путь закончен: дожимать нечего, проактивных касаний из этой колонки нет'),
             on_message_received_move_to_status: z.number().int().nullable().optional(),
             status_id: z.number().int().optional(),
             acknowledge_external_side_effect: z.literal(true),
@@ -469,15 +233,17 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'POST',
-            path: `/workspaces/${input.workspace_id}/crm/${input.crm_id}/pipelines/${input.pipeline_id}/statuses`,
+            path: `/crm-connections/${input.crm_id}/pipelines/${input.pipeline_id}/statuses`,
             body: compactObject({
                 name: input.name,
                 sort: input.sort,
                 color: input.color,
                 statusTypes: input.status_types,
                 isEditable: input.is_editable,
+                isSystemManaged: input.is_system_managed,
                 isBotActive: input.is_bot_active,
                 isOperatorAvailable: input.is_operator_available,
+                isTerminal: input.is_terminal,
                 onMessageReceivedMoveToStatus: input.on_message_received_move_to_status,
                 statusId: input.status_id,
                 acknowledgeExternalSideEffect: input.acknowledge_external_side_effect,
@@ -491,12 +257,7 @@ export const crmPlatformTools = [
         name: 'besales_crm_pipeline_status_update',
         sideEffect: 'write',
         defaultWorkspaceId: true,
-        requiredFields: [
-            'crm_id',
-            'pipeline_id',
-            'status_id',
-            'acknowledge_external_side_effect',
-        ],
+        requiredFields: ['crm_id', 'pipeline_id', 'status_id', 'acknowledge_external_side_effect'],
         schema: z
             .object({
             workspace_id: uuidSchema.optional(),
@@ -510,17 +271,21 @@ export const crmPlatformTools = [
             is_system_managed: z
                 .boolean()
                 .optional()
-                .describe('Главный переключатель управления статусом системой'),
+                .describe('Колонка ведётся платформой. Не помечена — автоматика в неё не заходит: бот молчит, оператор из неё не зовётся'),
             is_editable: z.boolean().optional(),
             is_bot_active: z.boolean().optional(),
             is_operator_available: z.boolean().optional(),
+            is_terminal: z
+                .boolean()
+                .optional()
+                .describe('Путь закончен: дожимать нечего, проактивных касаний из этой колонки нет'),
             on_message_received_move_to_status: z.number().int().nullable().optional(),
             acknowledge_external_side_effect: z.literal(true),
         })
             .strict(),
         createRequest: (input) => ({
             method: 'PATCH',
-            path: `/workspaces/${input.workspace_id}/crm/${input.crm_id}/pipelines/${input.pipeline_id}/statuses/${input.status_id}`,
+            path: `/crm-connections/${input.crm_id}/pipelines/${input.pipeline_id}/statuses/${input.status_id}`,
             body: compactObject({
                 name: input.name,
                 sort: input.sort,
@@ -530,6 +295,7 @@ export const crmPlatformTools = [
                 isEditable: input.is_editable,
                 isBotActive: input.is_bot_active,
                 isOperatorAvailable: input.is_operator_available,
+                isTerminal: input.is_terminal,
                 onMessageReceivedMoveToStatus: input.on_message_received_move_to_status,
                 acknowledgeExternalSideEffect: input.acknowledge_external_side_effect,
             }),
@@ -561,7 +327,7 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'DELETE',
-            path: `/workspaces/${input.workspace_id}/crm/${input.crm_id}/pipelines/${input.pipeline_id}/statuses/${input.status_id}`,
+            path: `/crm-connections/${input.crm_id}/pipelines/${input.pipeline_id}/statuses/${input.status_id}`,
             body: {
                 explicitConfirmation: input.explicit_confirmation,
                 acknowledgeExternalSideEffect: input.acknowledge_external_side_effect,
@@ -575,6 +341,11 @@ export const crmPlatformTools = [
         requiredFields: ['platform_id', 'pipeline_id', 'pipeline_crm_id'],
         schema: z
             .object({
+            expected_version: z
+                .string()
+                .min(1)
+                .regex(/^[A-Za-z0-9_.-]+$/u)
+                .optional(),
             workspace_id: uuidSchema.optional(),
             platform_id: uuidSchema,
             pipeline_id: z.number().int(),
@@ -584,14 +355,16 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'POST',
-            path: `/workspaces/${input.workspace_id}/platforms/${input.platform_id}/active-pipelines`,
+            path: `/channels/${input.platform_id}/active-pipelines`,
             body: compactObject({
+                expectedVersion: input.expected_version,
                 pipelineId: input.pipeline_id,
                 pipelineCrmId: input.pipeline_crm_id,
                 sort: input.sort,
             }),
         }),
         enhanceResponse: (response) => withInstructions(response, [
+            editVersionInstruction(),
             'Local-only M:N junction. Reversible audit — unlink восстановится через besales_audit_revert.',
         ]),
     }),
@@ -602,6 +375,11 @@ export const crmPlatformTools = [
         requiredFields: ['platform_id', 'platform_pipeline_id', 'explicit_confirmation'],
         schema: z
             .object({
+            expected_version: z
+                .string()
+                .min(1)
+                .regex(/^[A-Za-z0-9_.-]+$/u)
+                .optional(),
             workspace_id: uuidSchema.optional(),
             platform_id: uuidSchema,
             platform_pipeline_id: uuidSchema,
@@ -610,9 +388,11 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'DELETE',
-            path: `/workspaces/${input.workspace_id}/platforms/${input.platform_id}/active-pipelines/${input.platform_pipeline_id}`,
+            ...compactObject({ ifMatch: input.expected_version }),
+            path: `/channels/${input.platform_id}/active-pipelines/${input.platform_pipeline_id}`,
             body: { explicitConfirmation: input.explicit_confirmation },
         }),
+        enhanceResponse: withEditVersionInstructions,
     }),
     // ============================================================
     // v1.5 Increment 4d — cross-platform clone (3 tools)
@@ -662,10 +442,10 @@ export const crmPlatformTools = [
         }),
         createRequest: (input) => ({
             method: 'POST',
-            path: `/workspaces/${input.workspace_id}/platforms/clone/preview`,
+            path: `/workspaces/${input.workspace_id}/channels/clone/preview`,
             body: compactObject({
-                sourcePlatformId: input.source_platform_id,
-                targetPlatformId: input.target_platform_id,
+                sourceChannelId: input.source_platform_id,
+                targetChannelId: input.target_platform_id,
                 include: compactObject({
                     agents: input.include.agents,
                     agentTools: input.include.agent_tools,
@@ -732,11 +512,11 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'POST',
-            path: `/workspaces/${input.workspace_id}/platforms/clone/execute`,
+            path: `/workspaces/${input.workspace_id}/channels/clone/execute`,
             body: compactObject({
                 previewToken: input.preview_token,
-                sourcePlatformId: input.source_platform_id,
-                targetPlatformId: input.target_platform_id,
+                sourceChannelId: input.source_platform_id,
+                targetChannelId: input.target_platform_id,
                 explicitConfirmation: input.explicit_confirmation,
                 acknowledgeDestructiveOverwrite: input.acknowledge_destructive_overwrite,
                 idempotencyKey: input.idempotency_key,
@@ -744,7 +524,7 @@ export const crmPlatformTools = [
             }),
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Result reversible через besales_audit_revert (kind=revertClone) — пометит CloneRun.status=REVERTED.',
+            'Result reversible через besales_audit_revert (kind=revertClone) — физически откатывает изменения клона и помечает запуск REVERTED.',
             'idempotency_key reuse → returns cached result БЕЗ повторного выполнения.',
             'preview_token expired (15 min) → 410 Gone, нужно повторить preview.',
             'Если preview вернул `requires_destructive_ack: true` — обязательно передайте `acknowledge_destructive_overwrite: true` (overwrite mode фактически удалит target агентов / follow-ups / behavior).',
@@ -763,7 +543,7 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/platforms/clone/${input.clone_id}`,
+            path: `/workspaces/${input.workspace_id}/channels/clone/${input.clone_id}`,
         }),
     }),
     // ============================================================
@@ -786,6 +566,10 @@ export const crmPlatformTools = [
             source: mcpFileSourceSchema.optional(),
             mime_type: z.string().max(255).optional(),
             size_bytes: z.number().int().positive().max(MAX_FILE_UPLOAD_BYTES).optional(),
+            // Носитель, РАДИ которого грузится файл: он станет владельцем и только он вправе его
+            // убрать. Порядок: создать карточку → запросить загрузку ДЛЯ НЕЁ → человек кладёт файл.
+            owner_kind: z.literal('KNOWLEDGE_SOURCE').optional(),
+            owner_id: uuidSchema.optional(),
         })
             .strict(),
         createRequest: (input) => ({
@@ -798,11 +582,14 @@ export const crmPlatformTools = [
                 source: input.source,
                 mime_type: input.mime_type,
                 size_bytes: input.size_bytes,
+                owner_kind: input.owner_kind,
+                owner_id: input.owner_id,
             }),
         }),
         enhanceResponse: (response) => withInstructions(response, [
             'Отдайте пользователю `upload_page_url` — он откроет его в браузере (уже залогинен) и загрузит файл. Секрет/файл НЕ проходит через LLM.',
-            'Затем поллите `besales_file_upload_status({ upload_ref })`: status=READY → `stored_file_id` (используйте в knowledge_document_upload / behavior greeting).',
+            'Затем поллите `besales_file_upload_status({ upload_ref })`: status=READY → `stored_file_id` (используйте в besales_knowledge_document_upload с source_kind=STORED_FILE / behavior greeting).',
+            'Файл ДЛЯ карточки знаний: сначала создайте карточку, затем запросите загрузку с owner_kind=KNOWLEDGE_SOURCE и owner_id=<id карточки>. Такой файл принадлежит карточке: он не показывается в медиатеке, его нельзя поставить приветствием или вложением шага, и он удаляется вместе с карточкой.',
             'TTL сессии 15 минут. Имя файла (`name`) должно быть уникальным в workspace.',
         ]),
     }),
@@ -819,7 +606,7 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/file-upload-sessions/${input.upload_ref}`,
+            path: `/workspaces/${input.workspace_id}/file-upload-sessions/${encodeURIComponent(input.upload_ref)}`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
             'status: AWAITING_USER (ждём загрузку) → VALIDATING → READY (`stored_file_id` готов) | VALIDATION_FAILED (`error_message`, пользователь может повторить) | EXPIRED (создайте новую сессию).',
@@ -862,6 +649,7 @@ export const crmPlatformTools = [
         schema: z
             .object({
             workspace_id: uuidSchema.optional(),
+            operation_id: setupInitOperationIdSchema,
             platform_type: apiKeyPlatformTypeSchema,
             name: z.string().min(1).max(255),
             // Публичные (НЕ секретные) поля канала. Секреты вводятся на /setup/:ref.
@@ -876,6 +664,7 @@ export const crmPlatformTools = [
             method: 'POST',
             path: `/workspaces/${input.workspace_id}/platform-setup-sessions`,
             body: compactObject({
+                operationId: input.operation_id,
                 platform_type: input.platform_type,
                 name: input.name,
                 fields: input.fields,
@@ -901,7 +690,7 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/platform-setup-sessions/${input.setup_ref}`,
+            path: `/workspaces/${input.workspace_id}/platform-setup-sessions/${encodeURIComponent(input.setup_ref)}`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
             'status: AWAITING_USER → VALIDATING → READY (`platform_id` готов) | VALIDATION_FAILED (`error_message`, напр. невалидный токен — пользователь может повторить) | EXPIRED (создайте новую сессию).',
@@ -927,7 +716,10 @@ export const crmPlatformTools = [
         createRequest: (input) => ({
             method: 'POST',
             path: `/workspaces/${input.workspace_id}/platform-oauth-sessions`,
-            body: compactObject({ platform_type: input.platform_type, name: input.name }),
+            body: compactObject({
+                platform_type: input.platform_type,
+                name: input.name,
+            }),
         }),
         enhanceResponse: (response) => withInstructions(response, [
             'Отдайте пользователю `auth_url` — он откроет его в браузере и авторизуется у провайдера (Instagram/Avito). Код авторизации НЕ проходит через LLM.',
@@ -936,12 +728,10 @@ export const crmPlatformTools = [
         ]),
     }),
     // ============================================================
-    // v1.5 Increment 5c — CRM Connection + Field Mapping + Operators (5 tools)
+    // CRM Connection + Field Mapping + Operators
     // ============================================================
-    // CRM create через Setup URL pattern (секреты в браузере, минуя LLM): GETCOURSE/TELEGRAM
-    // (API-key) + AMOCRM/BITRIX24 (вставка credentials; Bitrix24 далее завершает local-app install
-    // вебхуком). Field mapping + operators — для уже подключённых CRM (AmoCRM/Bitrix24 для mapping;
-    // AmoCRM для operators).
+    // CRM create через Setup URL pattern (секреты в браузере, минуя LLM): GetCourse, AmoCRM и
+    // Bitrix24. Field mapping + operators — для уже подключённых CRM.
     defineTool({
         name: 'besales_crm_create_init',
         sideEffect: 'write',
@@ -950,17 +740,22 @@ export const crmPlatformTools = [
         schema: z
             .object({
             workspace_id: uuidSchema.optional(),
+            operation_id: setupInitOperationIdSchema,
             crm_type: provisionableCrmTypeSchema,
             // Публичные non-secret поля: GETCOURSE={account_domain, managed_tag_prefix?};
-            // TELEGRAM={forum_group_id}; AMOCRM={sub_domain, client_id}; BITRIX24={domain, client_id}.
-            // Секреты (school_api_key / crm_bot_token / client_secret / long_access_token) — на /setup/:ref.
+            // AMOCRM={sub_domain, client_id}; BITRIX24={domain, client_id}.
+            // Секреты (school_api_key / client_secret / long_access_token) — на /setup/:ref.
             fields: optionalAnyObjectSchema,
         })
             .strict(),
         createRequest: (input) => ({
             method: 'POST',
             path: `/workspaces/${input.workspace_id}/crm-setup-sessions`,
-            body: compactObject({ crm_type: input.crm_type, fields: input.fields }),
+            body: compactObject({
+                operationId: input.operation_id,
+                crm_type: input.crm_type,
+                fields: input.fields,
+            }),
         }),
         enhanceResponse: (response) => withInstructions(response, [
             'Отдайте пользователю `setup_page_url` — он вводит в браузере ВСЕ поля (и секреты, и несекретные sub_domain/client_id/domain/...), минуя чат. Несекретные — в `required_non_secret_fields`, секреты — в `required_secret_fields`.',
@@ -982,11 +777,11 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/crm-setup-sessions/${input.setup_ref}`,
+            path: `/workspaces/${input.workspace_id}/crm-setup-sessions/${encodeURIComponent(input.setup_ref)}`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
             'status: AWAITING_USER → VALIDATING → READY (`crm_id`) | VALIDATION_FAILED (`error_message`) | EXPIRED.',
-            'READY = CRM создана + токен онлайн-проверен для Telegram-CRM (getMe) и GetCourse (read-only API-probe) → битый токен/ключ = VALIDATION_FAILED.',
+            'READY = CRM создана; GetCourse-ключ дополнительно проходит read-only API-probe, поэтому битый ключ даёт VALIDATION_FAILED.',
             'AmoCRM: на READY авто-активируется, ЕСЛИ это единственная CRM workspace (токен live-проверяется при активации). Если есть другая активная CRM или токен битый — остаётся inactive → включи besales_crm_activate({ crm_id }). Bitrix24: онлайн НЕ проверяется, требует РУЧНОЙ установки local-app в портале (вебхук).',
         ]),
     }),
@@ -1003,12 +798,11 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'POST',
-            path: `/workspaces/${input.workspace_id}/crms/${input.crm_id}/activate`,
+            path: `/crm-connections/${input.crm_id}/activate`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'CRM активирована: токен live-проверен, остальные CRM workspace деактивированы, связанные триггеры включены.',
-            'Активна одна CRM на workspace за раз — этот вызов ДЕАКТИВИРУЕТ предыдущую активную. Предупреди пользователя перед переключением.',
-            'Битый/просроченный токен → ошибка активации (CRM остаётся неактивной). Зови после исправления токена либо для переключения активной CRM.',
+            'CRM connection активирована после live-проверки credentials.',
+            'Операция может переключить активное CRM-подключение workspace; предупреди пользователя.',
         ]),
     }),
     defineTool({
@@ -1023,12 +817,12 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/crms`,
+            path: `/workspaces/${input.workspace_id}/crm-connections`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Список CRM workspace: id, type, status, is_active, account (поддомен/домен), created_at.',
+            'Список v2 CRM connections workspace без credentials.',
             'Пустой список → CRM не подключена (нужен besales_crm_create_init).',
-            'is_active=false → CRM есть, но не активна (besales_crm_activate); это объясняет, почему pipelines/field-mapping/operators могут не отвечать.',
+            'Неактивное подключение можно включить через besales_crm_activate.',
         ]),
     }),
     defineTool({
@@ -1048,8 +842,36 @@ export const crmPlatformTools = [
         enhanceResponse: (response) => withInstructions(response, [
             'Без зарегистрированного канала бот управляет сделкой, но переписка в её карточке НЕ появляется: channelId и channelSecretKey выдаёт только техподдержка AmoCRM по письму заданной формы.',
             'Текст письма и адрес вебхука отдаёт бэкенд — пересылай их человеку ДОСЛОВНО, не пересказывай и не собирай адрес сам. Тот же ответ показывает страница AmoCRM в интерфейсе.',
-            'placeholders — места, которые заполняет ЧЕЛОВЕК (номер учётной записи, Id интеграции, скриншот): их знает только владелец аккаунта, назови их отдельно.',
-            'Полученные от поддержки channelId и channelSecretKey привязываются в интерфейсе (POST /api/amo-crm/channel-connect) — через MCP этого шага нет.',
+            '⚠️ Метку :scope_id в адресе вебхука НЕ трогай и не заменяй: её подставляет сама amoCRM при каждом хуке. Секрета в адресе нет — это нормально.',
+            'placeholders — места, которые заполняет ЧЕЛОВЕК (номер учётной записи, Id интеграции, скриншот, контактный e-mail для связи при ошибках): их знает только владелец аккаунта, назови их отдельно.',
+            'crmConnectionId и crmConnectionName называют подключение, для которого собрана заявка: адрес принадлежит ПОДКЛЮЧЕНИЮ, а не рабочей области.',
+            'Если у рабочей области несколько подключений amoCRM и активное среди них не одно, сервер откажет и назовёт подключения по именам: заявку для нужного подключения открой в интерфейсе — этот инструмент подключение выбрать не умеет.',
+            'Полученные от поддержки channelId и секрет канала привязываются к каналу в интерфейсе (раздел подключения канала, чат amoCRM) — через ассистента секрет не проходит и этого шага в MCP нет.',
+        ]),
+    }),
+    // ⛔ Адрес приёма событий CRM через этот инструмент НЕ проходит: он несёт пропуск параметром
+    // строки запроса, а ответ инструмента ложится в транскрипт хоста и его телеметрию. Вместо
+    // адреса выдаётся одноразовая ссылка; страница за ней требует входа и права управлять CRM.
+    defineTool({
+        name: 'besales_crm_webhook_url_reveal',
+        sideEffect: 'write',
+        requiredFields: ['crm_id'],
+        defaultWorkspaceId: false,
+        schema: z
+            .object({
+            crm_id: uuidSchema,
+        })
+            .strict(),
+        createRequest: (input) => ({
+            method: 'POST',
+            path: '/crm-webhook-url-reveals',
+            body: { crmConnectionId: input.crm_id },
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Ответ: { revealUrl, revealExpiresAt }. Самого адреса в нём НЕТ и не будет: адрес несёт пропуск, а секреты через ассистента не проходят.',
+            'Передай человеку revealUrl и попроси открыть в браузере. Страница потребует входа и права управлять CRM и покажет адрес ОДИН раз.',
+            'Ссылка одноразовая и с ограниченным сроком (revealExpiresAt); просроченную или уже открытую заказывай заново этим же инструментом.',
+            'Адрес нужен, чтобы человек вписал его в настройки вебхуков amoCRM. У прочих провайдеров такого адреса нет — инструмент ответит отказом.',
         ]),
     }),
     defineTool({
@@ -1072,11 +894,11 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/crms/${input.crm_id}/field-mapping`,
+            path: `/crm-connections/${input.crm_id}/field-mappings`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Возвращает `available_fields` (поля из CRM) + `current_mappings`. Только AmoCRM/Bitrix24 — иначе `unsupported_reason`.',
-            'Используйте `available_fields[].id` как `crm_field_id` в `besales_crm_field_mapping_upsert`.',
+            'Возвращает текущий список v2 field mappings.',
+            'crm_field_id для upsert берётся из каталога полей CRM-провайдера.',
         ]),
     }),
     defineTool({
@@ -1096,16 +918,22 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'PUT',
-            path: `/workspaces/${input.workspace_id}/crms/${input.crm_id}/field-mapping`,
+            path: `/crm-connections/${input.crm_id}/field-mappings`,
             body: {
-                replace_all_existing: input.replace_all_existing,
                 enabled: input.enabled,
-                field_mappings: input.field_mappings,
+                mappings: input.field_mappings.map((mapping) => compactObject({
+                    crmFieldId: mapping.crm_field_id,
+                    crmFieldName: mapping.crm_field_name,
+                    saveAs: mapping.save_as,
+                    isEnabled: mapping.enabled,
+                    specialPurpose: mapping.special_purpose,
+                    category: mapping.category,
+                })),
             },
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Replace-all: передавайте ВЕСЬ набор маппингов (не патч). Только AmoCRM/Bitrix24 — иначе `unsupported_reason`.',
-            'Чтобы изменить — повторно вызовите с новым полным набором (это «undo»). Audit non-reversible (снимок before в diff).',
+            'Replace-all: передавай весь желаемый набор mappings, а не патч.',
+            'crmFieldName/fieldType/category сервер гидратирует из каталога, если они отсутствуют.',
         ]),
     }),
     defineTool({
@@ -1122,11 +950,11 @@ export const crmPlatformTools = [
             .strict(),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/crms/${input.crm_id}/operators${input.sync ? '?sync=true' : ''}`,
+            path: `/crm-connections/${input.crm_id}/operators${input.sync ? '?sync=true' : ''}`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Операторы для assignee-стратегий PipelineSettings. Только AmoCRM/Bitrix24 — иначе `unsupported_reason`.',
-            'sync=true пересинхронизирует операторов из CRM перед возвратом.',
+            'Возвращаются активные локальные CRM operators.',
+            'sync=true сначала синхронизирует сотрудников из CRM; если не удалось — отказ с причиной (CRM отдала список не полностью, CRM недоступна, синхронизация уже идёт, лимит запросов). Сохранённый список читается тем же инструментом без sync.',
         ]),
     }),
     defineTool({
@@ -1141,24 +969,87 @@ export const crmPlatformTools = [
             operator_id: uuidSchema,
             is_operator: z.boolean().optional(),
             is_sdr: z.boolean().optional(),
+            expected_version: z
+                .uuid()
+                .describe('Версия снимка из чтения; без автоматического перечитывания и повтора при конфликте')
+                .optional(),
+            workspace_member_id: z
+                .string()
+                .min(1)
+                .nullable()
+                .describe('users.id сотрудника Besales; null снимает связь вручную, пропуск сохраняет её')
+                .optional(),
         })
             .strict()
             .superRefine((input, ctx) => {
-            if (input.is_operator === undefined && input.is_sdr === undefined) {
+            if (input.workspace_member_id !== undefined && input.expected_version === undefined) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['expected_version'],
+                    message: 'Provide expected_version when changing workspace_member_id',
+                });
+            }
+            if (!CRM_OPERATOR_CHANGE_FIELDS.some((field) => input[field] !== undefined)) {
                 ctx.addIssue({
                     code: z.ZodIssueCode.custom,
-                    message: 'Provide at least one of is_operator / is_sdr',
+                    message: 'Provide at least one of is_operator / is_sdr / workspace_member_id',
                 });
             }
         }),
         createRequest: (input) => ({
             method: 'PATCH',
-            path: `/workspaces/${input.workspace_id}/crms/${input.crm_id}/operators/${input.operator_id}`,
-            body: compactObject({ is_operator: input.is_operator, is_sdr: input.is_sdr }),
+            path: `/crm-connections/${input.crm_id}/operators/${input.operator_id}`,
+            body: compactObject({
+                isOperator: input.is_operator,
+                isSdr: input.is_sdr,
+                expectedVersion: input.expected_version,
+                workspaceMemberId: input.workspace_member_id,
+            }),
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Обновляет флаги и ручную связь с сотрудником. workspace_member_id — users.id; null снимает связь вручную.',
+            'Передайте expected_version прочитанной строки при изменении связи. При 409 сохраните ввод и перечитайте для сравнения; автоматического повтора нет.',
+            'Непереданный флаг сохраняет текущее значение; operator_id бери из besales_crm_operator_list.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_crm_rotate_init',
+        sideEffect: 'write',
+        defaultWorkspaceId: true,
+        requiredFields: ['connection_id'],
+        schema: z
+            .object({
+            workspace_id: uuidSchema.optional(),
+            connection_id: uuidSchema,
+            mode: z.enum(['GETCOURSE_KEYS', 'LONG_LIVED', 'OAUTH_PENDING', 'OAUTH']).optional(),
+        })
+            .strict(),
+        createRequest: (input) => ({
+            method: 'POST',
+            path: `/workspaces/${input.workspace_id}/crm-connections/${input.connection_id}/credential-setup-sessions`,
+            body: compactObject({ mode: input.mode }),
+        }),
+        enhanceResponse: (response) => withInstructions(response, [
+            'Передай setup_page_url человеку: ключи вводятся только в браузере. Не проси секреты в чат. Затем опрашивай besales_crm_rotate_status. Существующая CRM и её связи сохраняются.',
+        ]),
+    }),
+    defineTool({
+        name: 'besales_crm_rotate_status',
+        sideEffect: 'none',
+        defaultWorkspaceId: true,
+        requiredFields: ['setup_ref'],
+        schema: z
+            .object({
+            workspace_id: uuidSchema.optional(),
+            setup_ref: z.string().min(1),
+        })
+            .strict(),
+        createRequest: (input) => ({
+            method: 'GET',
+            path: `/workspaces/${input.workspace_id}/crm-credential-setup-sessions/${encodeURIComponent(input.setup_ref)}`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Вкл/выкл роли конкретного оператора: is_operator (assignee диалогов) и/или is_sdr. Только AmoCRM/Bitrix24 — иначе `unsupported_reason`.',
-            'Передайте хотя бы один флаг; не указанный сохраняет текущее значение. operator_id берётся из `besales_crm_operator_list`.',
+            'READY означает принятую смену ключей существующей CRM, авторизация или установка приложения могут ещё требоваться. Секреты и установочный адрес доступны только человеку в браузере.',
         ]),
     }),
 ];