@besales/mcp 0.48.0 → 1.0.0-beta.2

package/scripts/shipped-sample.spec.mjs

@@ -0,0 +1,451 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+
+import { lagKey, reconcileWithRegistry } from './registry-diff.mjs';
+import { sample } from './sample-args.mjs';
+import {
+  buildShippedSample,
+  filterOf,
+  generatedRoots,
+  normalizeIssuePath,
+  routeShape,
+  schemaLagExplains,
+  schemaPathsOf,
+} from './shipped-sample.mjs';
+
+/**
+ * Образец отгруженного вызова: тесты держат не «что-то собралось», а различия, ради которых механизм написан, —
+ * законный вызов вместо полного набора полей, отказ ветки v2 не прячется снятием, объявление отказа сверяется в обе
+ * стороны, и снятие строки при живом отказе краснит сверку.
+ */
+const WS = '00000000-0000-4000-8000-0000000000ff';
+
+function definition(schema, createRequest) {
+  return { schema, createRequest, defaultWorkspaceId: false };
+}
+
+/** Обе стороны схемы — JSON для путей и ограничений, как у реестров. */
+function jsonSchema(properties, required = []) {
+  return { type: 'object', properties, required };
+}
+
+function run({ shipped, v2, shippedJson, v2Json, known, full, schemaLag = [], goodValues = () => [] }) {
+  const shippedConstraints = schemaPathsOf(shippedJson, 'отгруженный');
+  const v2Constraints = schemaPathsOf(v2Json, 'v2');
+  return buildShippedSample({
+    full,
+    known,
+    acceptShipped: filterOf(shipped, WS),
+    acceptV2: filterOf(v2, WS),
+    explains: (path, args) => schemaLagExplains(path, args, schemaLag, v2Constraints),
+    shippedConstraints,
+    goodValues,
+    mainRouteShape: 'POST /things',
+  });
+}
+
+const post = (input) => ({ method: 'POST', path: '/things', body: input });
+
+describe('образец отгруженного вызова', () => {
+  it('взаимоисключение у обоих: основной образец без добавленного генератором поля и альтернатива с ним', () => {
+    const exclusive = z
+      .object({ file_id: z.string().optional(), url: z.string().optional() })
+      .strict()
+      .refine((value) => (value.file_id === undefined) !== (value.url === undefined), { message: 'одно из двух' });
+    const json = jsonSchema({ file_id: { type: 'string' }, url: { type: 'string' } });
+
+    const actual = run({
+      shipped: definition(exclusive, post),
+      v2: definition(exclusive, post),
+      shippedJson: json,
+      v2Json: json,
+      known: { file_id: 'f' },
+      full: { file_id: 'f', url: 'x' },
+    });
+
+    expect(actual.request.body).toEqual({ file_id: 'f' });
+    expect(actual.alternatives).toEqual([
+      expect.objectContaining({ forPath: 'url', request: expect.objectContaining({ body: { url: 'x' } }) }),
+    ]);
+    expect(actual.omitted).toEqual([]);
+  });
+
+  it('четыре снятых поля сверяются отдельно при другом законном значении отчёта', () => {
+    const report = z
+      .object({ report: z.enum(['a', 'b']), p1: z.number().optional(), p2: z.number().optional(), p3: z.number().optional(), p4: z.number().optional() })
+      .strict()
+      .superRefine((value, ctx) => {
+        if (value.report === 'a') {
+          for (const key of ['p1', 'p2', 'p3', 'p4']) {
+            if (value[key] !== undefined) ctx.addIssue({ code: 'custom', path: ['report'], message: 'не для a' });
+          }
+        }
+      });
+    const json = jsonSchema({
+      report: { type: 'string', enum: ['a', 'b'] },
+      p1: { type: 'integer' },
+      p2: { type: 'integer' },
+      p3: { type: 'integer' },
+      p4: { type: 'integer' },
+    });
+
+    const actual = run({
+      shipped: definition(report, post),
+      v2: definition(report, post),
+      shippedJson: json,
+      v2Json: json,
+      known: { report: 'a' },
+      full: { report: 'a', p1: 4, p2: 4, p3: 4, p4: 4 },
+    });
+
+    expect(actual.request.body).toEqual({ report: 'a' });
+    expect(actual.omitted).toEqual([]);
+    expect(actual.alternatives.map(({ forPath }) => forPath)).toEqual(['p1', 'p2', 'p3', 'p4']);
+    expect(actual.alternatives.every(({ request }) => request.body.report === 'b')).toBe(true);
+  });
+
+  it('пять полей, законных лишь вместе, сохраняются, если полный набор законен', () => {
+    const keys = ['a', 'b', 'c', 'd', 'e'];
+    const schema = z.object(Object.fromEntries(keys.map((key) => [key, z.string().optional()])))
+      .strict().refine((value) => keys.every((key) => value[key] === undefined)
+        || keys.every((key) => value[key] !== undefined), { path: ['a'] });
+    const json = jsonSchema(Object.fromEntries(keys.map((key) => [key, { type: 'string' }])));
+    const actual = run({ shipped: definition(schema, post), v2: definition(schema, post),
+      shippedJson: json, v2Json: json, known: {},
+      full: Object.fromEntries(keys.map((key) => [key, key])) });
+    expect(actual.request.body).toEqual(Object.fromEntries(keys.map((key) => [key, key])));
+    expect(actual.omitted).toEqual([]);
+  });
+
+  it('предел перебора назван, если пять связанных полей конфликтуют с проверенным полем', () => {
+    const keys = ['a', 'b', 'c', 'd', 'e'];
+    const schema = z.object({ block: z.string().optional(),
+      ...Object.fromEntries(keys.map((key) => [key, z.string().optional()])) })
+      .strict().refine((value) => {
+        const count = keys.filter((key) => value[key] !== undefined).length;
+        return (count === 0 || count === keys.length) && (value.block === undefined || count === 0);
+      }, { path: ['block'] });
+    const json = jsonSchema({ block: { type: 'string' },
+      ...Object.fromEntries(keys.map((key) => [key, { type: 'string' }])) });
+    const actual = run({ shipped: definition(schema, post), v2: definition(schema, post),
+      shippedJson: json, v2Json: json, known: { block: 'да' },
+      full: { block: 'да', ...Object.fromEntries(keys.map((key) => [key, key])) } });
+    expect(actual.request.body).toEqual({ block: 'да' });
+    expect(actual.omitted.map(({ path, why }) => [path, why])).toEqual(
+      keys.map((key) => [key, 'SEARCH_LIMIT_EXCEEDED']),
+    );
+    expect(actual.omitted.every(({ message }) => message.includes('Проверить нельзя'))).toBe(true);
+  });
+
+  it('предел снятия полей делает невозможность образца явной', () => {
+    const keys = ['p1', 'p2', 'p3', 'p4', 'p5'];
+    const schema = z.object({ mode: z.string(),
+      ...Object.fromEntries(keys.map((key) => [key, z.string().optional()])) })
+      .strict().refine((value) => value.p1 !== undefined
+        && keys.slice(1).every((key) => value[key] === undefined));
+    const json = jsonSchema({ mode: { type: 'string' },
+      ...Object.fromEntries(keys.map((key) => [key, { type: 'string' }])) });
+    const actual = run({ shipped: definition(schema, post), v2: definition(schema, post),
+      shippedJson: json, v2Json: json, known: { mode: 'x' },
+      full: { mode: 'x', ...Object.fromEntries(keys.map((key) => [key, key])) } });
+    expect(actual.impossible).toMatchObject({ reason: 'SHIPPED_COMBINATION_LIMIT' });
+    expect(actual.impossible.message).toContain('Проверить нельзя');
+  });
+
+  it('два необязательных поля, законных только вместе, возвращаются в один образец', () => {
+    const shipped = z.object({ a: z.string().optional(), b: z.string().optional() }).strict()
+      .refine((v) => (v.a === undefined) === (v.b === undefined), { path: ['a'] });
+    const json = jsonSchema({ a: { type: 'string' }, b: { type: 'string' } });
+    const actual = run({ shipped: definition(shipped, post), v2: definition(shipped, post),
+      shippedJson: json, v2Json: json, known: {}, full: { a: 'а', b: 'б' } });
+    expect(actual.request.body).toEqual({ a: 'а', b: 'б' });
+    expect(actual.omitted).toEqual([]);
+  });
+
+  it('широкий отчёт строит отдельный законный вызов для поля другого маршрута', () => {
+    const schema = z.object({
+      report: z.enum(['summary', 'payment']),
+      mode: z.enum(['all', 'range']).optional(),
+      payment_view: z.string().optional(),
+    }).strict().superRefine((value, context) => {
+      if (value.report === 'summary' && value.payment_view !== undefined) {
+        context.addIssue({ code: 'custom', path: ['payment_view'], message: 'не для summary' });
+      }
+      if (value.report === 'payment' && value.mode !== undefined) {
+        context.addIssue({ code: 'custom', path: ['report'], message: 'mode не для payment' });
+      }
+    });
+    const request = (input) => ({ method: 'POST',
+      path: input.report === 'payment' ? '/payments' : '/things', body: input });
+    const json = jsonSchema({
+      report: { type: 'string', enum: ['summary', 'payment'] },
+      mode: { type: 'string', enum: ['all', 'range'] },
+      payment_view: { type: 'string' },
+    }, ['report']);
+    const actual = run({ shipped: definition(schema, request), v2: definition(schema, request),
+      shippedJson: json, v2Json: json, known: { report: 'summary', mode: 'all' },
+      full: { report: 'summary', mode: 'all', payment_view: 'decidable' } });
+    expect(actual.request.path).toBe('/things');
+    expect(actual.omitted).toEqual([]);
+    expect(actual.alternatives).toContainEqual(expect.objectContaining({
+      forPath: 'payment_view',
+      request: expect.objectContaining({ path: '/payments', body: { report: 'payment', payment_view: 'decidable' } }),
+    }));
+  });
+
+  it('массив id берёт UUID соседнего одиночного id, если JSON-схема обещает лишь string', () => {
+    const schema = z.object({
+      segment_id: z.string().uuid(),
+      skip_after_segment_ids: z.array(z.string().uuid()).optional(),
+    }).strict();
+    const json = jsonSchema({
+      segment_id: { type: 'string', format: 'uuid' },
+      skip_after_segment_ids: { type: 'array', items: { type: 'string' } },
+    }, ['segment_id']);
+    const id = '00000000-0000-4000-8000-000000000003';
+    const actual = run({ shipped: definition(schema, post), v2: definition(schema, post),
+      shippedJson: json, v2Json: json, known: { segment_id: id },
+      full: { segment_id: id, skip_after_segment_ids: ['x'] } });
+    expect(actual.alternatives).toContainEqual(expect.objectContaining({
+      forPath: 'skip_after_segment_ids',
+      request: expect.objectContaining({ body: {
+        segment_id: id, skip_after_segment_ids: [id],
+      } }),
+    }));
+    expect(actual.omitted).toEqual([]);
+  });
+
+  it('законная отгруженная альтернатива, которую v2 отвергает за отсутствие A, видна как расхождение', () => {
+    const shipped = z.object({ a: z.string().optional(), p: z.string().optional() }).strict()
+      .refine((v) => (v.a === undefined) !== (v.p === undefined), { path: ['a'] });
+    const v2 = z.object({ a: z.string(), p: z.string().optional() }).strict();
+    const json = jsonSchema({ a: { type: 'string' }, p: { type: 'string' } });
+    const actual = run({ shipped: definition(shipped, post), v2: definition(v2, post),
+      shippedJson: json, v2Json: json, known: { a: 'а' }, full: { a: 'а', p: 'п' } });
+    expect(actual.absentKnown).toContain('a');
+    expect(actual.omitted).not.toContainEqual({ path: 'p', why: 'SHIPPED_FORBIDS' });
+  });
+
+  it('альтернатива сохраняет корень и снимает только негодный вложенный лист', () => {
+    const shipped = z.object({ root: z.object({ valid: z.string(), extra: z.string().optional() })
+      .refine((v) => v.extra === undefined, { path: ['extra'] }).optional() }).strict();
+    const json = jsonSchema({ root: { type: 'object', properties: {
+      valid: { type: 'string' }, extra: { type: 'string' },
+    } } });
+    const actual = run({ shipped: definition(shipped, post), v2: definition(shipped, post),
+      shippedJson: json, v2Json: json, known: {}, full: { root: { valid: 'да', extra: 'нет' } } });
+    expect(actual.alternatives).toContainEqual(expect.objectContaining({
+      forPath: 'root', request: expect.objectContaining({ body: { root: { valid: 'да' } } }),
+    }));
+  });
+
+  it('значение переменной проверяется в разрешённой области WORKSPACE', () => {
+    const shipped = z.object({ scope: z.enum(['CHANNEL', 'WORKSPACE']), value: z.string().optional() })
+      .strict().refine((v) => v.value === undefined || v.scope === 'WORKSPACE', { path: ['value'] });
+    const json = jsonSchema({ scope: { type: 'string', enum: ['CHANNEL', 'WORKSPACE'] }, value: { type: 'string' } });
+    const actual = run({ shipped: definition(shipped, post), v2: definition(shipped, post),
+      shippedJson: json, v2Json: json, known: { scope: 'CHANNEL' }, full: { scope: 'CHANNEL', value: 'x' } });
+    expect(actual.alternatives).toContainEqual(expect.objectContaining({
+      forPath: 'value', request: expect.objectContaining({ body: { scope: 'WORKSPACE', value: 'x' } }),
+    }));
+  });
+
+  it('SHIPPED_FORBIDS требует значения, принятого другим вариантом; без него причина VALUE_NOT_FOUND', () => {
+    const shipped = z.object({ mode: z.enum(['a', 'b']), extra: z.string().optional() })
+      .strict().refine((v) => v.mode !== 'a' || v.extra === undefined, { path: ['mode'] });
+    // Значения mode не перечислены в JSON-объявлении: перебор не вправе угадать 'b'.
+    const json = jsonSchema({ mode: { type: 'string' }, extra: { type: 'string' } });
+    const input = { shipped: definition(shipped, post), v2: definition(shipped, post),
+      shippedJson: json, v2Json: json, known: { mode: 'a' }, full: { mode: 'a', extra: 'x' } };
+    expect(run(input).omitted).toContainEqual({ path: 'extra', why: 'VALUE_NOT_FOUND' });
+    expect(run({ ...input, goodValues: () => ['x'] }).omitted)
+      .toContainEqual({ path: 'extra', why: 'SHIPPED_FORBIDS' });
+  });
+
+  it('⛔ v2 строже отгруженного (поле только в своём режиме) — отказ НАЙДЕН, а не спрятан снятием', () => {
+    const shipped = z.object({ mode: z.enum(['all', 'range']), days: z.number().optional() }).strict();
+    const v2 = shipped.superRefine((value, ctx) => {
+      if (value.mode !== 'all' && value.days !== undefined) {
+        ctx.addIssue({ code: 'custom', path: ['days'], message: 'days не относится к режиму' });
+      }
+    });
+    const json = jsonSchema({ mode: { type: 'string', enum: ['all', 'range'] }, days: { type: 'integer' } });
+
+    const actual = run({
+      shipped: definition(shipped, post),
+      v2: definition(v2, post),
+      shippedJson: json,
+      v2Json: json,
+      known: { mode: 'range' },
+      full: { mode: 'range', days: 4 },
+    });
+
+    expect(actual.refused).toEqual([{ path: 'days', message: 'days не относится к режиму' }]);
+    expect(actual.omitted).toEqual([{ path: 'days', why: 'DECLARED' }]);
+  });
+
+  it('отказ, который объясняет сравнение схем (поля нет в v2), наблюдённым отказом не становится', () => {
+    const shipped = z.object({ name: z.string(), legacy: z.string().optional() }).strict();
+    const v2 = z.object({ name: z.string() }).strict();
+
+    const actual = run({
+      shipped: definition(shipped, post),
+      v2: definition(v2, post),
+      shippedJson: jsonSchema({ name: { type: 'string' }, legacy: { type: 'string' } }),
+      v2Json: jsonSchema({ name: { type: 'string' } }),
+      known: { name: 'n' },
+      full: { name: 'n', legacy: 'x' },
+      schemaLag: [{ tool: 't', path: 'legacy', kind: 'MISSING_FIELD' }],
+    });
+
+    expect(actual.refused).toEqual([]);
+    expect(actual.omitted).toEqual([{ path: 'legacy', why: 'DECLARED' }]);
+    expect(actual.request.body).toEqual({ name: 'n' });
+  });
+
+  it('⛔ строка ограничения не объясняет отказ, если значение образца её не нарушает', () => {
+    const shipped = z.object({ size: z.number().optional() }).strict();
+    const v2 = shipped.refine((value) => value.size === undefined, { path: ['size'], message: 'чужой класс отказа' });
+
+    const actual = run({
+      shipped: definition(shipped, post),
+      v2: definition(v2, post),
+      shippedJson: jsonSchema({ size: { type: 'integer', maximum: 100 } }),
+      v2Json: jsonSchema({ size: { type: 'integer', maximum: 50 } }),
+      known: {},
+      full: { size: 4 },
+      schemaLag: [{ tool: 't', path: 'size#maximum', kind: 'CONSTRAINT' }],
+    });
+
+    expect(actual.refused.map((refusal) => refusal.path)).toEqual(['size']);
+  });
+
+  it('отказ ветки v2 БЕЗ пути (исключение конструктора) — находка «перенеси в схему», а не образец', () => {
+    const schema = z.object({ split: z.string().optional() }).strict();
+    const v2 = definition(schema, (input) => {
+      if (input.split !== undefined) throw new Error('split пока не поддерживается');
+      return post(input);
+    });
+
+    const actual = run({
+      shipped: definition(schema, post),
+      v2,
+      shippedJson: jsonSchema({ split: { type: 'string' } }),
+      v2Json: jsonSchema({ split: { type: 'string' } }),
+      known: {},
+      full: { split: 'x' },
+    });
+
+    expect(actual.pathless).toEqual(['split пока не поддерживается']);
+    expect(actual.request).toBeUndefined();
+  });
+
+  it('v2 требует поле, которого у отгруженного нет, — причина V2_REQUIRES_FIELD_UNKNOWN_TO_SHIPPED', () => {
+    const shipped = z.object({ name: z.string() }).strict();
+    const v2 = z.object({ name: z.string(), conversation_id: z.string() }).strict();
+
+    const actual = run({
+      shipped: definition(shipped, post),
+      v2: definition(v2, post),
+      shippedJson: jsonSchema({ name: { type: 'string' } }, ['name']),
+      v2Json: jsonSchema({ name: { type: 'string' }, conversation_id: { type: 'string' } }, ['name', 'conversation_id']),
+      known: { name: 'n' },
+      full: { name: 'n' },
+    });
+
+    expect(actual.impossible).toEqual({ reason: 'V2_REQUIRES_FIELD_UNKNOWN_TO_SHIPPED', paths: ['conversation_id'] });
+  });
+
+  it('поле генератора, переключающее маршрут (идентификатор правки), не входит в основной образец — оно альтернатива', () => {
+    const schema = z.object({ name: z.string(), rule_id: z.string().optional() }).strict();
+    const upsert = (input) =>
+      input.rule_id === undefined
+        ? { method: 'POST', path: '/things', body: input }
+        : { method: 'PATCH', path: `/things/${input.rule_id}`, body: input };
+    const json = jsonSchema({ name: { type: 'string' }, rule_id: { type: 'string' } });
+
+    const actual = run({
+      shipped: definition(schema, upsert),
+      v2: definition(schema, upsert),
+      shippedJson: json,
+      v2Json: json,
+      known: { name: 'n' },
+      full: { name: 'n', rule_id: 'x' },
+    });
+
+    expect(routeShape(actual.request)).toBe('POST /things');
+    expect(actual.alternatives.map((alternative) => [alternative.forPath, routeShape(alternative.request)])).toEqual([
+      ['rule_id', 'PATCH /things/x'],
+    ]);
+  });
+
+  it('проверенное поле, которое отгруженный не принимает в этом варианте, снимается с пометкой, маршрут тот же', () => {
+    const shipped = z
+      .object({ report: z.string(), mode: z.string().optional() })
+      .strict()
+      .refine((value) => value.mode === undefined, { path: ['report'], message: 'mode не для этого отчёта' });
+    const v2 = z.object({ report: z.string(), mode: z.string().optional() }).strict();
+    const json = jsonSchema({ report: { type: 'string' }, mode: { type: 'string' } });
+
+    const actual = run({
+      shipped: definition(shipped, post),
+      v2: definition(v2, post),
+      shippedJson: json,
+      v2Json: json,
+      known: { report: 'catalog', mode: 'all' },
+      full: { report: 'catalog', mode: 'all' },
+    });
+
+    expect(actual.request.body).toEqual({ report: 'catalog' });
+    expect(actual.omitted).toEqual([{ path: 'mode', why: 'SHIPPED_REJECTS_KNOWN' }]);
+  });
+
+  it('⛔ снятие строки #refused при живом отказе краснит сверку; строка без наблюдения — протухшая', () => {
+    const refusal = { tool: 't', path: 'days#refused', kind: 'REFUSED', shipped: 'integer', v2: 'refused' };
+    const found = { missingTools: [], contractLag: [refusal] };
+    const declared = { missingTools: {}, contractLag: { [lagKey(refusal)]: { reason: 'r', owner: 'o', severity: 'DELIBERATE' } } };
+
+    expect(reconcileWithRegistry(found, declared).undeclaredLag).toEqual([]);
+    expect(reconcileWithRegistry(found, { missingTools: {}, contractLag: {} }).undeclaredLag).toEqual([
+      't::days#refused::"integer"→"refused"',
+    ]);
+    expect(reconcileWithRegistry({ missingTools: [], contractLag: [] }, declared).staleLag).toEqual([
+      't::days#refused::"integer"→"refused"',
+    ]);
+  });
+});
+
+describe('помощники путей', () => {
+  it('генератор записи enum создаёт ключ каждого транспорта', () => {
+    expect(sample({ type: 'object', propertyNames: { enum: ['Site', 'MAX'] },
+      additionalProperties: { type: 'string' } })).toEqual({ Site: 'x', MAX: 'x' });
+  });
+  it('путь проблемы zod: индексы массива — [], корень — пустая строка', () => {
+    expect(normalizeIssuePath(['conditions', 0, 'variable_value'])).toBe('conditions[].variable_value');
+    expect(normalizeIssuePath(['tags', 2])).toBe('tags[]');
+    expect(normalizeIssuePath([])).toBe('');
+  });
+
+  it('корни генератора — самый короткий добавленный путь, внутри массива — по первому элементу', () => {
+    expect(
+      generatedRoots(
+        { a: 1, list: [{ keep: 1, extra: 2 }], added: { x: 1 } },
+        { a: 1, list: [{ keep: 1 }] },
+      ),
+    ).toEqual(['list[].extra', 'added']);
+  });
+});
+
+describe('ПГ-5: оригинальный GET отделён от нового POST', () => {
+  it('фильтр отгруженного клиента сохраняет собственный транспорт и query', () => {
+    const schema = z.object({ search: z.string().optional() }).strict();
+    const json = jsonSchema({ search: { type: 'string' } });
+    const actual = run({
+      shipped: definition(schema, (input) => ({ method: 'GET', path: `/things?search=${input.search}` })),
+      v2: definition(schema, post), shippedJson: json, v2Json: json,
+      known: { search: 'pgt-marker' }, full: { search: 'pgt-marker' },
+    });
+    expect(actual.request).toEqual({ method: 'POST', path: '/things', body: { search: 'pgt-marker' } });
+    expect(actual.originalRequest).toEqual({ method: 'GET', path: '/things?search=pgt-marker' });
+  });
+});

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

@@ -0,0 +1,72 @@
+// Выпуск схемы нового каталога и подсказок из исполняемых определений, без копии списка моделей.
+import { mkdirSync, readFileSync, writeFileSync } 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 { renderToolInventoryMarkdown, toolInventoryCounts } from '../dist/tools/inventory.js';
+
+const target = new URL('../src/schemas/mcp-tools.json', import.meta.url);
+const registry = JSON.parse(readFileSync(target, 'utf8'));
+const definition = agentModelTools[0];
+const contract = {
+  name: definition.name,
+  description:
+    'Модели для выбора агента в текущей рабочей области: серверные названия, available/offered, reasoning и ориентир цены. Scope: read:agents. agent_id необязателен. Для смены модели пользуйся этим каталогом; каталог сравнения имеет другой состав.',
+  inputSchema: z.toJSONSchema(definition.schema, {
+    target: 'draft-7',
+    io: 'input',
+  }),
+};
+const existing = registry.tools.findIndex((tool) => tool.name === definition.name);
+if (existing === -1) registry.tools.push(contract);
+else registry.tools[existing] = contract;
+for (const name of ['besales_agent_create', 'besales_agent_update']) {
+  const tool = agentSettingsTools.find((item) => item.name === name);
+  const published = registry.tools.find((item) => item.name === name);
+  if (!tool || !published) throw new Error('AGENT_TOOL_MISSING:' + name);
+  const generated = z.toJSONSchema(tool.schema, {
+    target: 'draft-7',
+    io: 'input',
+  });
+  published.inputSchema.properties.model = generated.properties.model;
+}
+const names = registry.tools.map((tool) => tool.name);
+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(
+  readmePath,
+  readme.replace(
+    /(<!-- BEGIN GENERATED TOOL INVENTORY -->)[\s\S]*?(<!-- END GENERATED TOOL INVENTORY -->)/u,
+    '$1\n\n' + renderToolInventoryMarkdown(names) + '\n\n$2',
+  ),
+);
+const routeMapPath = new URL('../src/schemas/mcp-v2-route-map.json', import.meta.url);
+const routeMap = JSON.parse(readFileSync(routeMapPath, 'utf8'));
+const args = {
+  workspace_id: '00000000-0000-4000-8000-000000000001',
+  agent_id: '00000000-0000-4000-8000-000000000002',
+};
+const request = definition.createRequest(definition.schema.parse(args));
+const url = new URL(request.path, 'https://api.invalid');
+const route = {
+  tool: definition.name,
+  canonicalArgs: args,
+  expected: {
+    method: request.method,
+    pathTemplate: url.pathname.replace(args.workspace_id, ':workspaceId'),
+    path: url.pathname,
+    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');
+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);
+console.log('Схемы каталога моделей агента и подсказки выпущены');

package/scripts/sync-api-contracts.mjs

@@ -0,0 +1,85 @@
+// Локальный выпуск по явному API checkout: API и Git-индекс остаются только входами.
+import { execFileSync } from 'node:child_process';
+import { shippedRef } from './shipped-ref.mjs';
+import { copyFileSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import { diffRegistries, lagKey } from './registry-diff.mjs';
+import { syncSchemaDescriptions } from './sync-schema-descriptions.mjs';
+
+const root = fileURLToPath(new URL('..', import.meta.url));
+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 run = (args) => execFileSync('yarn', args, { cwd: root, stdio: 'inherit' });
+run(['exec', 'openapi-typescript', apiFile, '-o', 'src/types/api-contract.gen.ts']);
+run(['build']);
+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));
+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]));
+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 } };
+  }
+  syncSchemaDescriptions(tool.inputSchema, derived);
+  return tool;
+});
+const { reactivationConfigSchema } = await import('../dist/tools/definitions/follow-up-config.js');
+const chain = registry.tools.find((tool) => tool.name === 'besales_followup_sequence_upsert');
+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.';
+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 inboundDefinition = toolDefinitions.find((tool) => tool.name === inbound.name);
+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 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 }));
+const finalRegistry = JSON.parse(readFileSync(registryPath, 'utf8'));
+const delta = diffRegistries(shipped.tools, 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];
+}
+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).',
+  };
+}
+writeFileSync(lagFile, JSON.stringify(lag, null, 2) + '\n');
+execFileSync(process.execPath, [resolve(root, 'scripts/sync-tool-inventory.mjs')], { cwd: root, stdio: 'inherit' });
+run(['build']);