@besales/mcp 1.0.0-beta.5 → 1.0.0-beta.9

package/scripts/sync-agent-model-schemas.mjs

@@ -1,10 +1,11 @@
+import { writeGeneratedFile } from './generated-output.mjs';
 // Выпуск схемы нового каталога и подсказок из исполняемых определений, без копии списка моделей.
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { z } from 'zod';
-import { agentModelTools } from '../dist/tools/definitions/agent-models.js';
-import { agentSettingsTools } from '../dist/tools/definitions/agent-settings.js';
+import { agentModelTools } from '../src/tools/definitions/agent-models.js';
+import { agentSettingsTools } from '../src/tools/definitions/agent-settings.js';
 
-import { renderToolInventoryMarkdown, toolInventoryCounts } from '../dist/tools/inventory.js';
+import { renderToolInventoryMarkdown, toolInventoryCounts } from '../src/tools/inventory.js';
 
 const target = new URL('../src/schemas/mcp-tools.json', import.meta.url);
 const registry = JSON.parse(readFileSync(target, 'utf8'));
@@ -36,7 +37,7 @@ registry.summary.total_tools = names.length;
 registry.summary.tools_by_category = toolInventoryCounts(names);
 const readmePath = new URL('../README.md', import.meta.url);
 const readme = readFileSync(readmePath, 'utf8');
-writeFileSync(
+writeGeneratedFile(
   readmePath,
   readme.replace(
     /(<!-- BEGIN GENERATED TOOL INVENTORY -->)[\s\S]*?(<!-- END GENERATED TOOL INVENTORY -->)/u,
@@ -56,17 +57,16 @@ const route = {
   canonicalArgs: args,
   expected: {
     method: request.method,
-    pathTemplate: url.pathname.replace(args.workspace_id, ':workspaceId'),
     path: url.pathname,
+    pathTemplate: url.pathname.replace(args.workspace_id, ':workspaceId'),
     query: Object.fromEntries(url.searchParams),
   },
 };
 const previousRoute = routeMap.findIndex((item) => item.tool === definition.name);
 if (previousRoute === -1) routeMap.push(route);
-else routeMap[previousRoute] = route;
-writeFileSync(routeMapPath, JSON.stringify(routeMap, null, 2) + '\n');
+// Прочие поля строки (backendTarget) ставит sync-api-contracts — не стирать их, иначе выпуски по очереди меняют файл.
+else routeMap[previousRoute] = { ...routeMap[previousRoute], ...route };
+writeGeneratedFile(routeMapPath, JSON.stringify(routeMap, null, 2) + '\n');
 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);
+writeGeneratedFile(target, serialized);
 console.log('Схемы каталога моделей агента и подсказки выпущены');

package/scripts/sync-api-contracts.mjs

@@ -1,10 +1,13 @@
 // Локальный выпуск по явному API checkout: API и Git-индекс остаются только входами.
 import { execFileSync } from 'node:child_process';
-import { shippedRef } from './shipped-ref.mjs';
-import { copyFileSync, readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
+import openapiTS, { astToString, COMMENT_HEADER } from 'openapi-typescript';
+import { pathToFileURL } from 'node:url';
+import { writeGeneratedFile } from './generated-output.mjs';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
+import { shippedRef } from './shipped-ref.mjs';
 import { diffRegistries, lagKey } from './registry-diff.mjs';
 import { syncSchemaDescriptions } from './sync-schema-descriptions.mjs';
 
@@ -14,14 +17,26 @@ if (!contracts) throw new Error('BESALES_API_CONTRACTS_DIR обязателен:
 const apiFile = resolve(contracts, 'openapi-besales-api.yaml');
 const apiText = readFileSync(apiFile, 'utf8');
 if (/^(?:<<<<<<<|=======|>>>>>>>)/mu.test(apiText)) throw new Error('OPENAPI_MERGE_CONFLICT');
-const run = (args) => execFileSync('yarn', args, { cwd: root, stdio: 'inherit' });
-run(['exec', 'openapi-typescript', apiFile, '-o', 'src/types/api-contract.gen.ts']);
-run(['build']);
+const types = COMMENT_HEADER + astToString(await openapiTS(pathToFileURL(apiFile)));
+writeGeneratedFile(new URL('../src/types/api-contract.gen.ts', import.meta.url), types);
 if (process.argv.includes('--types-only')) process.exit(0);
-for (const script of ['schemas:sync:trigger-arguments', 'schemas:sync:crm-stage-pool', 'schemas:sync:wave-ids', 'schemas:sync:agent-models']) run([script]);
-for (const script of ['sync-contract-ledger-schemas.mjs', 'generate-followup-session-contract.mjs']) execFileSync(process.execPath, [resolve(root, 'scripts', script)], { cwd: root, stdio: 'inherit' });
-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));
+process.env.BESALES_MCP_SCHEMA_SOURCE = '1';
+const check = process.argv.includes('--check') ? ['--check'] : [];
+const run = (script) =>
+  execFileSync(
+    process.execPath,
+    [...process.execArgv, resolve(root, 'scripts', script), ...check],
+    { cwd: root, stdio: 'inherit' },
+  );
+for (const script of [
+  'sync-trigger-argument-schema.mjs',
+  'sync-wave-id-schemas.mjs',
+  'sync-agent-model-schemas.mjs',
+  'sync-contract-ledger-schemas.mjs',
+  'generate-followup-session-contract.mjs',
+])
+  run(script);
+const { toolDefinitions } = await import('../src/tools/definitions.ts');
 const registryPath = new URL('../src/schemas/mcp-tools.json', import.meta.url);
 const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
 const known = new Map(registry.tools.map((tool) => [tool.name, tool]));
@@ -29,57 +44,101 @@ registry.tools = toolDefinitions.map((definition) => {
   const tool = known.get(definition.name);
   if (!tool) throw new Error(`REGISTRY_TOOL_MISSING:${definition.name}`);
   // Сохранённые ID областей знаний теперь не обязаны быть UUID.
-  const derived = z.toJSONSchema(definition.schema, { io: 'input', unrepresentable: 'any' });
-  if (derived.properties?.knowledge_space_id) tool.inputSchema.properties.knowledge_space_id = derived.properties.knowledge_space_id;
-  if (definition.name === 'besales_followup_sequence_upsert' && !tool.inputSchema.properties.config.properties.steps) {
-    const baseline = JSON.parse(execFileSync('git', ['show', 'HEAD:src/schemas/mcp-tools.json'], { encoding: 'utf8' }));
-    const config = baseline.tools.find((entry) => entry.name === definition.name).inputSchema.properties.config;
-    const current = tool.inputSchema.properties.config;
-    tool.inputSchema.properties.config = { ...config, properties: { ...config.properties, ...current.properties } };
-  }
+  const derived = z.toJSONSchema(definition.schema, {
+    io: 'input',
+    unrepresentable: 'any',
+  });
+  if (derived.properties?.knowledge_space_id)
+    tool.inputSchema.properties.knowledge_space_id = derived.properties.knowledge_space_id;
   syncSchemaDescriptions(tool.inputSchema, derived);
   return tool;
 });
-const { reactivationConfigSchema } = await import('../dist/tools/definitions/follow-up-config.js');
+const { reactivationConfigSchema } = await import('../src/tools/definitions/follow-up-config.ts');
 const chain = registry.tools.find((tool) => tool.name === 'besales_followup_sequence_upsert');
-const reactivation = z.toJSONSchema(reactivationConfigSchema, { io: 'input', unrepresentable: 'any' });
+const reactivation = z.toJSONSchema(reactivationConfigSchema, {
+  io: 'input',
+  unrepresentable: 'any',
+});
 function syncEnums(target, derived) {
   if (!target || !derived || typeof target !== 'object' || typeof derived !== 'object') return;
   if (derived.enum) target.enum = derived.enum;
   for (const key of Object.keys(target)) syncEnums(target[key], derived[key]);
 }
 syncEnums(chain.inputSchema.properties.config, reactivation);
-for (const field of ['sessionTimeVariable', 'sessionDayOffsets', 'sessionDurationMinutes']) chain.inputSchema.properties.config.properties[field] = reactivation.properties[field];
-if (!chain.description.includes('45 минут')) chain.description += ' Окно календарного шага по умолчанию 45 минут; серия эфиров задаётся sessionTimeVariable/sessionDayOffsets/sessionDurationMinutes.';
+for (const field of ['sessionTimeVariable', 'sessionDayOffsets', 'sessionDurationMinutes'])
+  chain.inputSchema.properties.config.properties[field] = reactivation.properties[field];
+if (!chain.description.includes('45 минут'))
+  chain.description +=
+    ' Окно календарного шага по умолчанию 45 минут; серия эфиров задаётся sessionTimeVariable/sessionDayOffsets/sessionDurationMinutes.';
 const inbound = registry.tools.find((tool) => tool.name === 'besales_inbound_analytics_get');
-const baselineRegistry = JSON.parse(execFileSync('git', ['show', 'HEAD:src/schemas/mcp-tools.json'], { encoding: 'utf8' }));
-const description = baselineRegistry.tools.find((tool) => tool.name === inbound.name).description;
+const description = inbound.description;
 const inboundDefinition = toolDefinitions.find((tool) => tool.name === inbound.name);
-const instructions = inboundDefinition.enhanceResponse({}, { report: 'money' }).instructions.split('\n');
+const instructions = inboundDefinition
+  .enhanceResponse({}, { report: 'money' })
+  .instructions.split('\n');
 const moneyInstructions = instructions.find((line) => line.startsWith('Деньги.'));
 if (!moneyInstructions) throw new Error('INBOUND_APPLICATION_DESCRIPTION_MISSING');
-const currentDescription = description.replace('(speed/cycle/quality) ещё не построены: отказ маршрута не означает отсутствие данных.', 'speed, cycle, quality также построены.');
-inbound.description = currentDescription.includes(moneyInstructions) ? currentDescription : currentDescription + ' ' + moneyInstructions;
-writeFileSync(registryPath, JSON.stringify(registry, null, 2) + '\n');
-run(['schemas:sync:crm-stage-pool']);
-execFileSync(process.execPath, [resolve(root, 'scripts/sync-route-map.mjs')], { cwd: root, stdio: 'inherit' });
-const rows = JSON.parse(readFileSync(new URL('../src/schemas/mcp-v2-route-map.json', import.meta.url), 'utf8'));
-// Построенные адреса не должны оставаться объявленным долгом.
+const currentDescription = description.replace(
+  '(speed/cycle/quality) ещё не построены: отказ маршрута не означает отсутствие данных.',
+  'speed, cycle, quality также построены.',
+);
+inbound.description = currentDescription.includes(moneyInstructions)
+  ? currentDescription
+  : currentDescription + ' ' + moneyInstructions;
+writeGeneratedFile(registryPath, JSON.stringify(registry, null, 2) + '\n');
+// Специализированные схемы накладываются в одном и том же порядке на каждом выпуске.
+for (const script of [
+  'sync-crm-stage-pool-schema.mjs',
+  'sync-trigger-event-schema.mjs',
+  'sync-trigger-step-reference-schema.mjs',
+  'sync-sandbox-request-key.mjs',
+  'sync-telegram-profile-photo.mjs',
+  'sync-tool-inventory.mjs',
+  'sync-route-map.mjs',
+])
+  run(script);
+
+// Обновление долга использует закреплённые входы; отгруженный реф остаётся эталоном в полном checkout.
+const rows = JSON.parse(
+  readFileSync(new URL('../src/schemas/mcp-v2-route-map.json', import.meta.url), 'utf8'),
+);
 const lagFile = new URL('../src/schemas/shipped-lag.json', import.meta.url);
 const lag = JSON.parse(readFileSync(lagFile, 'utf8'));
 for (const row of rows) if (lag.routeLag?.[row.tool]) delete lag.routeLag[row.tool];
-const shipped = JSON.parse(execFileSync('git', ['show', `${shippedRef()}:src/schemas/mcp-tools.json`], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 }));
+let shippedTools;
+if (process.env.BESALES_API_CONTRACTS_ONLY === '1') {
+  const exported = JSON.parse(readFileSync(resolve(contracts, 'mcp-tool-routes.json'), 'utf8'));
+  shippedTools = Object.entries(exported.shippedInputSchemas).map(([name, inputSchema]) => ({
+    name,
+    inputSchema,
+  }));
+  if (shippedTools.length !== exported.shippedRegistry.toolCount)
+    throw new Error('SHIPPED_CONTRACT_EXPORT_INCOMPLETE');
+} else
+  shippedTools = JSON.parse(
+    execFileSync('git', ['show', shippedRef() + ':src/schemas/mcp-tools.json'], {
+      cwd: root,
+      encoding: 'utf8',
+      maxBuffer: 16 * 1024 * 1024,
+    }),
+  ).tools;
 const finalRegistry = JSON.parse(readFileSync(registryPath, 'utf8'));
-const delta = diffRegistries(shipped.tools, finalRegistry.tools, lag.toolSuccessors);
+const delta = diffRegistries(shippedTools, finalRegistry.tools, lag.toolSuccessors);
 const activeKeys = new Set(delta.contractLag.map(lagKey));
 for (const [key] of Object.entries(lag.contractLag)) {
-  if (!activeKeys.has(key) && (key.includes('instagram_comment_templates') || key.includes('::personal_url_variable::'))) delete lag.contractLag[key];
+  if (
+    !activeKeys.has(key) &&
+    (key.includes('instagram_comment_templates') || key.includes('::personal_url_variable::'))
+  )
+    delete lag.contractLag[key];
 }
 for (const entry of delta.contractLag) {
-  if (entry.path === 'knowledge_space_id#pattern' && !lag.contractLag[lagKey(entry)]) lag.contractLag[lagKey(entry)] = {
-    owner: 'DELIBERATE', severity: 'DELIBERATE', reason: 'Сохранённые идентификаторы области знаний проверяются по структурной форме UUID без требований к версии и варианту; значение передаётся неизменным (night-spaceid).',
-  };
+  if (entry.path === 'knowledge_space_id#pattern' && !lag.contractLag[lagKey(entry)])
+    lag.contractLag[lagKey(entry)] = {
+      owner: 'DELIBERATE',
+      severity: 'DELIBERATE',
+      reason:
+        'Сохранённые идентификаторы области знаний проверяются по структурной форме UUID без требований к версии и варианту; значение передаётся неизменным (night-spaceid).',
+    };
 }
-writeFileSync(lagFile, JSON.stringify(lag, null, 2) + '\n');
-execFileSync(process.execPath, [resolve(root, 'scripts/sync-tool-inventory.mjs')], { cwd: root, stdio: 'inherit' });
-run(['build']);
+writeGeneratedFile(lagFile, JSON.stringify(lag, null, 2) + '\n');

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

@@ -1,4 +1,5 @@
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { writeGeneratedFile } from './generated-output.mjs';
+import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import openapiTS from 'openapi-typescript';
@@ -6,12 +7,12 @@ import { z } from 'zod';
 import {
   triggerActionItemSchema,
   followupSequenceConfigSchema,
-} from '../dist/tools/definitions/platform-setup.js';
+} from '../src/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';
+} from '../src/tools/definitions/crm-stage-pool.schema.js';
+import { CRM_STAGE_ACTION_POOL_MAX_SIZE } from '../src/shared/constants/crm-stage-pool.constants.js';
 
 // Каталог ссылки берётся из принятого API. Отставание соседних полей этим выпуском не снимается.
 const contractsDir = process.env.BESALES_API_CONTRACTS_DIR?.trim() || '../besales-api/contracts';
@@ -80,6 +81,4 @@ 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);
+writeGeneratedFile(target, serialized);

package/scripts/sync-route-map.mjs

@@ -1,51 +1,156 @@
 // Пересобирает только карту и локальные доказательства маршрутов; API остаётся входом.
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
+import { load } from 'js-yaml';
 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 { toolDefinitions } = await import('../src/tools/definitions.js');
+const { mappingCases } = await import('../src/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;
+  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));
+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 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' }));
+let privatePath;
+let privateEvidence;
+if (process.env.BESALES_API_CONTRACTS_ONLY === '1') {
+  // Явный режим закреплённого снимка: это доказательство из экспортов, а не проверка Nest.
+  const exported = JSON.parse(readFileSync(resolve(contracts, 'mcp-tool-routes.json'), 'utf8'));
+  const exportedRows = JSON.parse(
+    readFileSync(resolve(contracts, 'mcp-v2-route-map.json'), 'utf8'),
+  );
+  const tool = exported.tools.find((row) => row.name === 'besales_crm_webhook_url_reveal');
+  const route = exportedRows.find((row) => row.tool === 'besales_crm_webhook_url_reveal');
+  if (
+    tool?.kind !== 'api' ||
+    tool.method !== 'POST' ||
+    tool.samplePath !== '/crm-webhook-url-reveals' ||
+    route?.expected.method !== tool.method ||
+    route.expected.pathTemplate !== tool.samplePath
+  )
+    throw new Error('PRIVATE_CRM_CONTRACT_MISSING');
+  privatePath = '/api/v2' + tool.samplePath;
+  privateEvidence = {
+    source: 'pinned-contract-export',
+    file: resolve(contracts, 'mcp-tool-routes.json'),
+  };
+} else {
+  if (!existsSync(privateController) || !existsSync(privateModule))
+    throw new Error(
+      'PRIVATE_CRM_SOURCE_MISSING: use BESALES_API_CONTRACTS_ONLY=1 only with pinned exports',
+    );
+  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');
+  privatePath = '/api/v2/' + controller[1];
+  privateEvidence = {
+    source: 'controller',
+    controller: privateController,
+    sha256: createHash('sha256').update(controllerSource).digest('hex'),
+  };
+}
+paths.push({
+  path: privatePath,
+  methods: new Set(['POST']),
+  regex: new RegExp('^' + privatePath + '$'),
+  private: true,
+});
+// Setup-сессии и смена прокси скрыты из публичного описания как носители секретов.
+// Их существование проверяется по app-контракту того же закреплённого ядра.
+const customerTools = new Set([
+  'besales_platform_telegram_personal_proxy_import_link',
+  'besales_platform_telegram_personal_proxy_import_status',
+  'besales_platform_telegram_personal_account_proxy_change',
+  'besales_platform_telegram_personal_proxy_stock_import_link',
+  'besales_platform_telegram_personal_proxy_stock_import_status',
+  'besales_platform_telegram_personal_connect_link',
+  'besales_platform_telegram_personal_session_import_link',
+]);
+const appFile = resolve(contracts, 'openapi-app.yaml');
+const appText = readFileSync(appFile, 'utf8');
+if (/^(?:<<<<<<<|=======|>>>>>>>)/mu.test(appText)) throw new Error('APP_OPENAPI_MERGE_CONFLICT');
+const appPaths = Object.entries(load(appText).paths).map(([path, item]) => ({
+  path,
+  methods: new Set(Object.keys(item).map((method) => method.toUpperCase())),
+  regex: new RegExp(
+    '^' +
+      path
+        .split('/')
+        .map((part) =>
+          part.startsWith('{') ? '[^/]+' : part.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&'),
+        )
+        .join('/') +
+      '$',
+  ),
+  private: true,
+}));
+const initialRows = JSON.parse(original);
 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;
+  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);
+  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) {
@@ -55,40 +160,89 @@ for (const row of rows) {
     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));
+    const candidates = customerTools.has(definition.name) ? [...paths, ...appPaths] : paths;
+    const route = candidates.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') };
+    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() };
+        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';
+    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) }); }
+    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);
+const artifactDir = new URL('../.codex-artifacts-prBETA9ASM/', 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 };
+const payload = {
+  privateRoutes: [{ method: 'POST', path: privatePath, ...privateEvidence }],
+  source: 'working-tree',
+  apiOpenApi: apiFile,
+  apiSha256: createHash('sha256').update(apiText).digest('hex'),
+  appOpenApi: appFile,
+  appSha256: createHash('sha256').update(appText).digest('hex'),
+  apiHead: execFileSync('git', ['-C', contracts, 'log', '-1', '--format=%H'], {
+    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}`); }
+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');
+  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`);
+console.log(
+  `API route audit: ${payload.checkedApiTools} API tools, ${rows.length} variants; missing 0`,
+);

package/scripts/sync-sandbox-request-key.mjs

@@ -0,0 +1,40 @@
+// node --loader ./src/utils/setup-sessions-loader.mjs scripts/sync-sandbox-request-key.mjs [--check]
+// Узкий выпуск из исходников: существующие поля и метаданные реестра остаются на месте.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { z } from 'zod';
+import { agentDesignTools } from '../src/tools/definitions/agent-design.js';
+
+const name = 'besales_sandbox_run_start';
+const definition = agentDesignTools.find((tool) => tool.name === name);
+if (!definition?.createRequest) throw new Error('SANDBOX_DEFINITION_MISSING');
+const registryFile = new URL('../src/schemas/mcp-tools.json', import.meta.url);
+const routesFile = new URL('../src/schemas/mcp-v2-route-map.json', import.meta.url);
+const registry = JSON.parse(readFileSync(registryFile, 'utf8'));
+const routes = JSON.parse(readFileSync(routesFile, 'utf8'));
+const contract = registry.tools.find((tool) => tool.name === name);
+const route = routes.find((entry) => entry.tool === name);
+if (!contract || !route) throw new Error('SANDBOX_CONTRACT_MISSING');
+const derived = z.toJSONSchema(definition.schema, {
+  target: 'draft-7',
+  io: 'input',
+});
+contract.inputSchema.properties.request_key = derived.properties.request_key;
+route.canonicalArgs.request_key = '00000000-0000-4000-8000-000000000090';
+const input = definition.schema.parse(route.canonicalArgs);
+route.expected.body = definition.createRequest(input).body;
+const note = definition
+  .enhanceResponse({}, input)
+  .instructions.split('\n')
+  .find((line) => line.startsWith('Сохрани request_key.'));
+if (!note) throw new Error('SANDBOX_KEY_INSTRUCTIONS_MISSING');
+contract.description = contract.description.replace(/ Сохрани request_key\..*$/u, '') + ' ' + note;
+for (const [file, value] of [
+  [registryFile, registry],
+  [routesFile, routes],
+]) {
+  const output = JSON.stringify(value, null, 2) + '\n';
+  if (process.argv.includes('--check')) {
+    if (readFileSync(file, 'utf8') !== output)
+      throw new Error('SANDBOX_KEY_CONTRACT_DRIFT: ' + file.pathname);
+  } else writeFileSync(file, output);
+}