@naparnik/mcp 0.10.52 → 0.10.53

package/dist/tool-1kGke9dT.d.ts

@@ -0,0 +1,374 @@
+/** Определение ресурса в MCP */
+interface McpResource {
+    /** URI ресурса (уникальный идентификатор) */
+    uri: string;
+    /** Человекочитаемое имя */
+    name: string;
+    /** Описание ресурса (опционально) */
+    description?: string;
+    /** MIME-тип содержимого (опционально) */
+    mimeType?: string;
+}
+/** Текстовое содержимое ресурса */
+interface McpResourceTextContent {
+    uri: string;
+    mimeType?: string;
+    text: string;
+    /** Метаданные расширений: у виджета MCP Apps здесь `ui.csp`, `ui.prefersBorder` */
+    _meta?: Record<string, unknown>;
+}
+/** Бинарное содержимое ресурса */
+interface McpResourceBlobContent {
+    uri: string;
+    mimeType?: string;
+    /** Base64-кодированные данные */
+    blob: string;
+}
+/** Содержимое ресурса — текст или бинарные данные */
+type McpResourceItemContent = McpResourceTextContent | McpResourceBlobContent;
+
+/**
+ * Типы и утилиты для инструментов агентного цикла.
+ *
+ * Порт из packages/agent-core/src/tools/tool.ts с расширениями:
+ * - readOnly флаг для параллельного выполнения
+ * - group — категория инструмента для фильтрации и UI
+ * - emitProgress в ToolContext — стриминг прогресса без возврата из execute
+ * - agentId в ToolContext — для мульти-агентных сценариев
+ */
+/**
+ * Примитивный тип JSON Schema для параметра инструмента.
+ * Ограниченное подмножество JSON Schema — только то, что понимают LLM-провайдеры.
+ */
+type JSONSchemaType = {
+    type: 'string';
+    description?: string;
+    enum?: string[];
+    /** Максимальная длина строки — защита от DoS через гигантский input. */
+    maxLength?: number;
+    /** Минимальная длина строки. */
+    minLength?: number;
+} | {
+    type: 'number';
+    description?: string;
+} | {
+    type: 'integer';
+    description?: string;
+} | {
+    type: 'boolean';
+    description?: string;
+} | {
+    type: 'array';
+    items: JSONSchemaType;
+    description?: string;
+} | {
+    type: 'object';
+    properties: Record<string, JSONSchemaType>;
+    required?: string[];
+    description?: string;
+    /**
+     * Разрешить произвольные ключи в объекте (валидный JSON Schema keyword).
+     * Полезно для object-параметров с динамическими полями (params интеграций),
+     * где нужно явно подсказать LLM что это словарь произвольных ключей.
+     * При использовании совмещать с `properties: {}` для соответствия общему
+     * стилю кодовой базы.
+     */
+    additionalProperties?: boolean;
+};
+/** Схема входных параметров инструмента (JSON Schema объект верхнего уровня) */
+interface ToolInputSchema {
+    type: 'object';
+    properties: Record<string, JSONSchemaType>;
+    required?: string[];
+}
+/**
+ * Контекст, передаваемый в каждый вызов инструмента.
+ *
+ * readFileTimestamps — критически важен для защиты от устаревших записей:
+ * перед перезаписью файла инструменты write/edit проверяют, что файл был
+ * прочитан в текущей сессии и не изменился с момента чтения.
+ */
+interface ToolContext {
+    /** Уникальный идентификатор текущей сессии */
+    sessionId: string;
+    /** Сигнал отмены — инструменты должны проверять его при длительных операциях */
+    abortSignal?: AbortSignal;
+    /** Среда выполнения — влияет на доступные операции */
+    env: 'electron' | 'server' | 'test';
+    /** Рабочая директория для файловых операций */
+    workingDirectory?: string;
+    /**
+     * Временные метки последнего чтения файлов (путь → timestamp в мс).
+     *
+     * Заполняется инструментом чтения при каждом успешном обращении.
+     * Инструменты записи и редактирования проверяют этот словарь перед записью,
+     * чтобы обнаружить устаревшие правки (stale write detection).
+     *
+     * Ключ: абсолютный путь к файлу.
+     * Значение: Date.now() в момент прочтения.
+     */
+    readFileTimestamps: Record<string, number>;
+    /**
+     * Содержимое прочитанных файлов (путь → текст).
+     *
+     * Опциональный словарь для post-compact restore — заполняется инструментами
+     * чтения когда featureGates.postCompactRestore=true.
+     * Позволяет postCompactRestore() восстановить содержимое без повторного чтения с диска.
+     *
+     * Ключ: абсолютный путь к файлу (совпадает с readFileTimestamps).
+     * Значение: текстовое содержимое на момент последнего чтения.
+     */
+    readFileContents?: Record<string, string>;
+    /**
+     * Функция для эмиссии событий прогресса во время выполнения инструмента.
+     * Позволяет стримить промежуточные результаты в UI без завершения execute().
+     * Отсутствует, если потребитель не поддерживает стриминг прогресса.
+     */
+    emitProgress?: (content: string) => void;
+    /**
+     * Идентификатор агента в мульти-агентных сценариях.
+     * Используется для изоляции состояния между агентами и корректного логирования.
+     */
+    agentId?: string;
+    /**
+     * Программа, которая нас позвала: `clientInfo` из рукопожатия MCP
+     * («claude-ai», «codex-mcp-client»). Нужна отчёту о поломке
+     * (`crash-report.ts`): одна и та же беда у Claude Desktop и у Codex — это
+     * часто две разные беды. Нет — хост не представился.
+     */
+    host?: {
+        name: string;
+        version: string;
+    };
+}
+/**
+ * Текстовый блок в результате инструмента.
+ * Используется внутри mixed-content для аннотаций к изображениям.
+ */
+interface ToolTextBlock {
+    type: 'text';
+    text: string;
+}
+/**
+ * Блок изображения в результате инструмента (vision support).
+ *
+ * Tool возвращает картинку «по-человечески»: base64 + mediaType.
+ * Конвертация в нативный формат API провайдера (Anthropic source/Google inlineData/
+ * OpenAI image_url) — обязанность нижележащего слоя (tool-dispatch + LLM provider).
+ *
+ * Используется для:
+ * - чтения сканированных документов (vision fallback при отказе OCR)
+ * - анализа скриншотов
+ * - обработки фото с телефона пользователя
+ */
+interface ToolImageBlock {
+    type: 'image';
+    /** Base64-кодированные данные изображения (без префикса data:...) */
+    base64: string;
+    /** MIME-тип — модели нужен корректный формат для декодирования */
+    mediaType: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+}
+/**
+ * Блок-ссылка на изображение в vision-cache (disk storage).
+ *
+ * Альтернатива ToolImageBlock когда vision-cache сконфигурирован
+ * (`ctx.visionCache` есть). Tool пишет raw bytes в cache и возвращает
+ * file_ref вместо inline base64. Это снимает нагрузку с RAM/БД/PHP:
+ * tool_result в messages.content становится ~200 байт вместо ~500 KB.
+ *
+ * Раскрытие в base64 происходит непосредственно перед `provider.send()`
+ * через `expandVisionRefs` в `super-agent-core/src/loop/query.ts`.
+ *
+ * @see super-agent-core/src/loop/vision-cache.ts
+ */
+interface ToolImageRefBlock {
+    type: 'image_ref';
+    /** Относительный путь от rootPath: `<sessionId>/<sha256>.<ext>` */
+    pathSuffix: string;
+    mediaType: 'image/jpeg' | 'image/png' | 'image/gif' | 'image/webp';
+}
+/** Объединённый тип контентного блока в результате инструмента */
+type ToolContentBlock = ToolTextBlock | ToolImageBlock | ToolImageRefBlock;
+/**
+ * Успешный результат инструмента.
+ *
+ * Может быть простой строкой (обычный случай) или массивом блоков text+image
+ * для мультимодальных результатов (vision). Image-блоки требуются чтобы
+ * модель могла «видеть» картинку, а не получать строку base64 в text-блоке.
+ */
+interface ToolResultSuccess {
+    type: 'success';
+    content: string | ToolContentBlock[];
+    /**
+     * Данные для ВИДЖЕТА, мимо контекста модели.
+     *
+     * ⚠ РАЗДЕЛЕНИЕ НЕ РАДИ ПОРЯДКА, А РАДИ ДЕНЕГ И ТОЛКУ. Настоящий кадр ролика
+     * в base64 весит восемь килобайт; три кадра — двадцать четыре, и модель
+     * перечитывает их каждый ход, ничего в них не видя: base64 в тексте она
+     * «посмотреть» не может. Картинки нужны ГЛАЗАМ человека, то есть форме, а
+     * модели хватает названий словами. Уезжает как `structuredContent` в ответе
+     * `tools/call` — так это и разведено в спеке MCP.
+     */
+    structured?: Record<string, unknown>;
+}
+/** Результат с ошибкой без машиночитаемого кода */
+interface ToolResultErrorBase {
+    type: 'error';
+    error: string;
+}
+/** Результат с ошибкой с машиночитаемым кодом */
+interface ToolResultErrorWithCode {
+    type: 'error';
+    error: string;
+    /** Код ошибки для программной обработки (retry logic, UI, логирование) */
+    code: string;
+}
+/** Результат с ошибкой — с кодом или без */
+type ToolResultError = ToolResultErrorBase | ToolResultErrorWithCode;
+/** Финальный результат выполнения инструмента */
+type ToolResult = ToolResultSuccess | ToolResultError;
+/**
+ * Категория инструмента — для фильтрации, UI-группировки и политик доступа.
+ * Аналог group:* из конфигурации OpenClaw.
+ */
+type ToolGroup = 'fs' | 'runtime' | 'web' | 'memory' | 'knowledge' | 'ui' | 'system' | 'automation' | 'confirmation' | 'collaboration' | 'integration' | 'skill';
+/**
+ * Универсальный интерфейс инструмента агента.
+ *
+ * Инструменты регистрируются в агентском цикле и вызываются моделью
+ * по имени через механизм tool_use. Каждый инструмент описывает себя
+ * через JSON Schema и реализует функцию execute.
+ *
+ * @example
+ * ```typescript
+ * const readFileTool: Tool = {
+ *   name: 'read_file',
+ *   description: 'Читает содержимое файла по указанному пути',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: {
+ *       path: { type: 'string', description: 'Путь к файлу' }
+ *     },
+ *     required: ['path']
+ *   },
+ *   readOnly: true,
+ *   group: 'fs',
+ *   async execute(input, ctx) {
+ *     // ...
+ *   }
+ * }
+ * ```
+ */
+interface Tool<TInput = any> {
+    /** Уникальное имя инструмента (snake_case) */
+    name: string;
+    /** Человекочитаемое описание для модели */
+    description: string;
+    /**
+     * Название по-русски — для ЧЕЛОВЕКА, в отличие от `description` для модели.
+     * Уезжает хосту как `annotations.title` и показывается в настройках вместо
+     * имени из кода: без него человек читает «Choose variant», решая, разрешать
+     * ли инструмент.
+     */
+    title?: string;
+    /** JSON Schema входных параметров */
+    inputSchema: ToolInputSchema;
+    /**
+     * Флаг «только чтение».
+     * readOnly-инструменты не изменяют внешнее состояние и могут выполняться
+     * параллельно с другими readOnly-инструментами без риска конфликтов.
+     * Агентский цикл использует этот флаг для параллельного выполнения.
+     */
+    readOnly?: boolean;
+    /**
+     * Переписывает то, что у человека уже есть.
+     *
+     * По умолчанию `false`, и это не оптимизм: монтаж кладёт НОВЫЙ файл рядом с
+     * исходником, обновление держит прежнюю версию на диске, установка кладёт
+     * недостающее в свою папку — ничего из этого не затирает чужого. `true`
+     * ставится там, где вызов переписывает содержимое, которое человек считал
+     * своим: например, готовый фильтр цвета в его паке стиля.
+     */
+    destructive?: boolean;
+    /**
+     * Виджет инструмента (MCP Apps): адрес `ui://…` ресурса, HTML которого хост
+     * рисует в ленте вместо текстового ответа. Ресурс регистрируется на
+     * сервере отдельно (`McpServer.addResource`); здесь только ссылка, и в
+     * `tools/list` она уезжает как `_meta.ui.resourceUri`.
+     */
+    ui?: {
+        resourceUri: string;
+    };
+    /**
+     * Флаг «обратимое действие» — действие остаётся в рамках текущего диалога
+     * с этим пользователем и не выходит наружу.
+     *
+     * `true` (по умолчанию) — безопасно вызывать без явного человеческого approve:
+     *   recall, web_search, view, create_file (в workspace), send_file_to_chat,
+     *   send_task_to_agent (внутреннему агенту), bash_tool (sandbox-изолирован),
+     *   integration_call с read-методами.
+     *
+     * `false` — действие выходит наружу и должно сопровождаться явной формулировкой
+     *   подтверждения от пользователя (через диалог) перед выполнением:
+     *   отправка наружу (письмо/SMS внешнему адресату), запись в CRM/ERP,
+     *   финансовые операции, удаление persistent данных.
+     *
+     * Используется для генерации списков в system prompt и (в будущем)
+     * для автоматического enforcement в loop.
+     */
+    reversible?: boolean;
+    /**
+     * Группа инструмента — для фильтрации, UI-группировки и политик доступа.
+     * Соответствует group:* из конфигурации OpenClaw sandbox.
+     */
+    group?: ToolGroup;
+    /**
+     * Флаг «отложенная загрузка схемы» (lazy tool loading).
+     *
+     * Если `true` — JSON Schema этого tool'а НЕ передаётся в LLM API в каждом
+     * запросе. Модель видит только имя + 1-строчное описание в специальном
+     * блоке `<deferred_tools>` системного промпта и подгружает полную схему
+     * через ToolSearch tool когда нужно её вызвать.
+     *
+     * Используется для редких/тяжёлых tools чтобы экономить токены input'а:
+     * - integration_call (динамический, описание ~жирное)
+     * - browse_page (тяжёлый prompt)
+     * - observer_*, credential_*, skill_* (admin-flow, редко)
+     *
+     * НЕ deferr'им: bash, view, read, write, edit, grep, glob, web_*,
+     * todo_write, Task, ToolSearch, memory tools — это core.
+     *
+     * После вызова ToolSearch с `select:<name>` или релевантного keyword-search
+     * — схема активируется на оставшийся срок жизни сессии (обычный tools[] payload).
+     */
+    isDeferred?: boolean;
+    /**
+     * Максимальный размер `tool_result.content` в символах ДО persistence-cap.
+     *
+     * Семантика 1-в-1 как у Claude Code 2.1.88 (`Tool.ts:466`):
+     * - Эффективный порог = `min(maxResultSizeChars, DEFAULT_MAX_RESULT_SIZE_CHARS=50_000)`.
+     *   Tool может объявить **БОЛЬШЕ** 50K — глобальный cap всё равно применит 50K.
+     *   Tool может объявить **МЕНЬШЕ** 50K (например Grep 20K) — будет применён tool-specific лимит.
+     * - `Infinity` = hard opt-out, никогда не persist (для FileRead/view —
+     *   нет смысла записывать файл во второй файл).
+     * - `undefined` = поведение как 100_000 (clamp до 50K).
+     *
+     * Применяется в `maybePersistLargeToolResult` (слой A) сразу после
+     * выполнения tool'а в `tool-dispatch.ts`, ДО того как tool_result попадёт
+     * в messages history. Большие результаты пишутся на диск
+     * `<rootPath>/<sessionId>/<tool_use_id>.{json,txt}`, в messages летит
+     * preview ~2000 символов внутри `<persisted-output>` тегов.
+     *
+     * Подробности — `new-version/docs/claude-code-optimizations.md` (Слой A).
+     */
+    maxResultSizeChars?: number;
+    /**
+     * Выполняет инструмент с заданными параметрами.
+     * @param input - Валидированные входные параметры
+     * @param ctx - Контекст выполнения (сессия, сигнал отмены, среда, временные метки файлов)
+     * @returns Результат выполнения или ошибка
+     */
+    execute(input: TInput, ctx: ToolContext): Promise<ToolResult>;
+}
+
+export type { McpResource as M, Tool as T, McpResourceItemContent as a, ToolContext as b, ToolResult as c, ToolInputSchema as d };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naparnik/mcp",
-  "version": "0.10.52",
+  "version": "0.10.53",
   "description": "MCP-сервер Напарника: монтаж вертикального видео на машине пользователя — паузы, субтитры, герой на новом фоне, звук. Видео никуда не уезжает.",
   "license": "SEE LICENSE IN LICENSE.md",
   "private": false,