@besales/mcp 0.45.0 → 0.47.0

package/dist/tools/definitions/shared.d.ts

@@ -10,11 +10,79 @@ export interface ApiToolRequest {
 export interface LocalToolContext {
     readonly store: ConnectionStore;
     readonly env: NodeJS.ProcessEnv;
+    readonly apiClient: ToolApiClient;
+    /** Имена, доступные этой MCP-сессии после применения tool profile. */
+    readonly availableToolNames?: ReadonlySet<string>;
 }
+/**
+ * Как обходиться с ответом инструмента, если он не влезает в потолок. Общего алгоритма нет:
+ * что здесь можно потерять, знает только сам инструмент. Числа и классы — `docs/response-size-budget.md`.
+ */
+export interface ToolResultPolicy {
+    /**
+     * Ответ обрезать нельзя ни при каких условиях — при превышении уходит отказ, а не данные.
+     * Два случая: (1) ответ является снимком для замещающей записи («прочитай всё → пришли всё
+     * обратно»), и усечённый снимок молча удалит непрочитанное; (2) у инструмента уже работает
+     * постраничная выдача, и конверт подменил бы исправный механизм тихой потерей.
+     */
+    readonly neverTruncate?: boolean;
+    /**
+     * Пути, которые разрешено выбросить при превышении, в порядке готовности расстаться.
+     * Путь `agents[].baseSystemPrompt` снимает поле у каждого элемента массива. Объявляется
+     * только для того, что читается ОТДЕЛЬНЫМ инструментом, — иначе это потеря, а не сжатие.
+     * `requiredPaths` намеренно отсутствует: выбрасывается ровно перечисленное, всё прочее
+     * неприкосновенно по построению, и второй список был бы носителем без читателя.
+     */
+    readonly droppablePaths?: readonly string[];
+    /** Потолок именно этого инструмента; без него берётся общий по классу. */
+    readonly maxResultBytes?: number;
+    /**
+     * Чем сузить запрос — уходит в текст отказа и в маркер. Ставится ТОЛЬКО когда у инструмента
+     * действительно есть параметры сужения: общая подсказка там, где сузить нечем, — ложь.
+     */
+    readonly narrowingHint?: string;
+}
+/**
+ * Что инструмент делает с состоянием. Проставляется РУКАМИ у каждого определения, потому что
+ * ни имя, ни HTTP-метод этого не выводят — и врут в обе стороны:
+ * семь `*_get_instructions` — POST, создающий долговечную запись операции (подстрока `_get`
+ * увела бы их в «только чтение»); список операторов CRM и проверка живости источника — GET,
+ * которые пишут; расхождение промптов, линт и поиск по вопросам-ответам — POST, которые читают.
+ *
+ * `spend` — тратит деньги или квоту на стороне сервера (обращение к модели, векторизация,
+ * отправка людям). Отдельно от `write`, потому что цена ошибки другая: повторный вызов
+ * не «перезапишет то же самое», а заплатит второй раз.
+ */
+export type ToolSideEffect = 'none' | 'write' | 'spend';
 export interface ToolDefinition<Input> {
     readonly name: string;
+    readonly sideEffect: ToolSideEffect;
+    /**
+     * Операция доказуемо обратима — снимает пометку «разрушительная». По спецификации MCP у
+     * не-читающего инструмента она подразумевается ИСТИННОЙ, поэтому опасна не пропущенная
+     * пометка, а ошибочно снятая: она сделала бы удаление безопасным в глазах хоста,
+     * одобряющего вызовы автоматически.
+     */
+    readonly reversible?: boolean;
+    /**
+     * Повтор с теми же аргументами даёт тот же результат БЕЗУСЛОВНО. Правило «все `*_upsert`
+     * идемпотентны» неверно: без идентификатора они уходят в создание, и автоповтор заводит
+     * вторую сущность.
+     */
+    readonly idempotent?: boolean;
+    /** Инструмент заведомо не выходит за пределы Besales. Умолчание — обратное, как худшее. */
+    readonly closedWorld?: boolean;
+    /**
+     * Чем свериться, если исход остался НЕИЗВЕСТЕН: связь оборвалась или сервер ответил отказом
+     * уже после того, как запрос до него дошёл. Отсутствие локального подтверждения не
+     * доказывает, что операция не состоялась, поэтому вызывающему называют инструмент проверки,
+     * а не советуют повтор. Заполняется у неидемпотентных операций, у которых такой инструмент
+     * есть; без него текст просто не называет конкретное имя.
+     */
+    readonly verifyWithToolName?: string;
     readonly requiredFields: readonly string[];
     readonly schema: ZodType<Input>;
+    readonly resultPolicy?: ToolResultPolicy;
     readonly defaultWorkspaceId?: boolean;
     /** API-проксирующие тулы. Взаимоисключающе с `localHandler`. */
     readonly createRequest?: (input: Input) => ApiToolRequest;
@@ -50,6 +118,13 @@ export declare const modelLaneSchema: z.ZodEnum<{
 export declare const MAX_FILE_UPLOAD_BYTES: number;
 /** Верхняя граница `max_lines` в `besales_prompt_diff` — должна совпадать с DTO бэкенда. */
 export declare const PROMPT_DIFF_MAX_LINES_LIMIT = 1000;
+/**
+ * Верхняя граница страницы перечня переменных — совпадает с `VARIABLES_LIST_MAX_LIMIT` бэкенда.
+ * Больший `limit` сервер отвергнет валидацией, поэтому граница объявлена и здесь.
+ */
+export declare const VARIABLES_MAX_PAGE_SIZE = 200;
+/** Максимальный размер явно запрошенной страницы списка агентов платформы. */
+export declare const PLATFORM_AGENTS_MAX_PAGE_SIZE = 200;
 /** Потолок агентов в одном пакетном прогоне — должен совпадать с `PROMPT_BATCH_MAX_AGENTS`. */
 export declare const PROMPT_BATCH_MAX_AGENTS = 200;
 /** Длина ключа идемпотентности пакетного прогона — должна совпадать с DTO бэкенда. */
@@ -179,7 +254,7 @@ export declare const promptAnalysisStageOutputSchema: z.ZodObject<{
     }>;
     output: z.ZodObject<{}, z.core.$loose>;
 }, z.core.$strip>;
-export declare const icpAnalysisSegmentSchema: z.ZodObject<{
+export declare const icpAnalysisSegmentSchema: z.ZodPipe<z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
@@ -187,15 +262,90 @@ export declare const icpAnalysisSegmentSchema: z.ZodObject<{
     pains: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
     motivations: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
     language_style: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
-}, z.core.$strip>;
-export declare const icpAnalysisPersonaSchema: z.ZodObject<{
+    languageStyle: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+}, z.core.$strip>, z.ZodTransform<{
+    language_style: {
+        [x: string]: unknown;
+    } | undefined;
+    name: string;
+    id?: string | undefined;
+    description?: string | undefined;
+    demographics?: {
+        [x: string]: unknown;
+    } | undefined;
+    pains?: unknown[] | undefined;
+    motivations?: unknown[] | undefined;
+}, {
+    name: string;
+    id?: string | undefined;
+    description?: string | undefined;
+    demographics?: {
+        [x: string]: unknown;
+    } | undefined;
+    pains?: unknown[] | undefined;
+    motivations?: unknown[] | undefined;
+    language_style?: {
+        [x: string]: unknown;
+    } | undefined;
+    languageStyle?: {
+        [x: string]: unknown;
+    } | undefined;
+}>>;
+export declare const icpAnalysisPersonaSchema: z.ZodPipe<z.ZodObject<{
     name: z.ZodString;
-    segment_id: z.ZodString;
+    segment_id: z.ZodOptional<z.ZodString>;
+    segmentId: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     pain_points: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    painPoints: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
     goals: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
     objections: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
     messaging_hints: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+    messagingHints: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
+}, z.core.$strip>, z.ZodTransform<{
+    segment_id: string | undefined;
+    pain_points: unknown[] | undefined;
+    messaging_hints: {
+        [x: string]: unknown;
+    } | undefined;
+    name: string;
+    description?: string | undefined;
+    goals?: unknown[] | undefined;
+    objections?: {
+        [x: string]: unknown;
+    } | undefined;
+}, {
+    name: string;
+    segment_id?: string | undefined;
+    segmentId?: string | undefined;
+    description?: string | undefined;
+    pain_points?: unknown[] | undefined;
+    painPoints?: unknown[] | undefined;
+    goals?: unknown[] | undefined;
+    objections?: {
+        [x: string]: unknown;
+    } | undefined;
+    messaging_hints?: {
+        [x: string]: unknown;
+    } | undefined;
+    messagingHints?: {
+        [x: string]: unknown;
+    } | undefined;
+}>>;
+/**
+ * Машинные ожидания реплики: что раннер песочницы обязан увидеть в ответе агента на неё.
+ *
+ * ⚠️ Без этой схемы поле не просто «не валидируется», а ИСЧЕЗАЕТ: zod стрипает неизвестные ключи
+ * молча, и ожидания не доехали бы до backend вовсе. Вторая точка потери — маппинг сабмита, где
+ * реплики пересобираются по явному списку полей.
+ */
+export declare const scenarioTurnExpectationSchema: z.ZodObject<{
+    triggers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    noTriggers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    noTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    answerContains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    answerNotContains: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export declare const scenarioSituationSchema: z.ZodObject<{
     role: z.ZodEnum<{
@@ -203,6 +353,14 @@ export declare const scenarioSituationSchema: z.ZodObject<{
         agent: "agent";
     }>;
     text: z.ZodString;
+    expect: z.ZodOptional<z.ZodObject<{
+        triggers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        noTriggers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        noTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        answerContains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        answerNotContains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const generatedScenarioSchema: z.ZodPipe<z.ZodObject<{
     name: z.ZodString;
@@ -215,6 +373,14 @@ export declare const generatedScenarioSchema: z.ZodPipe<z.ZodObject<{
             agent: "agent";
         }>;
         text: z.ZodString;
+        expect: z.ZodOptional<z.ZodObject<{
+            triggers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            noTriggers: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            noTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            answerContains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            answerNotContains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
 }, z.core.$strip>, z.ZodTransform<{
     segment_ids: string[] | undefined;
@@ -222,6 +388,14 @@ export declare const generatedScenarioSchema: z.ZodPipe<z.ZodObject<{
     situations: {
         role: "client" | "agent";
         text: string;
+        expect?: {
+            triggers?: string[] | undefined;
+            noTriggers?: string[] | undefined;
+            tools?: string[] | undefined;
+            noTools?: string[] | undefined;
+            answerContains?: string[] | undefined;
+            answerNotContains?: string[] | undefined;
+        } | undefined;
     }[];
     description?: string | undefined;
 }, {
@@ -229,6 +403,14 @@ export declare const generatedScenarioSchema: z.ZodPipe<z.ZodObject<{
     situations: {
         role: "client" | "agent";
         text: string;
+        expect?: {
+            triggers?: string[] | undefined;
+            noTriggers?: string[] | undefined;
+            tools?: string[] | undefined;
+            noTools?: string[] | undefined;
+            answerContains?: string[] | undefined;
+            answerNotContains?: string[] | undefined;
+        } | undefined;
     }[];
     description?: string | undefined;
     segment_ids?: string[] | undefined;
@@ -236,27 +418,32 @@ export declare const generatedScenarioSchema: z.ZodPipe<z.ZodObject<{
 }>>;
 export declare const sandboxFindingSchema: z.ZodObject<{
     scenario_id: z.ZodOptional<z.ZodString>;
+    scenarioId: z.ZodOptional<z.ZodString>;
     category: z.ZodEnum<{
         other: "other";
         hallucination: "hallucination";
         wrong_action: "wrong_action";
         bad_tone: "bad_tone";
+        missed_context: "missed_context";
         wrong_routing: "wrong_routing";
-        missed_trigger: "missed_trigger";
-        wrong_pipeline_transition: "wrong_pipeline_transition";
         rag_miss: "rag_miss";
     }>;
     severity: z.ZodEnum<{
+        critical: "critical";
         low: "low";
         medium: "medium";
-        critical: "critical";
     }>;
-    message: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    message: z.ZodOptional<z.ZodString>;
+    evidence: z.ZodOptional<z.ZodString>;
+    recommendation: z.ZodOptional<z.ZodString>;
     suggestion: z.ZodOptional<z.ZodString>;
     turn_index: z.ZodOptional<z.ZodNumber>;
+    turnIndex: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const simulationFindingSchema: z.ZodObject<{
     dialogue_id: z.ZodOptional<z.ZodString>;
+    dialogueId: z.ZodOptional<z.ZodString>;
     category: z.ZodEnum<{
         other: "other";
         hallucination: "hallucination";
@@ -267,13 +454,14 @@ export declare const simulationFindingSchema: z.ZodObject<{
         off_topic: "off_topic";
     }>;
     severity: z.ZodEnum<{
+        critical: "critical";
         low: "low";
         medium: "medium";
-        critical: "critical";
     }>;
     message: z.ZodString;
     suggestion: z.ZodOptional<z.ZodString>;
     reference_message_index: z.ZodOptional<z.ZodNumber>;
+    referenceMessageIndex: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const routingRuleLeadStatusSchema: z.ZodObject<{
     lead_status_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -675,6 +863,51 @@ export declare const platformInstagramCommentSchema: z.ZodObject<{
     instagram_comment_keywords: z.ZodOptional<z.ZodNullable<z.ZodObject<{}, z.core.$loose>>>;
     reply_to_story_mentions: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
+/**
+ * Ссылка на стадию CRM ПОЛНЫМ композитом.
+ *
+ * ⚠️ Голый `status_id` не годится: статусы 142/143 и одноимённые стадии есть в КАЖДОЙ
+ * воронке, и выбор по номеру попал бы не туда.
+ */
+export declare const funnelStageRefSchema: z.ZodObject<{
+    pipeline_crm_id: z.ZodString;
+    pipeline_id: z.ZodNumber;
+    status_id: z.ZodNumber;
+}, z.core.$strict>;
+/**
+ * Настройки раздела «Воронка канала».
+ *
+ * ⚠️ `null` у `decision_gate`/`path_target_stage` — СБРОС; отсутствие поля — «не трогать».
+ * Бэкенд ДЕЛЕГИРУЕТ запись сервисам раздела, поэтому здесь нет своей валидации стадий:
+ * «стадии разные» и «стадия есть в каталоге площадки» проверяет он, и второй набор правил
+ * рядом разошёлся бы с первым.
+ */
+export declare const platformFunnelAnalyticsSchema: z.ZodObject<{
+    decision_gate: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        submitted: z.ZodObject<{
+            pipeline_crm_id: z.ZodString;
+            pipeline_id: z.ZodNumber;
+            status_id: z.ZodNumber;
+        }, z.core.$strict>;
+        approved: z.ZodObject<{
+            pipeline_crm_id: z.ZodString;
+            pipeline_id: z.ZodNumber;
+            status_id: z.ZodNumber;
+        }, z.core.$strict>;
+        rejected: z.ZodObject<{
+            pipeline_crm_id: z.ZodString;
+            pipeline_id: z.ZodNumber;
+            status_id: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>>;
+    path_target_stage: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        pipeline_crm_id: z.ZodString;
+        pipeline_id: z.ZodNumber;
+        status_id: z.ZodNumber;
+    }, z.core.$strict>>>;
+    engaged_inbound_count: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    stuck_threshold_hours: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, z.core.$strict>;
 export declare const platformGeneralSettingsSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     off_message: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -713,6 +946,18 @@ export declare const coldWelcomeChannelsModeEnum: z.ZodEnum<{
     RESTRICT: "RESTRICT";
     ADD: "ADD";
 }>;
+/**
+ * Режим правила предохранителя холодных отправок.
+ *
+ * OFF — правило выключено; WARN — сработавшее правило только записывается в аудит, отправка
+ * идёт; BLOCK — отправка останавливается. По умолчанию `active_series` = BLOCK (правило,
+ * из-за нарушения которого пришла жалоба клиента), остальные = WARN.
+ */
+export declare const guardModeEnum: z.ZodEnum<{
+    OFF: "OFF";
+    WARN: "WARN";
+    BLOCK: "BLOCK";
+}>;
 export declare const getcourseTransportEnum: z.ZodEnum<{
     Site: "Site";
     Email: "Email";
@@ -794,6 +1039,22 @@ export declare const platformGetcourseSettingsSchema: z.ZodObject<{
     }, z.core.$strict>>>>;
     target_department_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     delivery_check_enabled: z.ZodOptional<z.ZodBoolean>;
+    guard_active_series: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        OFF: "OFF";
+        WARN: "WARN";
+        BLOCK: "BLOCK";
+    }>>>;
+    guard_active_application: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        OFF: "OFF";
+        WARN: "WARN";
+        BLOCK: "BLOCK";
+    }>>>;
+    guard_paid: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        OFF: "OFF";
+        WARN: "WARN";
+        BLOCK: "BLOCK";
+    }>>>;
+    quiet_days: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     delivery_field_map: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
         Site: "Site";
         Email: "Email";
@@ -837,7 +1098,7 @@ export declare function setupConfirmation(input: {
 export declare function withInstructions(response: unknown, instructions: readonly string[]): unknown;
 export declare function buildKnowledgeSpaceListQuery(scopeType?: string, channelId?: string): string;
 export declare function buildListQuery(params: Record<string, string | number | boolean | string[] | undefined>): string;
-export declare function buildVariableListQuery(scope: 'WORKSPACE' | 'CHANNEL', platformId?: string, filter?: 'all' | 'variables' | 'constants'): string;
+export declare function buildVariableListQuery(scope: 'WORKSPACE' | 'CHANNEL', platformId?: string, filter?: 'all' | 'variables' | 'constants', limit?: number, cursor?: string): string;
 export declare function buildVariableScopeQuery(scope: 'WORKSPACE' | 'CHANNEL', platformId?: string): string;
 export declare function buildFileListQuery(input: {
     file_type?: string;
@@ -862,6 +1123,7 @@ export declare function mapPlatformVariablesConfigInput(input: z.infer<typeof pl
 export declare function mapPlatformCrmBehaviorInput(input: z.infer<typeof platformCrmBehaviorSchema>): Record<string, unknown>;
 export declare function mapPlatformWidgetMarketingInput(input: z.infer<typeof platformWidgetMarketingSchema>): Record<string, unknown>;
 export declare function mapPlatformInstagramCommentInput(input: z.infer<typeof platformInstagramCommentSchema>): Record<string, unknown>;
+export declare function mapPlatformFunnelAnalyticsInput(input: z.infer<typeof platformFunnelAnalyticsSchema>): Record<string, unknown>;
 export declare function mapPlatformGeneralSettingsInput(input: z.infer<typeof platformGeneralSettingsSchema>): Record<string, unknown>;
 export declare function mapPlatformSalebotSettingsInput(input: z.infer<typeof platformSalebotSettingsSchema>): Record<string, unknown>;
 export declare function mapPlatformSmsgorodSettingsInput(input: z.infer<typeof platformSmsgorodSettingsSchema>): Record<string, unknown>;