@besales/mcp 0.48.0 → 1.0.0-beta.4

package/scripts/sync-api-contracts.spec.mjs

@@ -0,0 +1,144 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { toolDefinitions } from '../src/tools/definitions.ts';
+import { syncSchemaDescriptions } from './sync-schema-descriptions.mjs';
+
+const options = { io: 'input', unrepresentable: 'any' };
+
+describe('генератор контрактов: описания полей', () => {
+  it('переносит новые и обновлённые описания любых полей, сохраняя ограничения и подписи без замены', () => {
+    const target = {
+      type: 'object',
+      required: ['another_field'],
+      properties: {
+        another_field: { type: 'integer', enum: [1, 2], description: 'старое описание' },
+        new_hint: { type: 'string', minLength: 4 },
+        published_hint: { type: 'string', description: 'подпись каталога' },
+        catalog_only: { type: 'boolean', description: 'только каталог' },
+      },
+      allOf: [{ if: { required: ['new_hint'] }, then: { required: ['published_hint'] } }],
+    };
+    const before = structuredClone(target);
+    const derived = z.toJSONSchema(
+      z.object({
+        another_field: z.number().int().describe('актуальное описание'),
+        new_hint: z.string().describe('новая подсказка'),
+        published_hint: z.string(),
+        executable_only: z.string().describe('не добавлять поле'),
+      }),
+      options,
+    );
+    const source = structuredClone(derived);
+
+    syncSchemaDescriptions(target, derived);
+
+    before.properties.another_field.description = 'актуальное описание';
+    before.properties.new_hint.description = 'новая подсказка';
+    expect(target).toEqual(before);
+    expect(derived).toEqual(source);
+    syncSchemaDescriptions(target, derived);
+    expect(target).toEqual(before);
+  });
+
+  it('обходит вложенные объекты, элементы массивов, словари и ветви схем', () => {
+    const derived = z.toJSONSchema(
+      z.object({
+        rows: z.array(z.object({
+          value: z.string().describe('значение строки'),
+          description: z.string().describe('подсказка поля с именем description'),
+        }).describe('строка')).describe('строки'),
+        dictionary: z.record(z.string(), z.string().describe('значение словаря')),
+        choice: z.union([
+          z.string().describe('текст'),
+          z.object({ count: z.number().describe('количество') }),
+        ]),
+      }),
+      options,
+    );
+    const target = structuredClone(derived);
+    const withoutDescriptions = (value) => {
+      if (!value || typeof value !== 'object') return;
+      if (typeof value.description === 'string') delete value.description;
+      Object.values(value).forEach(withoutDescriptions);
+    };
+    withoutDescriptions(target);
+    syncSchemaDescriptions(target, derived);
+    expect(target).toEqual(derived);
+
+    const conditional = { allOf: [{ if: {}, then: {}, else: {} }], oneOf: [{}], prefixItems: [{}] };
+    const annotations = {
+      allOf: [{
+        if: { description: 'условие' },
+        then: { description: 'да' },
+        else: { description: 'нет' },
+      }],
+      oneOf: [{ description: 'вариант' }],
+      prefixItems: [{ description: 'элемент' }],
+    };
+    syncSchemaDescriptions(conditional, annotations);
+    expect(conditional).toEqual(annotations);
+  });
+
+  it('не переписывает description внутри пользовательских default/const/enum/examples', () => {
+    const target = {
+      default: { description: 'данные' },
+      const: { description: 'данные' },
+      enum: [{ description: 'данные' }],
+      examples: [{ description: 'данные' }],
+      additionalProperties: false,
+    };
+    const before = structuredClone(target);
+    syncSchemaDescriptions(target, {
+      default: { description: 'не подпись' },
+      const: { description: 'не подпись' },
+      enum: [{ description: 'не подпись' }],
+      examples: [{ description: 'не подпись' }],
+      additionalProperties: { description: 'не менять boolean-схему' },
+    });
+    expect(target).toEqual(before);
+    expect(() => syncSchemaDescriptions(undefined, {})).not.toThrow();
+    expect(() => syncSchemaDescriptions({}, false)).not.toThrow();
+  });
+
+  it('S28: на текущем снимке переносит адаптивный горизонт и не меняет в каталоге ничего кроме описаний', () => {
+    const registry = JSON.parse(
+      readFileSync(new URL('../src/schemas/mcp-tools.json', import.meta.url), 'utf8'),
+    );
+    const snapshot = readFileSync(new URL('../src/types/api-contract.gen.ts', import.meta.url), 'utf8');
+    expect(snapshot).toContain('Если не передан, сервер подбирает его по доле вырезанных касаний');
+    const before = structuredClone(registry);
+    for (const definition of toolDefinitions) {
+      const tool = registry.tools.find((entry) => entry.name === definition.name);
+      expect(tool, definition.name).toBeDefined();
+      syncSchemaDescriptions(tool.inputSchema, z.toJSONSchema(definition.schema, options));
+    }
+    const horizon = registry.tools.find(
+      (entry) => entry.name === 'besales_followup_reactions',
+    ).inputSchema.properties.horizon_minutes;
+    const definition = toolDefinitions.find((entry) => entry.name === 'besales_followup_reactions');
+    expect(horizon.description).toBe(
+      z.toJSONSchema(definition.schema, options).properties.horizon_minutes.description,
+    );
+    expect(horizon.description).toContain('Если не передан, сервер подбирает горизонт');
+    expect(horizon.description).not.toMatch(/по умолчанию 90/iu);
+    const withoutDescriptions = (value) => {
+      if (Array.isArray(value)) return value.map(withoutDescriptions);
+      if (!value || typeof value !== 'object') return value;
+      return Object.fromEntries(
+        Object.entries(value)
+          .filter(([key, child]) => key !== 'description' || typeof child !== 'string')
+          .map(([key, child]) => [key, withoutDescriptions(child)]),
+      );
+    };
+    expect(withoutDescriptions(registry)).toEqual(withoutDescriptions(before));
+    const generated = structuredClone(registry);
+    for (const definition of toolDefinitions) {
+      syncSchemaDescriptions(
+        registry.tools.find((entry) => entry.name === definition.name).inputSchema,
+        z.toJSONSchema(definition.schema, options),
+      );
+    }
+    expect(registry).toEqual(generated);
+  });
+});

package/scripts/sync-contract-ledger-schemas.mjs

@@ -0,0 +1,161 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { z } from 'zod';
+import { syncSchemaDescriptions } from './sync-schema-descriptions.mjs';
+const { v15DescriptionUpdates } = await import(process.env.BESALES_MCP_SCHEMA_SOURCE === '1'
+  ? '../src/tools/definitions/v15-port-descriptions.ts' : '../dist/tools/definitions/v15-port-descriptions.js');
+const { toolDefinitions } = await import(process.env.BESALES_MCP_SCHEMA_SOURCE === '1'
+  ? '../src/tools/definitions.ts' : '../dist/tools/definitions.js');
+const { MODEL_COMPARISON_MAX_MODELS } = await import(process.env.BESALES_MCP_SCHEMA_SOURCE === '1'
+  ? '../src/tools/definitions/model-comparison.ts' : '../dist/tools/definitions/model-comparison.js');
+
+// Меняются только узлы этой поправки: описания остальных инструментов сохраняются.
+const registryPath = new URL('../src/schemas/mcp-tools.json', import.meta.url);
+const original = readFileSync(registryPath, 'utf8');
+const registry = JSON.parse(original);
+const selected = {
+  besales_model_comparison_run_start: ['models'],
+  besales_agent_list: ['query'],
+  besales_contact_search: ['phone', 'email', 'external_id'],
+  besales_trigger_upsert: ['allow_repeated_calls', 'run_once_per_contact'],
+  besales_trigger_claim_list: ['contact_id', 'chat_user_id'],
+  besales_broadcast_analytics_get: ['reason'],
+  besales_dialogue_audit_findings: ['agent_id'],
+  besales_dialogue_audit_import: ['findings.items.category', 'findings.items.severity', 'findings.items.expected_behavior'],
+  ...Object.fromEntries(['document','qa','table','website'].map((kind) => [`besales_knowledge_${kind}_list`, ['page']])),
+};
+const constraints = ['type','format','enum','const','minLength','maxLength','minimum','maximum','minItems','maxItems','default'];
+function node(root, key, create = false) {
+  const parts = key.split('.');
+  let parent = root;
+  for (const part of parts.slice(0,-1)) {
+    if (part === 'items') parent = parent.items;
+    else parent = parent.properties[part];
+  }
+  parent.properties ??= {};
+  const last = parts.at(-1);
+  if (create) parent.properties[last] ??= {};
+  return { parent, last, value: parent.properties[last] };
+}
+for (const [name, keys] of Object.entries(selected)) {
+  const tool = registry.tools.find((entry) => entry.name === name);
+  const definition = toolDefinitions.find((entry) => entry.name === name);
+  if (!tool || !definition) throw new Error(`Нет инструмента ${name}`);
+  const derived = z.toJSONSchema(definition.schema, { io: 'input' });
+  for (const key of keys) {
+    const source = node(derived, key).value;
+    if (!source) throw new Error(`${name}.${key} отсутствует в zod`);
+    const destination = node(tool.inputSchema, key, true).value;
+    for (const field of constraints) {
+      delete destination[field];
+      if (source[field] !== undefined && !(['minimum','maximum'].includes(field) &&
+          Math.abs(source[field]) === Number.MAX_SAFE_INTEGER)) destination[field] = source[field];
+    }
+  }
+  if (name === 'besales_dialogue_audit_findings') {
+    // В v1.5 это уже был UUID: возвращаем прежний контракт, без нового pattern.
+    const agent = tool.inputSchema.properties.agent_id;
+    delete agent.pattern;
+    agent.description = node(derived, 'agent_id').value.description;
+  }
+  if (name === 'besales_trigger_claim_list') tool.inputSchema.required = [];
+  if (name.startsWith('besales_knowledge_') && name.endsWith('_list')) {
+    tool.description = tool.description.replace(/page\/limit применяются локально MCP-клиентом[^.]*\.?/gu, 'limit и cursor передаются серверу.');
+    delete tool.inputSchema.properties.limit.default;
+    tool.inputSchema.properties.page.description = 'Прежний page отвергается до запроса: продолжайте по cursor из предыдущего ответа.';
+  }
+}
+const search = registry.tools.find((entry) => entry.name === 'besales_contact_search');
+const comparison = registry.tools.find((entry) => entry.name === 'besales_model_comparison_run_start');
+comparison.description = comparison.description.replace(/1\.\.\d+/gu, `1..${MODEL_COMPARISON_MAX_MODELS}`);
+comparison.inputSchema.properties.models.description = comparison.inputSchema.properties.models.description.replace(/1\.\.\d+/gu, `1..${MODEL_COMPARISON_MAX_MODELS}`);
+search.inputSchema.properties.email.description = 'Один email или CSV почт через запятую; предел всей строки 8192.';
+search.inputSchema.properties.phone.description = 'Один телефон или CSV телефонов через запятую, международный формат. Национальная запись не переписывается (8 не заменяется на +7); предел всей строки 8192.';
+const claims = registry.tools.find((entry) => entry.name === 'besales_trigger_claim_list');
+claims.inputSchema.properties.chat_user_id.description = 'Прежнее имя contact_id. Передайте одно имя или одинаковые значения; разные адреса отвергаются.';
+const triggers = registry.tools.find((entry) => entry.name === 'besales_trigger_upsert');
+triggers.inputSchema.properties.allow_repeated_calls.description = 'Прежний флаг повтора: переводится маппером переноса в allow_repeat_in_conversation. run_once_per_contact=true имеет приоритет; горизонт новой системы — переписка, не контакт навсегда.';
+triggers.inputSchema.properties.run_once_per_contact.description = 'Прежняя однократность: true переводится в allow_repeat_in_conversation=false. После закрытия переписки право возвращается; повтор в CRM возможен. Не смешивайте с новым именем.';
+// SATMCPB: обновляем только перенесённые поля; ручные allOf и остальной контракт сохраняются.
+const portFields = {
+  besales_getcourse_wave_import: ['channels', 'funnel'],
+  besales_getcourse_wave_run_start: ['channels', 'funnel'],
+  besales_getcourse_wave_run_batch_start: ['segments.items.channels', 'segments.items.funnel'],
+};
+for (const name of new Set([...Object.keys(portFields), ...Object.keys(v15DescriptionUpdates), 'besales_broadcast_schedule_upsert'])) {
+  const tool = registry.tools.find((entry) => entry.name === name);
+  const definition = toolDefinitions.find((entry) => entry.name === name);
+  if (!tool || !definition) throw new Error('PORT_TOOL_MISSING:' + name);
+  const derived = z.toJSONSchema(definition.schema, { io: 'input', target: 'draft-7' });
+  syncSchemaDescriptions(tool.inputSchema, derived);
+  for (const field of portFields[name] ?? []) {
+    const source = node(derived, field).value;
+    if (!source) throw new Error('PORT_FIELD_MISSING:' + name + '.' + field);
+    const target = node(tool.inputSchema, field, true);
+    // Nullable оформляем как type:[T,null], чтобы опись видела границы значения.
+    const nonNull = source.anyOf?.find((branch) => branch.type !== 'null');
+    const nullable = source.anyOf?.length === 2 && source.anyOf.some((branch) => branch.type === 'null');
+    if (nullable && nonNull && ['string', 'integer'].includes(nonNull.type)) {
+      const { anyOf: _branches, ...metadata } = source;
+      target.parent.properties[target.last] = { ...nonNull, ...metadata, type: [nonNull.type, 'null'] };
+    } else target.parent.properties[target.last] = source;
+  }
+  // Снимаем прежние подсказки перед добавлением исправленных: повторный sync идемпотентен.
+  if (name === 'besales_broadcast_analytics_get' && !tool.description.includes(v15DescriptionUpdates[name].append)) {
+    tool.description = tool.description.replace('mode=range требует полный упорядоченный диапазон from/to. Параметры должны поддерживаться выбранным report; payment_candidates: page_size не больше 100. payment_view можно сочетать с payment_status/payment_eligibility: API отдаёт приоритет view.', '').replace('mode=range принимает открытый диапазон: только from, только to или обе границы; если заданы обе, to не раньше from. Параметры должны поддерживаться выбранным report; payment_candidates: page_size не больше 100. payment_view можно сочетать с payment_status/payment_eligibility: API отдаёт приоритет view.', '').trim();
+  }
+  if (name === 'besales_broadcast_schedule_runs') {
+    tool.description = tool.description.replace(/Снятые из-за переменных блоки: excludedBy\.blockPlaceholdersUnresolved, исход SKIPPED_UNRESOLVED_VARS и пауза 6 часов; имена переменных — в причине строк журнала\./u, 'Снятие БЛОКА планом из-за переменных: excludedBy.blockPlaceholdersUnresolved, исход SKIPPED_UNRESOLVED_VARS и пауза 6 часов (при отправке отдельному человеку пауза сутки); имена переменных — в причине строк журнала.');
+  }
+  const update = v15DescriptionUpdates[name];
+  if (update) {
+    for (const [from, to] of update.replace ?? []) tool.description = tool.description.replace(from, to);
+    if (!tool.description.includes(update.append)) tool.description += ' ' + update.append;
+  }
+}
+// Условная схема архивации тоже обязана объявлять boolean для const:true.
+const archive = registry.tools.find((entry) => entry.name === 'besales_broadcast_mailing_variant_update');
+archive.inputSchema.if.properties.archived = z.toJSONSchema(z.literal(true), { io: 'input' });
+delete archive.inputSchema.if.properties.archived.$schema;
+// Сохраняем остальные условия фасада. Потолок берётся из выделенного списка оплат.
+const facade = registry.tools.find((entry) => entry.name === 'besales_broadcast_analytics_get');
+delete facade.inputSchema.properties.mode.default;
+const pageSize = registry.tools.find((entry) => entry.name === 'besales_broadcast_payment_candidates_list').inputSchema.properties.page_size;
+const pageCap = {
+  if: { properties: { report: { const: 'payment_candidates' } }, required: ['report'] },
+  then: { properties: { page_size: { type: 'integer', minimum: pageSize.minimum, maximum: pageSize.maximum } } },
+};
+facade.inputSchema.allOf = (facade.inputSchema.allOf ?? []).filter((rule) => rule.if?.properties?.report?.const !== 'payment_candidates');
+facade.inputSchema.allOf.push(pageCap);
+facade.inputSchema.allOf = facade.inputSchema.allOf.filter((rule) => rule.if?.properties?.mode?.const !== 'range');
+facade.inputSchema.allOf.push({
+  if: { properties: { report: { enum: ['payment_candidates', 'payment_candidates_summary'] }, mode: { const: 'range' } }, required: ['report', 'mode'] },
+  then: { anyOf: [{ required: ['from'] }, { required: ['to'] }] },
+});
+const findings = registry.tools.find((entry) => entry.name === 'besales_dialogue_audit_findings');
+const agentScopeHint = 'agent_id необязателен: мост сначала читает разбор (besales_dialogue_audit_run_get) и сверяет agentId; при несовпадении — «разбор относится к другому агенту», без запроса находок. Без agent_id находки читаются сразу.';
+findings.description = findings.description.replace('⛔ Фильтра по агенту у инструмента нет: прогон v2 принадлежит ОДНОМУ агенту, и фильтр невыразим. Чей это прогон — покажет besales_dialogue_audit_run_get.', agentScopeHint);
+if (!findings.description.includes(agentScopeHint)) findings.description += ' ' + agentScopeHint;
+// Владельцы и ссылки описи воспроизводятся вместе со схемами. ACTIVE-решения
+// для новых точных ключей ратифицируются в API, а не выдумываются генератором.
+const lagPath = new URL('../src/schemas/shipped-lag.json', import.meta.url);
+const lagOriginal = readFileSync(lagPath, 'utf8');
+const lag = JSON.parse(lagOriginal);
+const channelDecisions = {
+  besales_getcourse_wave_import: '6.19.51:ratification-e91ef72931a8',
+  besales_getcourse_wave_run_batch_start: '6.19.51:ratification-dd43ed6fe094',
+  besales_getcourse_wave_run_start: '6.19.51:ratification-f32263f46446',
+};
+for (const [key, row] of Object.entries(lag.contractLag)) {
+  const id = channelDecisions[key.split('::')[0]];
+  if (id && key.includes('channels[]#enum')) {
+    row.owner = 'DELIBERATE';
+    row.severity = 'DELIBERATE';
+    row.reason = row.reason.replace(/decision:[^\s;,]+/gu, 'decision:' + id);
+  }
+}
+for (const [path, before, value] of [[registryPath, original, registry], [lagPath, lagOriginal, lag]]) {
+  const output = JSON.stringify(value, null, 2) + '\n';
+  if (process.argv.includes('--check')) {
+    if (before !== output) throw new Error(`${path.pathname}: выполните sync-contract-ledger-schemas.mjs`);
+  } else writeFileSync(path, output);
+}

package/scripts/sync-crm-stage-pool-schema.mjs

@@ -0,0 +1,85 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import openapiTS from 'openapi-typescript';
+import { z } from 'zod';
+import {
+  triggerActionItemSchema,
+  followupSequenceConfigSchema,
+} from '../dist/tools/definitions/platform-setup.js';
+import {
+  crmMoveStageConfigSchema,
+  stagePoolFields,
+} from '../dist/tools/definitions/crm-stage-pool.schema.js';
+import { CRM_STAGE_ACTION_POOL_MAX_SIZE } from '../dist/shared/constants/crm-stage-pool.constants.js';
+
+// Каталог ссылки берётся из принятого API. Отставание соседних полей этим выпуском не снимается.
+const contractsDir = process.env.BESALES_API_CONTRACTS_DIR?.trim() || '../besales-api/contracts';
+let apiPool;
+await openapiTS(pathToFileURL(resolve(contractsDir, 'openapi-besales-api.yaml')), {
+  transform(schema) {
+    if (
+      schema.properties?.step_type?.enum?.includes('CRM_MOVE_STAGE') &&
+      schema.properties.assign_responsible_operator_ids
+    )
+      apiPool = schema.properties.assign_responsible_operator_ids;
+  },
+});
+if (
+  apiPool?.type !== 'array' ||
+  apiPool.items?.format !== 'uuid' ||
+  apiPool.uniqueItems !== true ||
+  apiPool.minItems !== 1 ||
+  apiPool.maxItems !== undefined
+)
+  throw new Error('CRM_STAGE_POOL_CONTRACT_MISSING_OR_DRIFTED');
+const options = { target: 'draft-7', io: 'input' };
+const stage = z.toJSONSchema(crmMoveStageConfigSchema, options);
+const action = z.toJSONSchema(triggerActionItemSchema, options);
+const followup = z.toJSONSchema(followupSequenceConfigSchema, options);
+delete stage.$schema;
+for (const name of Object.keys(stagePoolFields)) {
+  const property = stage.properties[name];
+  const array = property.anyOf.find((branch) => branch.type === 'array');
+  array.uniqueItems = true;
+  if (name === 'assign_responsible_operator_ids') array.items = apiPool.items;
+  followup.properties[name] = JSON.parse(JSON.stringify(property));
+  array.maxItems = CRM_STAGE_ACTION_POOL_MAX_SIZE;
+}
+const extraArray = stage.properties.extra.properties.assignResponsibleOperatorIds.anyOf.find(
+  (branch) => branch.type === 'array',
+);
+extraArray.maxItems = CRM_STAGE_ACTION_POOL_MAX_SIZE;
+extraArray.uniqueItems = true;
+
+const target = new URL('../src/schemas/mcp-tools.json', import.meta.url);
+const registry = JSON.parse(readFileSync(target, 'utf8'));
+const trigger = registry.tools.find((tool) => tool.name === 'besales_trigger_upsert');
+const chain = registry.tools.find((tool) => tool.name === 'besales_followup_sequence_upsert');
+const read = registry.tools.find((tool) => tool.name === 'besales_followup_sequence_list');
+if (
+  !trigger?.inputSchema?.properties?.actions?.items?.properties?.config ||
+  !chain?.inputSchema?.properties?.config ||
+  !read?.inputSchema?.properties
+)
+  throw new Error('CRM_STAGE_POOL_TOOL_MISSING');
+const item = trigger.inputSchema.properties.actions.items;
+item.properties.type = action.properties.type;
+for (const container of ['crmConfig', 'crmMoveStage', 'crmMoveStageConfig'])
+  item.properties[container] = stage;
+for (const name of Object.keys(stagePoolFields)) {
+  item.properties.config.properties[name] = stage.properties[name];
+  chain.inputSchema.properties.config.properties[name] = followup.properties[name];
+}
+item.properties.config.properties.extra = stage.properties.extra;
+read.description = read.description.replace(
+  'Отдаёт РЕЗУЛЬТАТ трансляции (какие шаги реально исполняются), а не вход besales_followup_sequence_upsert: конфигурацию в форме v1.5 инструмент не возвращает.',
+  'С sequence_id возвращает сохранённые type, trigger, config и configUnavailableReason для правки. Пул сохраняется в config без сортировки. При config=null требуется полное восстановление формы; latestVersion.steps не подставляют в config.',
+);
+const hint = stagePoolFields.assign_responsible_operator_ids.description;
+for (const tool of [trigger, chain])
+  if (!tool.description.includes(hint)) tool.description += ` ${hint}`;
+const serialized = `${JSON.stringify(registry, null, 2)}\n`;
+writeFileSync(target, serialized);
+mkdirSync(new URL('../dist/schemas/', import.meta.url), { recursive: true });
+writeFileSync(new URL('../dist/schemas/mcp-tools.json', import.meta.url), serialized);

package/scripts/sync-prompt-draft-schema.mjs

@@ -0,0 +1,92 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { z } from 'zod';
+
+/** Меняются только входы выбора: остальные принятые определения сохраняют свои подписи. */
+const target = new URL('../src/schemas/mcp-tools.json', import.meta.url);
+const registry = JSON.parse(readFileSync(target, 'utf8'));
+mkdirSync(new URL('../dist/schemas/', import.meta.url), { recursive: true });
+writeFileSync(new URL('../dist/schemas/mcp-tools.json', import.meta.url), JSON.stringify(registry));
+const { toolDefinitions } = await import('../dist/tools/definitions.js');
+const names = ['besales_prompt_patch_start', 'besales_prompt_drafts_mine'];
+for (const name of names) {
+  const definition = toolDefinitions.find((tool) => tool.name === name);
+  if (!definition) throw new Error('Missing prompt draft tool: ' + name);
+  const generated = z.toJSONSchema(definition.schema, {
+    target: 'draft-7',
+    io: 'input',
+  });
+  delete generated.$schema;
+  let contract = registry.tools.find((tool) => tool.name === name);
+  if (!contract) {
+    contract = {
+      name,
+      description:
+        'Мои черновики по агенту: текущий ACTIVE отдельно от страницы истории; только metadata без текста.',
+      inputSchema: generated,
+      executionMode: 'proxy',
+    };
+    const position = toolDefinitions.findIndex((tool) => tool.name === name);
+    const previous = toolDefinitions[position - 1].name;
+    registry.tools.splice(
+      registry.tools.findIndex((tool) => tool.name === previous) + 1,
+      0,
+      contract,
+    );
+  } else if (name === 'besales_prompt_patch_start') {
+    for (const field of ['mode', 'draft_id', 'expected_content_hash'])
+      contract.inputSchema.properties[field] = generated.properties[field];
+    contract.description =
+      'Начать черновик. CREATED / CONTINUED обозначают успех; CHOICE_REQUIRED требует явного выбора автора через mode, draft_id и expected_content_hash. Чужие конфликты возвращаются числом conflictingDraftCount.';
+  } else {
+    contract.inputSchema = generated;
+    contract.description =
+      'Мои черновики по агенту: текущий ACTIVE отдельно от страницы истории; только metadata без текста.';
+  }
+}
+const serialized = JSON.stringify(registry, null, 2) + '\n';
+writeFileSync(target, serialized);
+mkdirSync(new URL('../dist/schemas/', import.meta.url), { recursive: true });
+writeFileSync(new URL('../dist/schemas/mcp-tools.json', import.meta.url), serialized);
+
+const routeTarget = new URL('../src/schemas/mcp-v2-route-map.json', import.meta.url);
+const routes = JSON.parse(readFileSync(routeTarget, 'utf8'));
+const mine = toolDefinitions.find((tool) => tool.name === 'besales_prompt_drafts_mine');
+const canonicalArgs = { agent_id: '00000000-0000-4000-8000-000000000002' };
+const request = mine.createRequest(mine.schema.parse(canonicalArgs));
+const entry = {
+  tool: mine.name,
+  canonicalArgs,
+  expected: {
+    method: request.method,
+    pathTemplate: '/agents/:agentId/prompt/drafts/mine',
+    path: request.path,
+  },
+};
+const index = routes.findIndex((row) => row.tool === mine.name);
+if (index < 0) routes.push(entry);
+else routes[index] = entry;
+writeFileSync(routeTarget, JSON.stringify(routes, null, 2) + '\n');
+
+const { toolInventoryCounts, renderToolInventoryMarkdown } =
+  await import('../dist/tools/inventory.js');
+const activeNames = registry.tools.map((tool) => tool.name);
+registry.summary.total_tools = activeNames.length;
+registry.summary.tools_by_category = toolInventoryCounts(activeNames);
+const completeRegistry = JSON.stringify(registry, null, 2) + '\n';
+writeFileSync(target, completeRegistry);
+writeFileSync(new URL('../dist/schemas/mcp-tools.json', import.meta.url), completeRegistry);
+const readmeTarget = new URL('../README.md', import.meta.url);
+const readme = readFileSync(readmeTarget, 'utf8');
+const startMarker = '<!-- BEGIN GENERATED TOOL INVENTORY -->';
+const endMarker = '<!-- END GENERATED TOOL INVENTORY -->';
+const start = readme.indexOf(startMarker),
+  end = readme.indexOf(endMarker);
+if (start < 0 || end < start) throw new Error('README inventory markers missing');
+writeFileSync(
+  readmeTarget,
+  readme.slice(0, start + startMarker.length) +
+    '\n' +
+    renderToolInventoryMarkdown(activeNames) +
+    '\n' +
+    readme.slice(end),
+);

package/scripts/sync-route-map.mjs

@@ -0,0 +1,94 @@
+// Пересобирает только карту и локальные доказательства маршрутов; API остаётся входом.
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { sampleFor, resetSampleUid } from './sample-args.mjs';
+const contracts = process.env.BESALES_API_CONTRACTS_DIR?.trim();
+if (!contracts) throw new Error('BESALES_API_CONTRACTS_DIR обязателен: contracts/ выбранного API');
+const apiFile = resolve(contracts, 'openapi-besales-api.yaml');
+const apiText = readFileSync(apiFile, 'utf8');
+if (/^(?:<<<<<<<|=======|>>>>>>>)/mu.test(apiText)) throw new Error('OPENAPI_MERGE_CONFLICT');
+const { toolDefinitions } = await import('../dist/tools/definitions.js');
+copyFileSync(new URL('../src/schemas/mcp-v2-route-map.json', import.meta.url), new URL('../dist/schemas/mcp-v2-route-map.json', import.meta.url));
+const { mappingCases } = await import('../dist/tools/registry-mapping.cases.js');
+const registry = JSON.parse(readFileSync(new URL('../src/schemas/mcp-tools.json', import.meta.url), 'utf8'));
+const known = new Map(registry.tools.map((tool) => [tool.name, tool]));
+const routeFile = new URL('../src/schemas/mcp-v2-route-map.json', import.meta.url);
+const original = readFileSync(routeFile, 'utf8');
+const rows = JSON.parse(original);
+// Справочники не принимают фильтр периода: прежний образец mode=all стал недопустим.
+for (const row of rows) {
+  if (['besales_broadcast_analytics_get@segments_catalog', 'besales_broadcast_analytics_get@funnel_products'].includes(row.tool)) delete row.canonicalArgs.mode;
+}
+const definitions = new Map(toolDefinitions.map((definition) => [definition.name, definition]));
+const snapshot = readFileSync(new URL('../src/types/api-contract.gen.ts', import.meta.url), 'utf8');
+const paths = [...snapshot.matchAll(/^ {4}"(\/[^"]*)":\s*\{\n([\s\S]*?)^ {4}\};$/gm)].map((block) => ({
+  path: block[1], methods: new Set([...block[2].matchAll(/^ {8}([a-z]+):[ \t]*(\S[^\n]*)/gm)].filter((match) => !/^never\b/u.test(match[2])).map((match) => match[1].toUpperCase())),
+  regex: new RegExp('^' + block[1].split('/').map((part) => part.startsWith('{') ? '[^/]+' : part.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')).join('/') + '$'),
+})).sort((a, b) => (a.path.match(/\{/gu)?.length ?? 0) - (b.path.match(/\{/gu)?.length ?? 0));
+// Маршрут намеренно исключён из публичного OpenAPI, но зарегистрирован в текущем API.
+const privateController = resolve(contracts, '../src/control/channel/crm-webhook-url-reveal.controller.ts');
+const privateModule = resolve(contracts, '../src/control/channel/channel.module.ts');
+const controllerSource = readFileSync(privateController, 'utf8');
+const moduleSource = readFileSync(privateModule, 'utf8');
+const controller = /@Controller\('([^']+)'\)/u.exec(controllerSource);
+if (!controller || !/@Post\(\)/u.test(controllerSource) || !/@HiddenFromPublicDocs/u.test(controllerSource) || !/controllers:\s*\[[\s\S]*?CrmWebhookUrlRevealController/u.test(moduleSource)) throw new Error('PRIVATE_CRM_ROUTE_NOT_REGISTERED');
+const privatePath = '/api/v2/' + controller[1];
+paths.push({ path: privatePath, methods: new Set(['POST']), regex: new RegExp('^' + privatePath + '$'), private: true });
+const initialRows = JSON.parse(execFileSync('git', ['show', 'HEAD:src/schemas/mcp-v2-route-map.json'], { encoding: 'utf8' }));
+const initialByName = new Map(initialRows.map((row) => [row.tool, row]));
+const errors = [];
+const changes = [];
+for (const definition of toolDefinitions) {
+  if (!definition.createRequest || rows.some((row) => row.tool.split('@')[0] === definition.name)) continue;
+  resetSampleUid();
+  const schema = known.get(definition.name).inputSchema;
+  const args = mappingCases.find((row) => row.name === definition.name)?.input ?? sampleFor(definition.name, schema, true);
+  if (definition.name === 'besales_feedback_document_access_update') args.expected_document_snapshot = 'a'.repeat(64);
+  rows.push({ tool: definition.name, canonicalArgs: args });
+}
+for (const row of rows) {
+  const definition = definitions.get(row.tool.split('@')[0]);
+  try {
+    const input = definition.schema.parse(row.canonicalArgs);
+    const request = definition.createRequest(input);
+    const url = new URL(request.path, 'https://api.test');
+    const method = request.method ?? 'POST';
+    const route = paths.find((candidate) => candidate.regex.test('/api/v2' + url.pathname) && candidate.methods.has(method));
+    if (!route) throw new Error(`API_ROUTE_MISSING:${method} ${url.pathname}`);
+    const query = {};
+    for (const key of new Set(url.searchParams.keys())) {
+      const values = url.searchParams.getAll(key);
+      query[key] = values.length === 1 ? values[0] : values;
+    }
+    const expected = { method, path: url.pathname, pathTemplate: route.path.slice('/api/v2'.length).replace(/\{([^}]+)\}/gu, ':$1') };
+    if (Object.keys(query).length) expected.query = query;
+    if (request.body instanceof FormData) {
+      const fields = {};
+      let file;
+      for (const [key, value] of request.body.entries()) {
+        if (typeof value === 'string') fields[key] = value;
+        else file = { fieldName: key, filename: value.name, contentType: value.type, content: await value.text() };
+      }
+      expected.multipart = { fields, file };
+    } else if (request.body !== undefined) expected.body = request.body;
+    const before = initialByName.get(row.tool)?.expected;
+    if (before && (before.method !== method || before.pathTemplate !== expected.pathTemplate)) changes.push({ tool: row.tool, before: before.method + ' ' + before.pathTemplate, after: method + ' ' + expected.pathTemplate });
+    if (row.tool.startsWith('besales_dialogue_audit_run_start@')) expected.body.idempotencyKey = '00000000-0000-4000-8000-000000000090';
+    row.expected = expected;
+    if (route.private) { delete row.backendTarget; row.contractVisibility = 'CUSTOMER'; }
+    else row.backendTarget = 'besales-api';
+  } catch (error) { errors.push({ tool: row.tool, error: String(error) }); }
+}
+const artifactDir = new URL('../.codex-artifacts-bridge-train2/', import.meta.url);
+mkdirSync(artifactDir, { recursive: true });
+const payload = { privateRoutes: [{ method: 'POST', path: privatePath, controller: privateController, sha256: createHash('sha256').update(controllerSource).digest('hex') }], source: 'working-tree', apiOpenApi: apiFile, apiSha256: createHash('sha256').update(apiText).digest('hex'), apiHead: execFileSync('git', ['-C', resolve(contracts, '..'), 'rev-parse', 'HEAD'], { encoding: 'utf8' }).trim(), totalTools: toolDefinitions.length, localTools: toolDefinitions.filter((tool) => !tool.createRequest).map((tool) => tool.name), checkedApiTools: new Set(rows.map((row) => row.tool.split('@')[0])).size, records: rows.length, changes, errors };
+writeFileSync(new URL('route-audit.json', artifactDir), JSON.stringify(payload, null, 2) + '\n');
+writeFileSync(new URL('mcp-tool-routes.json', artifactDir), JSON.stringify({ ...payload, tools: rows }, null, 2) + '\n');
+if (errors.length) { console.error(JSON.stringify(errors, null, 2)); throw new Error(`API_ROUTE_AUDIT_FAILED:${errors.length}`); }
+const output = JSON.stringify(rows, null, 2) + '\n';
+if (process.argv.includes('--check')) {
+  if (original !== output) throw new Error('Карта разошлась с определениями: выполните sync-route-map.mjs');
+} else writeFileSync(routeFile, output);
+console.log(`API route audit: ${payload.checkedApiTools} API tools, ${rows.length} variants; missing 0`);

package/scripts/sync-schema-descriptions.mjs

@@ -0,0 +1,25 @@
+// Обновляем только описания совпадающих узлов JSON Schema. Ограничения каталога,
+// в том числе ручные allOf для superRefine, не заменяются выводом Zod.
+export function syncSchemaDescriptions(target, derived) {
+  if (!target || !derived || typeof target !== 'object' || typeof derived !== 'object') return;
+  if (typeof derived.description === 'string') target.description = derived.description;
+
+  for (const keyword of ['properties', 'patternProperties', '$defs', 'definitions', 'dependentSchemas']) {
+    for (const name of Object.keys(target[keyword] ?? {})) {
+      syncSchemaDescriptions(target[keyword][name], derived[keyword]?.[name]);
+    }
+  }
+  for (const keyword of [
+    'items', 'additionalProperties', 'additionalItems', 'contains', 'propertyNames',
+    'not', 'if', 'then', 'else', 'unevaluatedProperties', 'unevaluatedItems',
+  ]) {
+    if (!Array.isArray(target[keyword]) && !Array.isArray(derived[keyword])) {
+      syncSchemaDescriptions(target[keyword], derived[keyword]);
+    }
+  }
+  for (const keyword of ['items', 'prefixItems', 'allOf', 'anyOf', 'oneOf']) {
+    if (Array.isArray(target[keyword]) && Array.isArray(derived[keyword])) {
+      target[keyword].forEach((schema, index) => syncSchemaDescriptions(schema, derived[keyword][index]));
+    }
+  }
+}

package/scripts/sync-tool-inventory.mjs

@@ -0,0 +1,27 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import ts from 'typescript';
+
+const source = readFileSync(new URL('../src/tools/inventory.ts', import.meta.url), 'utf8');
+const compiled = ts.transpileModule(source, {
+  compilerOptions: { module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2022 },
+}).outputText;
+const { renderToolInventoryMarkdown, toolInventoryCounts } = await import(
+  'data:text/javascript;base64,' + Buffer.from(compiled).toString('base64')
+);
+const schemaUrl = new URL('../src/schemas/mcp-tools.json', import.meta.url);
+const schema = JSON.parse(readFileSync(schemaUrl, 'utf8'));
+const names = schema.tools.filter((tool) => tool.status !== 'removed').map((tool) => tool.name);
+schema.summary.total_tools = names.length;
+schema.summary.tools_by_category = toolInventoryCounts(names);
+writeFileSync(schemaUrl, JSON.stringify(schema, null, 2) + '\n');
+const readmeUrl = new URL('../README.md', import.meta.url);
+const readme = readFileSync(readmeUrl, 'utf8');
+const begin = '<!-- BEGIN GENERATED TOOL INVENTORY -->';
+const end = '<!-- END GENERATED TOOL INVENTORY -->';
+const first = readme.indexOf(begin), last = readme.indexOf(end);
+if (first < 0 || last < first) throw new Error('README inventory markers missing');
+writeFileSync(
+  readmeUrl,
+  readme.slice(0, first + begin.length) + '\n\n' +
+  renderToolInventoryMarkdown(names) + '\n\n' + readme.slice(last),
+);