@besales/mcp 0.48.0 → 1.0.0-beta.2

package/dist/tools/definitions/knowledge.js

@@ -1,5 +1,67 @@
 import { z } from 'zod';
-import { buildKnowledgeSpaceListQuery, buildListQuery, compactObject, defineTool, knowledgeTableSourceSchema, uuidSchema, withInstructions, } from './shared.js';
+import { knowledgeSpaceSearchFields } from './knowledge-space-search-fields.js';
+/** Номер страницы нельзя молча превратить в первую страницу курсорного списка. */
+const retiredKnowledgePageSchema = z.number().int().min(1).optional().superRefine((value, context) => {
+    if (value !== undefined)
+        context.addIssue({
+            code: 'custom',
+            message: 'page упразднён: продолжайте список по cursor из предыдущего ответа; страница не прочитана',
+        });
+});
+import { refineSplitOverride, splitOverrideSchema, toV2Chunking } from './knowledge-chunking.js';
+import { buildKnowledgeSpaceListQuery, compactObject, defineTool, knowledgeTableSourceSchema, knowledgeSpaceIdSchema, uuidSchema, withInstructions, } from './shared.js';
+const QA_SOURCE_NAME_MAX_CODE_POINTS = 80;
+function mapDocumentStatus(status) {
+    if (status === undefined)
+        return undefined;
+    if (status === 'COMPLETED')
+        return 'ACTIVE';
+    if (status === 'FAILED')
+        return 'FAILED';
+    if (status === 'LOADED' || status === 'TEXT_EXTRACTED')
+        return 'PENDING';
+    return 'INDEXING';
+}
+function mapWebsiteStatus(status) {
+    if (status === undefined || status === 'PENDING' || status === 'FAILED')
+        return status;
+    return status === 'COMPLETED' ? 'ACTIVE' : 'INDEXING';
+}
+/**
+ * limit и cursor передаются серверу; номер page отвергается до запроса с адресом поля.
+ * Курсор сохраняет обход при создании и удалении источников между страницами:
+ * смещение могло бы пропустить строку или показать её дважды.
+ */
+function buildSourceListQuery(sourceType, filters = {}) {
+    const query = new URLSearchParams({ sourceType });
+    if (filters.status)
+        query.set('status', filters.status);
+    if (filters.qaMode)
+        query.set('qaMode', filters.qaMode);
+    if (filters.isActive !== undefined)
+        query.set('isActive', String(filters.isActive));
+    if (filters.limit !== undefined)
+        query.set('limit', String(filters.limit));
+    if (filters.cursor)
+        query.set('cursor', filters.cursor);
+    return `?${query.toString()}`;
+}
+function deriveQaSourceName(question) {
+    const normalized = question.normalize('NFC').trim().replace(/\s+/gu, ' ');
+    return [...normalized].slice(0, QA_SOURCE_NAME_MAX_CODE_POINTS).join('');
+}
+function mapQaAnswerChunks(chunks, answer, create) {
+    if (chunks) {
+        return chunks.map((chunk) => compactObject({
+            text: chunk.text,
+            storedFileId: chunk.stored_file_id,
+            buttons: chunk.buttons,
+        }));
+    }
+    if (answer !== undefined)
+        return [{ text: answer }];
+    return create ? [{}] : undefined;
+}
 function requireSingleSheetSelector(value, ctx) {
     const count = [value.sheet_title, value.sheet_gid, value.sheet_index].filter((item) => item !== undefined).length;
     if (count !== 1) {
@@ -66,14 +128,14 @@ export const knowledgeTools = [
             }),
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Это инвентаризация и sample, а не полное чтение. dimensionsKnown=false или truncated=true требуют постраничного `besales_workbook_sheet_read`.',
+            'Это инвентаризация и sample, а не полное чтение. truncated/rowsTruncated/columnsTruncated требуют постраничного `besales_workbook_sheet_read` либо явного сообщения о parser cap.',
             'Проверь readError у каждой вкладки: ошибка чтения не означает, что лист пуст.',
-            'Пройди по ВСЕМ вкладкам — не делай вывод «этого нет в файле», пока не дочитал их страницы.',
+            'Пройди по содержимому ВСЕХ вкладок — не делай вывод «этого нет в файле», пока не дочитал доступные страницы каждой.',
             'Если контент на языке, отличном от языка диалога с пользователем — ПЕРЕД внедрением (RAG/промпт/ICP) дай пользователю краткое саммари на его языке: что нашёл и что внедряешь; по цифрам/процентам/условиям дождись подтверждения.',
             'Классифицируй каждую вкладку по таксономии из `besales://concepts/workbook-classification`.',
             'Для compact knowledge (≤8k chars) — сделай локальную LLM-выжимку и положи через `besales_agent_facts_set`.',
             'Для bulk knowledge (>8k) — `besales_workbook_to_knowledge_document`.',
-            'Для диалог-индексов с amoCRM-ссылками — вызови `besales_workbook_extract_amocrm_leads`, затем передай leads[].id в `besales_icp_import_dialogues mode=audio audio_source_type=amocrm_leads`.',
+            'XLSX с amoCRM-ссылками можно передать в besales_icp_import_dialogues с source.kind=xlsx_upload, storedFileId и crmConnectionId; потребуются request_key и явное gdpr_confirmed=true.',
             'Если Google Sheets 403 (`google_sheets_not_shared`) — покажи юзеру `serviceAccountEmail` из response и попроси расшарить таблицу.',
             'После классификации зафиксируй решения через `besales_workbook_classification_update`.',
         ]),
@@ -112,10 +174,9 @@ export const knowledgeTools = [
             path: `/workspaces/${input.workspace_id}/workbooks/${input.workbook_id}/sheets/read?${buildWorkbookSheetReadQuery(input)}`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Это явная страница листа. Для полного 2D-обхода пройди rowOffset до scanUpperBoundRowCount для каждого columnOffset, затем сбрось rowOffset в 0 и перейди к следующему nextColumnOffset.',
-            'Для Google Sheets totalRowCount/totalColumnCount могут быть null: это неизвестный total, а не ноль.',
-            'Пустая страница внутри Google grid не доказывает конец данных: следуй nextRowOffset/nextColumnOffset до верхних границ.',
-            'Если sourceTruncated=true, backend знает, что часть источника лежит за parser cap: не называй результат полным и не внедряй его как полный набор.',
+            'Для полного 2D-обхода пройди rowOffset до scanUpperBoundRowCount для каждого columnOffset, затем сбрось rowOffset в 0 и перейди к следующему nextColumnOffset.',
+            'Пустая страница не доказывает конец данных: offsets продвигаются до явных scanUpperBound.',
+            'Если sourceTruncated=true, часть источника лежит за parser cap: не называй результат полным и не внедряй его как полный набор.',
             'Повтори страницу перед внедрением и сравни pageFingerprint, если источник мог измениться во время чтения.',
         ]),
     }),
@@ -149,13 +210,13 @@ export const knowledgeTools = [
             path: `/workspaces/${input.workspace_id}/workbooks/${input.workbook_id}/archive`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'SourceWorkbook архивирован; созданные KnowledgeDocument не удалены.',
+            'SourceWorkbook архивирован; созданные knowledge documents не удалены.',
             'Для проверки перечитай книгу через `besales_workbook_get` и проверь archivedAt.',
         ]),
     }),
     defineTool({
         name: 'besales_workbook_extract_amocrm_leads',
-        sideEffect: 'write',
+        sideEffect: 'none',
         requiredFields: ['workbook_id'],
         defaultWorkspaceId: true,
         schema: z
@@ -179,7 +240,7 @@ export const knowledgeTools = [
         }),
         enhanceResponse: (response) => withInstructions(response, [
             'Возвращены все amoCRM lead-ID из ВСЕЙ вкладки (без sample-лимита inspect).',
-            'Используй leads[].id для `besales_icp_import_dialogues mode=audio audio_source_type=amocrm_leads`.',
+            'lead-ID можно передать в besales_icp_import_dialogues с source.kind=amocrm_calls, crmConnectionId и leadIds; потребуются request_key и явное gdpr_confirmed=true.',
             'Если truncated=true — вкладка длиннее 10000 строк (hard cap); часть строк не прочитана.',
         ]),
     }),
@@ -195,42 +256,58 @@ export const knowledgeTools = [
             sheet_title: z.string().optional(),
             sheet_gid: z.number().int().optional(),
             sheet_index: z.number().int().min(0).optional(),
+            /**
+             * Два способа адресовать одно и то же пространство знаний, и это НЕ дублирование:
+             * отгруженный клиент называет пространство ИМЕНЕМ (`namespace`), а в v2 пространство —
+             * сущность с идентификатором. Прежняя редакция ветки оставляла только идентификатор, и
+             * отгруженный вызов с именем ронялся сервером на неизвестном поле. Разрешение имени
+             * делает СЕРВЕР — одной операцией, точным совпадением; поиск на стороне моста означал бы
+             * второй запрос и гонку между чтением списка и записью документа.
+             */
+            knowledge_space_id: knowledgeSpaceIdSchema.optional(),
             namespace: z.string().optional(),
-            split_override: z
-                .object({
-                split_mode: z.enum(['size', 'separator']),
-                separator: z.string().optional(),
-                chunk_size: z.number().int().min(100).optional(),
-                chunk_overlap: z.number().int().min(0).optional(),
-                max_chunk_size: z.number().int().min(100).optional(),
-            })
-                .optional(),
+            split_override: splitOverrideSchema.optional(),
             replace_existing: z.boolean().optional(),
+            target_knowledge_source_id: uuidSchema.optional(),
         })
-            .superRefine(requireSingleSheetSelector),
+            .superRefine((value, ctx) => {
+            requireSingleSheetSelector(value, ctx);
+            refineSplitOverride(value.split_override, ctx);
+            // Оба поля можно опустить: сервер разрешит имя general тем же правилом, что явное имя.
+            // Одновременная адресация двумя способами остаётся ошибкой до сетевого запроса.
+            const byId = value.knowledge_space_id !== undefined;
+            const byName = value.namespace !== undefined;
+            if (byId && byName) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message: 'knowledge_space_id и namespace взаимоисключающи: назови пространство одним способом',
+                    path: ['knowledge_space_id'],
+                });
+            }
+        }),
         createRequest: (input) => ({
             path: `/workspaces/${input.workspace_id}/workbooks/${input.workbook_id}/knowledge-document`,
             body: compactObject({
                 sheetTitle: input.sheet_title,
                 sheetGid: input.sheet_gid,
                 sheetIndex: input.sheet_index,
-                namespace: input.namespace,
-                splitOverride: input.split_override
-                    ? compactObject({
-                        splitMode: input.split_override.split_mode,
-                        separator: input.split_override.separator,
-                        chunkSize: input.split_override.chunk_size,
-                        chunkOverlap: input.split_override.chunk_overlap,
-                        maxChunkSize: input.split_override.max_chunk_size,
-                    })
-                    : undefined,
+                knowledgeSpaceId: input.knowledge_space_id,
+                knowledgeSpaceName: input.namespace,
+                chunking: input.split_override ? toV2Chunking(input.split_override) : undefined,
                 replaceExisting: input.replace_existing,
+                targetKnowledgeSourceId: input.target_knowledge_source_id,
             }),
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'KnowledgeDocument создан. Привяжи namespace к агенту через `AgentChat.knowledgeNamespaces` если не привязан (см. besales_agent_update).',
-            'response.splitDecision.reason — почему сервер выбрал такой режим чанкинга (heuristic либо override).',
-            'При повторном вызове для того же листа — старый AI_INGESTED документ заменяется (idempotency).',
+            'outcome=CONTENT_REPLACED означает, что содержимое выбранного документа поставлено на переиндексацию; outcome=CREATED — создан новый документ.',
+            'Цель выбирается по порядку: явный target_knowledge_source_id → единственное доказуемое совпадение → новый документ. Признак совпадения зависит от рода книги: у Google это ТОЛЬКО стабильный gid (заголовок вкладки мутабелен и не участвует), у xlsx — книга и заголовок вкладки; Google без gid цель не ищет вовсе.',
+            'Несколько совпадений — отказ 409 со списком knowledgeSourceIds, документ НЕ создаётся: удали лишние либо назови нужный в target_knowledge_source_id.',
+            'Перезалитый xlsx автоматически не опознаётся как та же книга: для замены передай target_knowledge_source_id явно.',
+            'possibleDuplicates — только подсказка и ничего не изменяет. При необходимости повтори вызов с target_knowledge_source_id.',
+            'indexingStatus=QUEUED означает асинхронную индексацию: ответ не обещает, что новые чанки уже активны.',
+            'splitDecision называет применённые правила разбиения: OVERRIDE — из split_override этого вызова, GLOBAL_DEFAULT — умолчание (памяти прошлых правил у документа нет: замена без split_override возвращает умолчание).',
+            'Пространство можно назвать ОДНИМ способом: knowledge_space_id либо namespace (имя). Без обоих полей используется пространство с именем general. Имя сравнивается ТОЧНО — как его уникализирует база; несуществующее имя даёт отказ, пространство по нему не создаётся.',
+            'Привяжи knowledge-пространство к агенту, если оно ещё не привязано (см. besales_agent_update).',
         ]),
     }),
     // v1.5 — Knowledge Spaces (Increment 1): создание/управление namespaces для агентов
@@ -245,7 +322,7 @@ export const knowledgeTools = [
             name: z.string().min(1).max(100),
             scope_type: z.enum(['WORKSPACE', 'CHANNEL']),
             channel_id: uuidSchema.optional(),
-            access_mode: z.enum(['AUTO_QUERY', 'TOOL_ONLY']).optional(),
+            ...knowledgeSpaceSearchFields,
         })
             .superRefine((value, ctx) => {
             if (value.scope_type === 'CHANNEL' && !value.channel_id) {
@@ -262,19 +339,22 @@ export const knowledgeTools = [
             }
         }),
         createRequest: (input) => ({
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces`,
+            path: '/knowledge-spaces',
             body: compactObject({
+                workspaceId: input.workspace_id,
                 name: input.name,
-                scope_type: input.scope_type,
-                channel_id: input.channel_id,
-                access_mode: input.access_mode,
+                scopeType: input.scope_type,
+                scopeId: input.channel_id,
+                accessMode: input.access_mode,
+                purpose: input.purpose,
+                searchKeywords: input.search_keywords,
             }),
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Knowledge space создан. id — UUID для последующих ingestion-операций.',
-            'WORKSPACE scope доступен всем каналам через besales_knowledge_space_channel_link_upsert.',
-            'CHANNEL scope привязан к channel_id жёстко (изолирован).',
-            'Дальше: загрузи документ через besales_knowledge_document_upload или Q&A (Increment 2).',
+            'База знаний создана. Её идентификатор нужен для добавления источников.',
+            'Общую базу можно подключить к нужным каналам; база отдельного канала доступна только ему.',
+            'Добавь документ или проверенную пару вопрос–ответ и дождись индексации.',
+            'Назначение помогает агенту выбрать базу по запросу. Слова обязательного поиска добавляют доступную активную базу в автоматический план при совпадении с вопросом.',
         ]),
     }),
     defineTool({
@@ -299,11 +379,11 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
         }),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}`,
         }),
     }),
     defineTool({
@@ -313,16 +393,18 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             name: z.string().min(1).max(100).optional(),
-            access_mode: z.enum(['AUTO_QUERY', 'TOOL_ONLY']).optional(),
+            ...knowledgeSpaceSearchFields,
         }),
         createRequest: (input) => ({
             method: 'PATCH',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}`,
             body: compactObject({
                 name: input.name,
-                access_mode: input.access_mode,
+                accessMode: input.access_mode,
+                purpose: input.purpose,
+                searchKeywords: input.search_keywords,
             }),
         }),
     }),
@@ -333,12 +415,13 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             channel_id: uuidSchema,
         }),
         createRequest: (input) => ({
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/channel-links`,
-            body: { channel_id: input.channel_id },
+            method: 'PUT',
+            path: `/knowledge-spaces/${input.knowledge_space_id}/channel-links/${input.channel_id}`,
+            body: {},
         }),
     }),
     defineTool({
@@ -348,39 +431,32 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             channel_id: uuidSchema,
         }),
         createRequest: (input) => ({
             method: 'DELETE',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/channel-links/${input.channel_id}`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}/channel-links/${input.channel_id}`,
         }),
     }),
     // v1.5 — Knowledge Documents (Increment 1): загрузка/удаление документов в space
     defineTool({
         name: 'besales_knowledge_document_upload',
-        sideEffect: 'write',
+        sideEffect: 'spend',
         requiredFields: ['knowledge_space_id', 'source_kind'],
         defaultWorkspaceId: true,
         schema: z
             .object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             source_kind: z.enum(['STORED_FILE', 'TEXT']),
             stored_file_id: uuidSchema.optional(),
             content: z.string().optional(),
             filename: z.string().optional(),
-            split_override: z
-                .object({
-                split_mode: z.enum(['size', 'separator']),
-                separator: z.string().optional(),
-                chunk_size: z.number().int().min(100).optional(),
-                chunk_overlap: z.number().int().min(0).optional(),
-                max_chunk_size: z.number().int().min(100).optional(),
-            })
-                .optional(),
+            split_override: splitOverrideSchema.optional(),
         })
             .superRefine((value, ctx) => {
+            refineSplitOverride(value.split_override, ctx);
             if (value.source_kind === 'STORED_FILE' && !value.stored_file_id) {
                 ctx.addIssue({
                     code: z.ZodIssueCode.custom,
@@ -393,30 +469,49 @@ export const knowledgeTools = [
                     message: 'content и filename обязательны для source_kind=TEXT',
                 });
             }
+            else if (value.source_kind === 'TEXT' && value.content.trim() === '') {
+                // Как у прежней системы: пустой текст — отказ, а не документ (и не замена рабочего документа пустотой).
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['content'],
+                    message: 'content не может состоять из одних пробелов',
+                });
+            }
         }),
-        createRequest: (input) => ({
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/documents`,
-            body: compactObject({
-                source_kind: input.source_kind,
-                stored_file_id: input.stored_file_id,
-                content: input.content,
-                filename: input.filename,
-                split_override: input.split_override
-                    ? compactObject({
-                        split_mode: input.split_override.split_mode,
-                        separator: input.split_override.separator,
-                        chunk_size: input.split_override.chunk_size,
-                        chunk_overlap: input.split_override.chunk_overlap,
-                        max_chunk_size: input.split_override.max_chunk_size,
-                    })
-                    : undefined,
-            }),
-        }),
+        createRequest: (input) => {
+            const chunking = input.split_override ? toV2Chunking(input.split_override) : undefined;
+            // Файл библиотеки: сервер копирует тело в собственный файл документа; content и filename не читаются (как у
+            // прежней системы — имя документа берётся из имени файла).
+            if (input.source_kind === 'STORED_FILE') {
+                return {
+                    path: `/knowledge-spaces/${input.knowledge_space_id}/sources/document/from-file`,
+                    body: compactObject({ storedFileId: input.stored_file_id, chunking }),
+                };
+            }
+            const filename = input.filename ?? 'document.txt';
+            const body = new FormData();
+            body.append('name', filename);
+            // Как у прежней системы: повтор текста с тем же именем даёт документу новое содержимое, а не второй документ.
+            // Сервер заменяет текстом только документ, созданный ассистентом (текстом, из файла библиотеки, из вкладки книги):
+            // документ с тем же именем, загруженный человеком файлом, — отказ 409.
+            body.append('replaceExisting', 'true');
+            // ⛔ Правила — ОДНИМ полем JSON: плоское поле формы уходит с заменой перевода строки на «возврат каретки +
+            // перевод строки», и разделитель вида «\\n## » пришёл бы на сервер изменённым.
+            if (chunking !== undefined)
+                body.append('chunking', JSON.stringify(chunking));
+            body.append('file', new Blob([input.content ?? ''], { type: 'text/plain;charset=utf-8' }), filename);
+            return {
+                path: `/knowledge-spaces/${input.knowledge_space_id}/sources/document`,
+                body,
+            };
+        },
         enhanceResponse: (response) => withInstructions(response, [
-            'Document uploaded. Processing is async — статус движется PENDING → COMPLETED либо FAILED.',
-            'Опрашивай статус через besales_knowledge_document_get пока status=COMPLETED.',
-            'Для TEXT source_kind при повторном вызове с тем же filename — старый документ заменяется (document_replaced=true).',
-            'Binary файлы (PDF/DOCX) — загрузи сначала через POST /api/v2/files отдельно, затем передай stored_file_id сюда.',
+            'outcome=CREATED — документ создан в статусе PENDING; outcome=CONTENT_REPLACED — у текстового документа с тем же именем заменено содержимое (document_replaced прежней системы). Индексация асинхронна.',
+            'Создание: опрашивай besales_knowledge_document_get до status=ACTIVE, FAILED либо EMPTY. EMPTY — в файле не нашлось текста (например, скан без текстового слоя): такой документ ничего не отвечает — удали его и загрузи файл с текстом.',
+            'Замена: status остаётся ACTIVE и во время переиндексации, и после её провала — по статусу замену не проверить. Новый текст отвечает, когда lastIndexedAt станет позже updatedAt из этого ответа; непустой errorMessage — переиндексация не удалась, отвечает прежний текст. Не сообщай «новый текст в базе знаний», пока lastIndexedAt не обновился.',
+            'Текстом заменяется документ, созданный ассистентом: текстом этого инструмента, из файла библиотеки (source_kind=STORED_FILE) или из вкладки книги. Документ с тем же именем, загруженный человеком файлом через интерфейс (в том числе .txt или .md), — отказ 409 KNOWLEDGE_REPLACE_TARGET_UPLOADED; выбери другое имя или удали документ.',
+            'Файл из библиотеки: besales_file_upload_request → besales_file_upload_status (READY → stored_file_id) → этот инструмент с source_kind=STORED_FILE. Имя документа — имя файла; документ с таким именем уже есть — отказ 409 «имя занято»: удали его либо загрузи файл под другим именем. В знания идёт только файл библиотеки: присланный человеком в переписке и пришедший из CRM — отказ (знания видят все клиенты).',
+            'split_override задаёт правила разбиения этого документа: size — по размеру куска, separator — по разделителю (раздел длиннее max_chunk_size дорезается). Без split_override — правила по умолчанию.',
         ]),
     }),
     defineTool({
@@ -427,8 +522,9 @@ export const knowledgeTools = [
         requiredFields: ['knowledge_space_id'],
         defaultWorkspaceId: true,
         schema: z.object({
+            page: retiredKnowledgePageSchema,
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             status: z
                 .enum([
                 'LOADED',
@@ -441,12 +537,12 @@ export const knowledgeTools = [
                 'CHUNKS_SAVED',
             ])
                 .optional(),
-            page: z.number().int().min(1).optional(),
+            cursor: z.string().min(1).optional(),
             limit: z.number().int().min(1).max(100).optional(),
         }),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/documents${buildListQuery({ status: input.status, page: input.page, limit: input.limit })}`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources${buildSourceListQuery('DOCUMENT', { status: mapDocumentStatus(input.status), limit: input.limit, cursor: input.cursor })}`,
         }),
     }),
     defineTool({
@@ -456,12 +552,12 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             document_id: uuidSchema,
         }),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/documents/${input.document_id}`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources/${input.document_id}`,
         }),
     }),
     defineTool({
@@ -471,25 +567,24 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             document_id: uuidSchema,
             explicit_confirmation: z.literal(true),
         }),
         createRequest: (input) => ({
             method: 'DELETE',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/documents/${input.document_id}`,
-            body: { explicit_confirmation: input.explicit_confirmation },
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources/${input.document_id}`,
         }),
     }),
     // ----- v1.5 Increment 2: Q&A CRUD (7 tools) -----
     defineTool({
         name: 'besales_knowledge_qa_create',
-        sideEffect: 'write',
+        sideEffect: 'spend',
         requiredFields: ['knowledge_space_id', 'question'],
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             question: z.string().min(1),
             answer: z.string().optional(),
             answer_chunks: z
@@ -509,22 +604,25 @@ export const knowledgeTools = [
             is_call_qa_only: z.boolean().optional(),
         }),
         createRequest: (input) => ({
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/qa-pairs`,
-            body: compactObject({
-                question: input.question,
-                answer: input.answer,
-                answer_chunks: input.answer_chunks,
-                alias: input.alias,
-                mode: input.mode,
-                call_operator: input.call_operator,
-                chunk_delay_seconds: input.chunk_delay_seconds,
-                is_call_qa_only: input.is_call_qa_only,
-            }),
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources`,
+            body: {
+                sourceType: 'QA',
+                name: deriveQaSourceName(input.question),
+                qa: compactObject({
+                    question: input.question,
+                    alias: input.alias,
+                    mode: input.mode ?? 'SIMPLE',
+                    callOperator: input.call_operator,
+                    chunkDelaySeconds: input.chunk_delay_seconds,
+                    isCallQaOnly: input.is_call_qa_only,
+                    answerChunks: mapQaAnswerChunks(input.answer_chunks, input.answer, true),
+                }),
+            },
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Q&A создана. Embedding для вопроса генерируется sync — статус COMPLETED в большинстве случаев сразу.',
-            'mode=SIMPLE с одним чанком → используется с RAG; STRICT — только QA-промпт без RAG; ONCE_STRICT — первый раз STRICT, далее как контекст.',
-            'is_call_qa_only=true → QA не векторизуется, доступна только через call_qa tool.',
+            'QA source создан в статусе PENDING; индексация выполняется асинхронно.',
+            'mode=SIMPLE участвует в обычном retrieval; STRICT/ONCE_STRICT сохраняют специальную QA-семантику.',
+            'is_call_qa_only=true исключает source из auto-retrieval.',
         ]),
     }),
     defineTool({
@@ -535,15 +633,16 @@ export const knowledgeTools = [
         requiredFields: ['knowledge_space_id'],
         defaultWorkspaceId: true,
         schema: z.object({
+            page: retiredKnowledgePageSchema,
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             mode: z.enum(['SIMPLE', 'STRICT', 'ONCE_STRICT']).optional(),
-            page: z.number().int().min(1).optional(),
+            cursor: z.string().min(1).optional(),
             limit: z.number().int().min(1).max(100).optional(),
         }),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/qa-pairs${buildListQuery({ mode: input.mode, page: input.page, limit: input.limit })}`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources${buildSourceListQuery('QA', { qaMode: input.mode, limit: input.limit, cursor: input.cursor })}`,
         }),
     }),
     defineTool({
@@ -553,12 +652,12 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             qa_id: uuidSchema,
         }),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/qa-pairs/${input.qa_id}`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources/${input.qa_id}`,
         }),
     }),
     defineTool({
@@ -568,14 +667,17 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             qa_id: uuidSchema,
             question: z.string().min(1).optional(),
             answer: z.string().optional(),
             answer_chunks: z
                 .array(z.object({
                 text: z.string().optional(),
-                stored_file_id: uuidSchema.optional(),
+                // ⛔ nullable, а не только optional: «ключ не прислан» = не менять, а `null` =
+                // СНЯТЬ вложение. Без null снять его было нечем — схема отвергала значение до
+                // отправки, и построенного пути открепления у клиента не существовало вовсе.
+                stored_file_id: uuidSchema.nullable().optional(),
                 buttons: z
                     .array(z.object({ name: z.string().min(1), url: z.string().min(1) }))
                     .optional(),
@@ -590,17 +692,18 @@ export const knowledgeTools = [
         }),
         createRequest: (input) => ({
             method: 'PATCH',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/qa-pairs/${input.qa_id}`,
-            body: compactObject({
-                question: input.question,
-                answer: input.answer,
-                answer_chunks: input.answer_chunks,
-                alias: input.alias,
-                mode: input.mode,
-                call_operator: input.call_operator,
-                chunk_delay_seconds: input.chunk_delay_seconds,
-                is_call_qa_only: input.is_call_qa_only,
-            }),
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources/${input.qa_id}`,
+            body: {
+                qa: compactObject({
+                    question: input.question,
+                    alias: input.alias,
+                    mode: input.mode,
+                    callOperator: input.call_operator,
+                    chunkDelaySeconds: input.chunk_delay_seconds,
+                    isCallQaOnly: input.is_call_qa_only,
+                    answerChunks: mapQaAnswerChunks(input.answer_chunks, input.answer, false),
+                }),
+            },
         }),
     }),
     defineTool({
@@ -610,35 +713,34 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             qa_id: uuidSchema,
             explicit_confirmation: z.literal(true),
         }),
         createRequest: (input) => ({
             method: 'DELETE',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/qa-pairs/${input.qa_id}`,
-            body: { explicit_confirmation: input.explicit_confirmation },
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources/${input.qa_id}`,
         }),
     }),
     defineTool({
         name: 'besales_knowledge_qa_search',
         sideEffect: 'none',
-        closedWorld: true,
         requiredFields: ['knowledge_space_id', 'query'],
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             query: z.string().min(1),
             top_k: z.number().int().min(1).max(50).optional(),
             min_score: z.number().optional(),
         }),
         createRequest: (input) => ({
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/qa-pairs/search`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources/search`,
             body: compactObject({
                 query: input.query,
-                top_k: input.top_k,
-                min_score: input.min_score,
+                sourceType: 'QA',
+                topK: input.top_k,
+                minScore: input.min_score,
             }),
         }),
     }),
@@ -649,47 +751,46 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            source_space_id: uuidSchema,
+            source_space_id: knowledgeSpaceIdSchema,
             qa_id: uuidSchema,
-            target_space_id: uuidSchema,
+            target_space_id: knowledgeSpaceIdSchema,
             explicit_confirmation: z.literal(true),
         }),
         createRequest: (input) => ({
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.source_space_id}/qa-pairs/${input.qa_id}/move`,
+            path: `/knowledge-spaces/${input.source_space_id}/sources/${input.qa_id}/move`,
             body: {
-                target_space_id: input.target_space_id,
-                explicit_confirmation: input.explicit_confirmation,
+                targetSpaceId: input.target_space_id,
             },
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Move = delete + recreate в новом knowledge space. Возвращается новый ID — обнови ссылки в caller-коде.',
-            'Pinecone vectors переиндексируются: старый embedding удаляется из source namespace, новый создаётся в target.',
-            'Alias НЕ переносится (unique-per-workspace constraint).',
+            'Источник перенесён транзакционно в новый knowledge space.',
+            'ID источника, alias и существующие chunks сохраняются; ссылки обновлять не нужно.',
+            'Перенос не запускает переиндексацию.',
         ]),
     }),
     // ----- v1.5 Increment 2: Websites (4 tools) -----
     defineTool({
         name: 'besales_knowledge_website_add',
-        sideEffect: 'write',
+        sideEffect: 'spend',
         requiredFields: ['knowledge_space_id', 'url'],
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             url: z.string().url(),
             display_name: z.string().optional(),
         }),
         createRequest: (input) => ({
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/websites`,
-            body: compactObject({
-                url: input.url,
-                display_name: input.display_name,
-            }),
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources`,
+            body: {
+                sourceType: 'WEBSITE',
+                name: input.display_name ?? input.url,
+                website: { url: input.url },
+            },
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'SYNC operation — может занять несколько секунд для краулинга + chunking + Pinecone upsert.',
-            'Idempotency: повторный POST с тем же URL вернёт existing site, replaced=true. FAILED перезапускается автоматически.',
-            'Status: PENDING → CRAWLING → PROCESSING → COMPLETED | FAILED.',
+            'WEBSITE source создан в статусе PENDING; crawl и индексация выполняются асинхронно.',
+            'Опрашивай besales_knowledge_website_get до status=ACTIVE либо FAILED.',
         ]),
     }),
     defineTool({
@@ -700,15 +801,16 @@ export const knowledgeTools = [
         requiredFields: ['knowledge_space_id'],
         defaultWorkspaceId: true,
         schema: z.object({
+            page: retiredKnowledgePageSchema,
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             status: z.enum(['PENDING', 'CRAWLING', 'PROCESSING', 'COMPLETED', 'FAILED']).optional(),
-            page: z.number().int().min(1).optional(),
+            cursor: z.string().min(1).optional(),
             limit: z.number().int().min(1).max(100).optional(),
         }),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/websites${buildListQuery({ status: input.status, page: input.page, limit: input.limit })}`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources${buildSourceListQuery('WEBSITE', { status: mapWebsiteStatus(input.status), limit: input.limit, cursor: input.cursor })}`,
         }),
     }),
     defineTool({
@@ -718,12 +820,12 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             website_id: uuidSchema,
         }),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/websites/${input.website_id}`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources/${input.website_id}`,
         }),
     }),
     defineTool({
@@ -733,14 +835,13 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             website_id: uuidSchema,
             explicit_confirmation: z.literal(true),
         }),
         createRequest: (input) => ({
             method: 'DELETE',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/websites/${input.website_id}`,
-            body: { explicit_confirmation: input.explicit_confirmation },
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources/${input.website_id}`,
         }),
     }),
     // ============================================================
@@ -748,12 +849,12 @@ export const knowledgeTools = [
     // ============================================================
     defineTool({
         name: 'besales_knowledge_table_link',
-        sideEffect: 'write',
+        sideEffect: 'spend',
         requiredFields: ['knowledge_space_id', 'source', 'display_name'],
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             source: knowledgeTableSourceSchema,
             display_name: z.string(),
             header_row_index: z.number().int().min(1).optional(),
@@ -765,25 +866,26 @@ export const knowledgeTools = [
         }),
         createRequest: (input) => ({
             method: 'POST',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/tables`,
-            body: compactObject({
-                source: {
-                    kind: input.source.kind,
-                    spreadsheet_url: input.source.spreadsheet_url,
-                    table_schema: input.source.table_schema,
-                },
-                display_name: input.display_name,
-                header_row_index: input.header_row_index,
-                cache_ttl_seconds: input.cache_ttl_seconds,
-                use_vector_index: input.use_vector_index,
-                vector_top_k: input.vector_top_k,
-                vector_embed_max_chars: input.vector_embed_max_chars,
-                access: input.access,
-            }),
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources`,
+            body: {
+                sourceType: 'TABLE',
+                name: input.display_name,
+                table: compactObject({
+                    tableName: input.display_name,
+                    type: 'GOOGLE_SHEETS',
+                    url: input.source.spreadsheet_url,
+                    access: input.access,
+                    headerRowIndex: input.header_row_index === undefined ? undefined : input.header_row_index - 1,
+                    cacheTtlSeconds: input.cache_ttl_seconds,
+                    useVectorIndex: input.use_vector_index,
+                    vectorTopK: input.vector_top_k,
+                    vectorEmbedMaxChars: input.vector_embed_max_chars,
+                }),
+            },
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Knowledge table связана. Если URL уже существовал, replaced=true (idempotency by namespace+url).',
-            'Для индексации в Pinecone установи use_vector_index=true и вызови besales_knowledge_table_reindex.',
+            'TABLE source создан в статусе PENDING.',
+            'Для row-level vector retrieval включи use_vector_index и вызови besales_knowledge_table_reindex.',
         ]),
     }),
     defineTool({
@@ -794,15 +896,16 @@ export const knowledgeTools = [
         requiredFields: ['knowledge_space_id'],
         defaultWorkspaceId: true,
         schema: z.object({
+            page: retiredKnowledgePageSchema,
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             is_active: z.boolean().optional(),
-            page: z.number().int().min(1).optional(),
+            cursor: z.string().min(1).optional(),
             limit: z.number().int().min(1).max(100).optional(),
         }),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/tables${buildListQuery({ is_active: input.is_active, page: input.page, limit: input.limit })}`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources${buildSourceListQuery('TABLE', { isActive: input.is_active, limit: input.limit, cursor: input.cursor })}`,
         }),
     }),
     defineTool({
@@ -812,12 +915,12 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             table_id: uuidSchema,
         }),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/tables/${input.table_id}`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources/${input.table_id}`,
         }),
     }),
     defineTool({
@@ -827,9 +930,9 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             table_id: uuidSchema,
-            // source присутствует только для validation (URL иммутабельный).
+            // NATIVE/table_schema остаются неподдержанными, GOOGLE_SHEETS URL патчабелен.
             source: knowledgeTableSourceSchema.optional(),
             display_name: z.string().optional(),
             header_row_index: z.number().int().min(1).optional(),
@@ -840,29 +943,29 @@ export const knowledgeTools = [
             access: z.enum(['PUBLIC', 'PRIVATE']).optional(),
             is_active: z.boolean().optional(),
         }),
-        createRequest: (input) => ({
-            method: 'PATCH',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/tables/${input.table_id}`,
-            body: compactObject({
-                source: input.source
-                    ? {
-                        kind: input.source.kind,
-                        spreadsheet_url: input.source.spreadsheet_url,
-                        table_schema: input.source.table_schema,
-                    }
-                    : undefined,
-                display_name: input.display_name,
-                header_row_index: input.header_row_index,
-                cache_ttl_seconds: input.cache_ttl_seconds,
-                use_vector_index: input.use_vector_index,
-                vector_top_k: input.vector_top_k,
-                vector_embed_max_chars: input.vector_embed_max_chars,
-                access: input.access,
-                is_active: input.is_active,
-            }),
-        }),
+        createRequest: (input) => {
+            return {
+                method: 'PATCH',
+                path: `/knowledge-spaces/${input.knowledge_space_id}/sources/${input.table_id}`,
+                body: compactObject({
+                    name: input.display_name,
+                    table: compactObject({
+                        tableName: input.display_name,
+                        type: input.source?.kind,
+                        url: input.source?.spreadsheet_url,
+                        access: input.access,
+                        headerRowIndex: input.header_row_index === undefined ? undefined : input.header_row_index - 1,
+                        cacheTtlSeconds: input.cache_ttl_seconds,
+                        useVectorIndex: input.use_vector_index,
+                        vectorTopK: input.vector_top_k,
+                        vectorEmbedMaxChars: input.vector_embed_max_chars,
+                        isActive: input.is_active,
+                    }),
+                }),
+            };
+        },
         enhanceResponse: (response) => withInstructions(response, [
-            'source.url иммутабельный — для смены URL используй delete + create.',
+            'source.spreadsheet_url обновляет URL существующей GOOGLE_SHEETS-таблицы.',
         ]),
     }),
     defineTool({
@@ -872,36 +975,33 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             table_id: uuidSchema,
             explicit_confirmation: z.literal(true),
         }),
         createRequest: (input) => ({
             method: 'DELETE',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/tables/${input.table_id}`,
-            body: { explicit_confirmation: input.explicit_confirmation },
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources/${input.table_id}`,
         }),
     }),
     defineTool({
         name: 'besales_knowledge_table_reindex',
-        sideEffect: 'spend',
         verifyWithToolName: 'besales_knowledge_table_reindex_status',
+        sideEffect: 'spend',
         requiredFields: ['knowledge_space_id', 'table_id', 'explicit_confirmation'],
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             table_id: uuidSchema,
             explicit_confirmation: z.literal(true),
         }),
         createRequest: (input) => ({
             method: 'POST',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/tables/${input.table_id}/reindex`,
-            body: { explicit_confirmation: input.explicit_confirmation },
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources/${input.table_id}/reindex`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Полная переиндексация выполняется в фоне (delete vectors + re-fetch CSV + re-embed + upsert). Сохрани job_id из ответа.',
-            'Первую проверку сделай через 10–30 секунд через besales_knowledge_table_reindex_status; повторяй до COMPLETED, FAILED или EXPIRED.',
+            'Переиндексация поставлена в knowledge-indexing очередь; повторный живой job дедуплицируется.',
         ]),
     }),
     defineTool({
@@ -911,38 +1011,46 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             table_id: uuidSchema,
         }),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/tables/${input.table_id}/reindex/status`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}/sources/${input.table_id}/reindex/status`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'QUEUED/RUNNING — подожди 10–30 секунд и проверь снова. COMPLETED/FAILED/EXPIRED — терминальные состояния.',
-            'EXPIRED означает, что retained job уже удалён; не считай это доказательством успеха или ошибки.',
+            'QUEUED/RUNNING — подожди 10–30 секунд и спроси снова; COMPLETED/FAILED — исход известен.',
+            // ⛔ Значение EXPIRED в v2 означает ДРУГОЕ, чем у прежнего сервера. Там оно означало «след
+            // задания очереди уже удалён хранением», то есть исход неизвестен. Здесь статус считается
+            // по прогону РЕСУРСА, и удержание задания на ответ не влияет: EXPIRED означает, что
+            // переиндексации этой цели не было вовсе. Промолчав, инструмент склеил бы «не запускали» с
+            // «не знаем» — за первым идут и запускают, за вторым ждут.
+            'EXPIRED — прогона по этой цели нет: переиндексацию не запускали. Это не «исход неизвестен».',
         ]),
     }),
     defineTool({
         name: 'besales_knowledge_namespace_reindex',
-        sideEffect: 'spend',
         verifyWithToolName: 'besales_knowledge_namespace_reindex_status',
+        sideEffect: 'spend',
+        // Жёсткий гейт: переиндексация ВСЕГО пространства знаний — та же операция, что у одной
+        // таблицы, только по всему набору источников. Гейт стоял на частном случае и отсутствовал
+        // на общем.
         requiredFields: ['knowledge_space_id', 'explicit_confirmation'],
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
             types: z.array(z.enum(['qa', 'doc'])).optional(),
             explicit_confirmation: z.literal(true),
         }),
         createRequest: (input) => ({
             method: 'POST',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/reindex`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}/reindex`,
             body: compactObject({ types: input.types }),
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'Фоновый re-embed существующих Q&A + чанков документов из Postgres → Pinecone. Сохрани job_id из ответа. types опционально (по умолчанию qa+doc).',
-            'Первую проверку сделай через 10–30 секунд через besales_knowledge_namespace_reindex_status; повторяй до COMPLETED, FAILED или EXPIRED.',
+            'Фоновая переиндексация QA/DOCUMENT sources в pgvector через knowledge-indexing очередь.',
+            'types опционально; по умолчанию обрабатываются qa и doc. TABLE/WEBSITE не входят.',
         ]),
     }),
     defineTool({
@@ -952,15 +1060,16 @@ export const knowledgeTools = [
         defaultWorkspaceId: true,
         schema: z.object({
             workspace_id: uuidSchema.optional(),
-            knowledge_space_id: uuidSchema,
+            knowledge_space_id: knowledgeSpaceIdSchema,
         }),
         createRequest: (input) => ({
             method: 'GET',
-            path: `/workspaces/${input.workspace_id}/knowledge-spaces/${input.knowledge_space_id}/reindex/status`,
+            path: `/knowledge-spaces/${input.knowledge_space_id}/reindex/status`,
         }),
         enhanceResponse: (response) => withInstructions(response, [
-            'QUEUED/RUNNING — подожди 10–30 секунд и проверь снова. COMPLETED/FAILED/EXPIRED — терминальные состояния.',
-            'После COMPLETED подожди eventual consistency Pinecone и проверь поиск чтением.',
+            'QUEUED/RUNNING — подожди 10–30 секунд и спроси снова; COMPLETED/FAILED — исход известен.',
+            'EXPIRED — прогона по этому пространству нет: переиндексацию не запускали. Это не «исход неизвестен».',
+            'progress считает ИСТОЧНИКИ прогона; removed — источники, удалённые или перенесённые во время него.',
         ]),
     }),
 ];