@naparnik/mcp 0.10.21 → 0.10.25

package/dist/index.d.ts

@@ -119,748 +119,856 @@ declare class NaparnikApiClient {
     private parse;
 }
 
+/** Определение ресурса в 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;
+
 /**
- * Где внутри распакованной портативной сборки лежит сам интерпретатор.
- *
- * ⚠ ТРИ ВАРИАНТА, А НЕ ДВА, И РОВНО ТЕ ЖЕ, ЧТО У ДВИЖКА. Источник правды —
- * `engine/shell-contract.json` → `portable_python.inside`: оттуда их берёт и
- * питон (`engine/setup/python_finder.py`). Копия здесь неизбежна — питон мы
- * ищем ДО того, как есть чем запустить питон, — но прошлая копия знала два
- * варианта из трёх: на сборке, где внутри лежит только `bin/python`, движок
- * питон видел, а сервер MCP нет. Правится сначала JSON, потом сюда; расхождение
- * ловит тест границы (`engine.test.ts`) сверкой с этим JSON.
- */
-declare const INSIDE_PYTHON: string[];
-/** Дом по умолчанию — ровно тот же литерал, что в `engine/kit/home.py`. */
-declare const DEFAULT_HOME = "~/.naparnik";
-/**
- * Шаги установки, которые идут минутами и часами: их нельзя держать внутри
- * вызова инструмента. Секундами считается только `check`.
- *
- * ⚠ «python» здесь вместе с портативной сборкой: шаг, который раньше лишь
- * советовал сходить на python.org, теперь может качать от 24 до 104 МБ.
- * Оставь его быстрым — и на медленной связи клиентская программа оборвала бы
- * вызов по своему таймауту, а скачивание осталось бы сиротой; повтор начал бы
- * второе.
- */
-declare const LONG_STEPS: Set<string>;
-/**
- * Все шаги установки, которые понимает движок.
- *
- * ⚠ ЭТО ЗЕРКАЛО `STEPS` движка, и оно уже один раз разошлось: движок печатал
- * «Шаг установки „вырез“», а здешний список о таком шаге не знал — клиент
- * оказывался в тупике, потому что инструмент не принимал значение, которое
- * движок сам же и назвал. Источник правды — `engine/shell-contract.json` →
- * `install_steps`: оттуда `STEPS` берёт и `setup/install.py`. Правится сверху
- * вниз: сначала JSON, потом сюда. Расхождение сторожит `engine.test.ts` сверкой
- * с этим JSON.
- */
-declare const INSTALL_STEPS: string[];
-/**
- * Паспорт пака: имена этапов, список моделей, чем запускать.
+ * Типы и утилиты для инструментов агентного цикла.
  *
- * Спрашивается у движка ОДНОЙ командой, а не переписывается сюда. Пока его не
- * было, списки этапов и моделей жили здесь второй правдой, а точка входа была
- * прибита строкой "scripts/edit.py".
+ * Порт из packages/agent-core/src/tools/tool.ts с расширениями:
+ * - readOnly флаг для параллельного выполнения
+ * - group — категория инструмента для фильтрации и UI
+ * - emitProgress в ToolContext — стриминг прогресса без возврата из execute
+ * - agentId в ToolContext — для мульти-агентных сценариев
  */
 /**
- * ⚠ ИМЕНА ПОЛЕЙ — ОТВЕТ ПИТОНА, А НЕ НАШ ОБЪЕКТ. Паспорт печатает движок
- * монтажа (`engine/passport.py` → `as_json`, команда `pack-description`), и
- * имена полей — его. Переименование здесь ничего не меняет на той стороне:
- * оболочка просто перестала бы находить поля и объявила бы «паспорт не
- * прочитан» на каждом запуске. Поля, несущие имена, сверяет с настоящими
- * `pack.json` и рецептом `tool-declaration.test.ts`.
+ * Примитивный тип JSON Schema для параметра инструмента.
+ * Ограниченное подмножество JSON Schema — только то, что понимают LLM-провайдеры.
  */
-interface PackPassport {
-    'name': string;
-    'title': string;
-    'entry': string;
-    'stages': string[];
-    'models': string[];
-    /**
-     * Движок распознавания → модель по умолчанию. Карта, а не одно имя: на
-     * видеокарте Apple берётся medium, на процессоре turbo — разница в скорости
-     * десятикратная, замерено.
-     */
-    'default_model': Record<string, string>;
+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: {}` для соответствия общему
+     * стилю кодовой базы.
      */
-    'capabilities'?: Record<string, {
-        'kind': string;
-        'about': string;
-    }>;
-}
-/** Ответ команды движка в виде, пригодном для инструмента. */
-type CommandOutcome = {
-    ok: true;
-    text: string;
-} | {
-    ok: false;
-    text: string;
+    additionalProperties?: boolean;
 };
-/** Где лежит установленная сборка движка. */
-interface EnginePlace {
-    /** Папка с `console.py`. */
-    engine: string;
-    /** Папка пака монтажа: `.venv`, `pack.json`, точка входа. */
-    pack: string;
-    /** Полный путь к `console.py`. */
-    consolePy: string;
+/** Схема входных параметров инструмента (JSON Schema объект верхнего уровня) */
+interface ToolInputSchema {
+    type: 'object';
+    properties: Record<string, JSONSchemaType>;
+    required?: string[];
 }
-declare class Engine {
-    private readonly env;
-    private passportCache;
-    private versionAtStart;
-    private pythonChecked;
-    constructor(env?: NodeJS.ProcessEnv);
+/**
+ * Контекст, передаваемый в каждый вызов инструмента.
+ *
+ * readFileTimestamps — критически важен для защиты от устаревших записей:
+ * перед перезаписью файла инструменты write/edit проверяют, что файл был
+ * прочитан в текущей сессии и не изменился с момента чтения.
+ */
+interface ToolContext {
+    /** Уникальный идентификатор текущей сессии */
+    sessionId: string;
+    /** Сигнал отмены — инструменты должны проверять его при длительных операциях */
+    abortSignal?: AbortSignal;
+    /** Среда выполнения — влияет на доступные операции */
+    env: 'electron' | 'server' | 'test';
+    /** Рабочая директория для файловых операций */
+    workingDirectory?: string;
     /**
-     * Корень Напарника на машине клиента.
+     * Временные метки последнего чтения файлов (путь → timestamp в мс).
      *
-     * ⚠ ПУСТАЯ СТРОКА — ЭТО «НЕ ЗАДАНО», А НЕ «ТЕКУЩАЯ ПАПКА». Прочитай мы её
-     * как путь — дом уехал бы в рабочий каталог процесса, и питон с TypeScript
-     * разошлись бы в том, где вообще живут задачи и стиль. Тот же `or` стоит в
-     * `engine/kit/home.py`.
+     * Заполняется инструментом чтения при каждом успешном обращении.
+     * Инструменты записи и редактирования проверяют этот словарь перед записью,
+     * чтобы обнаружить устаревшие правки (stale write detection).
      *
-     * ⚠ И ШАБЛОН — ТОЖЕ «НЕ ЗАДАНО», см. `fromHost` в `config.ts`. Пустое поле
-     * настроек приезжает от Claude Desktop строкой `${user_config.engine_home}`,
-     * и до 2026-09-10 движок искался в папке с таким именем: у человека он лежал
-     * в `~/.naparnik`, а расширение отвечало «не установлен — монтировать нечем».
+     * Ключ: абсолютный путь к файлу.
+     * Значение: Date.now() в момент прочтения.
      */
-    home(): string;
+    readFileTimestamps: Record<string, number>;
     /**
-     * Значение переменной окружения — или undefined, если она пуста либо не
-     * задана. Наружу нужна затем, что окружение у Движка своё (передано в
-     * конструктор), а `process.env` в тестах не тот же самый.
+     * Содержимое прочитанных файлов (путь → текст).
      *
-     * ⚠ ПУСТАЯ СТРОКА И ШАБЛОН СЧИТАЮТСЯ «НЕ ЗАДАНО» — по той же причине, что
-     * и у дома: незаполненное поле настроек приезжает от Claude Desktop либо
-     * пустым, либо строкой `${user_config.…}` (`fromHost` в `config.ts`).
+     * Опциональный словарь для post-compact restore — заполняется инструментами
+     * чтения когда featureGates.postCompactRestore=true.
+     * Позволяет postCompactRestore() восстановить содержимое без повторного чтения с диска.
+     *
+     * Ключ: абсолютный путь к файлу (совпадает с readFileTimestamps).
+     * Значение: текстовое содержимое на момент последнего чтения.
      */
-    variable(name: string): string | undefined;
-    /** Папка версий движка: `<дом>/engine`. */
-    versionsDir(): string;
+    readFileContents?: Record<string, string>;
     /**
-     * Какая версия движка объявлена рабочей.
-     *
-     * Обычный ТЕКСТОВЫЙ файл, а не симлинк: создание симлинка на Windows требует
-     * режима разработчика или прав администратора, а строка в файле переносима и
-     * переименовывается атомарно.
-     *
-     * ⚠ ЗАПОМИНАЕТСЯ НА ВСЮ ЖИЗНЬ ПРОЦЕССА, И ЭТО НЕСУЩЕЕ. Так работает обещание
-     * «подмена начинки — только на старте»: обновление меняет файл `current`, а
-     * запущенный процесс продолжает считать на той версии, с которой начал.
-     * Читай мы файл каждый раз — задача, заведённая старой версией, дочитывалась
-     * бы новой. У движка кэш по отпечаткам, и в отпечаток входит код шага: смесь
-     * двух версий внутри одной задачи не упала бы, а тихо смешала результаты.
-     *
-     * `freshVersion()` даёт незакэшированное значение — она нужна ровно двум местам:
-     * самому обновлению и рассказу человеку о том, что новая версия уже готова и
-     * подхватится после перезапуска.
+     * Функция для эмиссии событий прогресса во время выполнения инструмента.
+     * Позволяет стримить промежуточные результаты в UI без завершения execute().
+     * Отсутствует, если потребитель не поддерживает стриминг прогресса.
      */
-    currentVersion(): string | null;
-    /** Что записано в файле `current` прямо сейчас, мимо памяти процесса. */
-    freshVersion(): string | null;
+    emitProgress?: (content: string) => void;
     /**
-     * Где установлен движок — или null, если нигде.
-     *
-     * Порядок: явное указание переменной (лаборатория, тесты, ручная сборка) →
-     * версионная раскладка `<дом>/engine/<текущая>`. Третьего варианта нет
-     * намеренно: каждый «а ещё поищем вот тут» — это место, где TypeScript и
-     * питон однажды разойдутся.
+     * Идентификатор агента в мульти-агентных сценариях.
+     * Используется для изоляции состояния между агентами и корректного логирования.
      */
+    agentId?: string;
     /**
-     * Указан ли движок переменной вручную.
-     *
-     * ⚠ ЭТО НЕ МЕЛОЧЬ ДЛЯ ОБНОВЛЕНИЯ. Ручной путь ПОБЕЖДАЕТ версионную
-     * раскладку, а обновление умеет только её: оно распакует новую версию в
-     * `<дом>/engine/<версия>` и переставит указатель — на который эта машина не
-     * смотрит вовсе. Получилось бы обновление, которое честно отчитывается об
-     * успехе и не меняет ничего.
+     * Программа, которая нас позвала: `clientInfo` из рукопожатия MCP
+     * («claude-ai», «codex-mcp-client»). Нужна отчёту о поломке
+     * (`crash-report.ts`): одна и та же беда у Claude Desktop и у Codex — это
+     * часто две разные беды. Нет — хост не представился.
      */
-    pathSetByHand(): boolean;
-    place(): EnginePlace | null;
-    /** Явное место кандидата: не читает и не меняет current. */
-    placeForVersion(version: string): EnginePlace | null;
-    private assemble;
+    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[];
     /**
-     * Почему монтировать нечем — словами для нейросети клиента.
+     * Данные для ВИДЖЕТА, мимо контекста модели.
      *
-     * ⚠ ЭТО НЕ ОШИБКА ИНСТРУМЕНТА, а состояние машины. Отдай мы сюда `spawn
-     * python3 ENOENT` или молчание — модель начала бы извиняться и гадать
-     * вместо того, чтобы объяснить человеку один недостающий шаг.
+     * ⚠ РАЗДЕЛЕНИЕ НЕ РАДИ ПОРЯДКА, А РАДИ ДЕНЕГ И ТОЛКУ. Настоящий кадр ролика
+     * в base64 весит восемь килобайт; три кадра — двадцать четыре, и модель
+     * перечитывает их каждый ход, ничего в них не видя: base64 в тексте она
+     * «посмотреть» не может. Картинки нужны ГЛАЗАМ человека, то есть форме, а
+     * модели хватает названий словами. Уезжает как `structuredContent` в ответе
+     * `tools/call` — так это и разведено в спеке MCP.
      */
-    whyNoEngine(): string;
+    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;
     /**
-     * Забыть, где движок, — после того как мы его только что поставили.
-     *
-     * ⚠ БЕЗ ЭТОГО ПЕРВАЯ УСТАНОВКА НЕ ВИДНА САМОЙ СЕБЕ. `currentVersion`
-     * запоминается на всю жизнь процесса нарочно (подмена начинки — только на
-     * старте), и сразу после доставки следующий же вызов получил бы
-     * закэшированное «версии нет» про версию, которую мы сами и разложили.
-     * Здесь это не нарушает обещания: смешивать две версии внутри задачи нечем,
-     * до этого момента версии не было вовсе.
+     * Название по-русски — для ЧЕЛОВЕКА, в отличие от `description` для модели.
+     * Уезжает хосту как `annotations.title` и показывается в настройках вместо
+     * имени из кода: без него человек читает «Choose variant», решая, разрешать
+     * ли инструмент.
      */
-    forgetPlace(): void;
-    /** Забыть ответ на вопрос «есть ли питон» — после того как мы его принесли. */
-    forgetPython(): void;
-    /** Python окружения пака — им считается монтаж. Может ещё не существовать. */
-    packPython(): string | null;
+    title?: string;
+    /** JSON Schema входных параметров */
+    inputSchema: ToolInputSchema;
     /**
-     * Портативный python, который движок доставил сам (шаг «python» установки).
-     *
-     * ⚠ ЗНАТЬ ПРО НЕГО ОБЯЗАНА И ЭТА СТОРОНА. Он лежит в `<дом>/bin/python` и в
-     * PATH не попадает намеренно — PATH человека мы не трогаем. Пропусти его
-     * здесь, и получится: установка принесла питон, окружение на нём собралось,
-     * а сервер MCP по-прежнему зовёт системный «python», которого нет или
-     * который заглушка из Microsoft Store.
+     * Флаг «только чтение».
+     * readOnly-инструменты не изменяют внешнее состояние и могут выполняться
+     * параллельно с другими readOnly-инструментами без риска конфликтов.
+     * Агентский цикл использует этот флаг для параллельного выполнения.
      */
-    ourPython(): string | null;
+    readOnly?: boolean;
     /**
-     * Python для команд движка.
+     * Переписывает то, что у человека уже есть.
      *
-     * Окружения пака может не быть вовсе — именно это и проверяет `check_setup`,
-     * поэтому запускать проверку его питоном нельзя: получилась бы курица и
-     * яйцо. Команды движка написаны на голой стандартной библиотеке и идут
-     * системным python'ом, когда своего ещё нет.
+     * По умолчанию `false`, и это не оптимизм: монтаж кладёт НОВЫЙ файл рядом с
+     * исходником, обновление держит прежнюю версию на диске, установка кладёт
+     * недостающее в свою папку — ничего из этого не затирает чужого. `true`
+     * ставится там, где вызов переписывает содержимое, которое человек считал
+     * своим: например, готовый фильтр цвета в его паке стиля.
      */
-    enginePython(): string;
-    /** Python подготовки кандидата — намеренно без fallback на venv старого пака. */
-    bootstrapPython(): string;
-    /** Python ровно названного кандидата, а не текущей версии. */
-    candidatePython(place: EnginePlace): string | null;
+    destructive?: boolean;
     /**
-     * Среда для КАЖДОГО питона, которого мы запускаем.
-     *
-     * ⚠ БЕЗ ЭТОГО НА WINDOWS НЕ РАБОТАЕТ НИЧЕГО. Пока в питоне не включён режим
-     * UTF-8, он печатает в кодовой странице системы (cp1251 на русской, cp1252
-     * на английской), а Node декодирует ребёнка как UTF-8 — и весь ответ
-     * приезжал нечитаемым: «????? ???: /??? ??????.mp4». Отдельно ломался
-     * preview: строка JSON у нас с русскими ключами, и поле `файл` выходило
-     * undefined. Свой код мы чиним вызовом (`engine/kit/encoding.py`), а чужие
-     * библиотеки внутри того же процесса — только средой. Нужны оба заслона.
+     * Виджет инструмента (MCP Apps): адрес `ui://…` ресурса, HTML которого хост
+     * рисует в ленте вместо текстового ответа. Ресурс регистрируется на
+     * сервере отдельно (`McpServer.addResource`); здесь только ссылка, и в
+     * `tools/list` она уезжает как `_meta.ui.resourceUri`.
      */
-    pythonEnv(): NodeJS.ProcessEnv;
+    ui?: {
+        resourceUri: string;
+    };
     /**
-     * Есть ли на машине python вообще — и словами, если нет.
+     * Флаг «обратимое действие» — действие остаётся в рамках текущего диалога
+     * с этим пользователем и не выходит наружу.
      *
-     * Весь движок (включая проверку и установку) идёт через запуск python'а.
-     * Когда его нет, `execFile` бросает ENOENT, и клиентской нейросети
-     * доставалось «spawn python3 ENOENT» — текст, из которого человеку не понять
-     * ничего. Шаг «python», написанный ровно для этого случая, при этом
-     * недостижим по устройству: он сам запускается python'ом.
+     * `true` (по умолчанию) — безопасно вызывать без явного человеческого approve:
+     *   recall, web_search, view, create_file (в workspace), send_file_to_chat,
+     *   send_task_to_agent (внутреннему агенту), bash_tool (sandbox-изолирован),
+     *   integration_call с read-методами.
      *
-     * На Windows есть отдельная беда: в PATH лежит заглушка Microsoft Store —
-     * `python` там есть, он печатает рекламу магазина и выходит с кодом 9009.
-     * Поэтому проверяем не наличие файла, а ответ на вопрос о версии.
-     */
-    pythonTrouble(): Promise<string | null>;
-    /**
-     * Запустить команду движка и отдать её текст как есть.
+     * `false` — действие выходит наружу и должно сопровождаться явной формулировкой
+     *   подтверждения от пользователя (через диалог) перед выполнением:
+     *   отправка наружу (письмо/SMS внешнему адресату), запись в CRM/ERP,
+     *   финансовые операции, удаление persistent данных.
      *
-     * Умолчание таймаута заведомо БОЛЬШЕ внутренних таймаутов движка (самый
-     * долгий — опрос окружения пака, 180 с). Внешний таймаут короче внутреннего
-     * означает, что внутренний недостижим: пробник убивался снаружи, и его
-     * объяснение не доезжало до человека вовсе.
+     * Используется для генерации списков в system prompt и (в будущем)
+     * для автоматического enforcement в loop.
      */
-    command(args: string[], { maxBuffer, timeout, key, }?: {
-        maxBuffer?: number;
-        timeout?: number;
-        key?: string;
-    }): Promise<CommandOutcome>;
+    reversible?: boolean;
     /**
-     * Сырой запуск консоли движка. Наружу нужен затем, что часть работы
-     * (заведение задания, показ кадра) читает не текст, а JSON.
+     * Группа инструмента — для фильтрации, UI-группировки и политик доступа.
+     * Соответствует group:* из конфигурации OpenClaw sandbox.
      */
-    run(place: EnginePlace, args: string[], { maxBuffer, timeout, key, }?: {
-        maxBuffer?: number;
-        timeout?: number;
-        key?: string;
-    }): Promise<{
-        stdout: string;
-        stderr: string;
-    }>;
-    /** Запуск через явно выбранный Python нужен проверке кандидата до current. */
-    runWith(executable: string, place: EnginePlace, args: string[], { maxBuffer, timeout, key, }?: {
-        maxBuffer?: number;
-        timeout?: number;
-        key?: string;
-    }): Promise<{
-        stdout: string;
-        stderr: string;
-    }>;
-    /** Одна строка вывода команды — например, номер заведённого задания. */
-    asString(place: EnginePlace, args: string[], key?: string): Promise<string>;
+    group?: ToolGroup;
     /**
-     * Паспорт пака. Читается один раз за жизнь процесса: состав пака при
-     * работающей программе не меняется, а спрашивать его подпроцессом на каждый
-     * вызов инструмента — лишние полсекунды на ровном месте.
+     * Флаг «отложенная загрузка схемы» (lazy tool loading).
      *
-     * ⚠ ТАЙМАУТ КОРОТКИЙ, И ЭТО НЕСУЩЕЕ. Паспорт читается НА СТАРТЕ, до
-     * регистрации инструментов, — то есть внутри рукопожатия, которое клиент
-     * ждёт по своему таймауту (у Codex это 10 секунд по умолчанию). Команда
-     * честно занимает доли секунды: запустить питон и прочитать pack.json.
-     * Не уложилась — с паком что-то не так, и правильный размен здесь такой:
-     * потерять подсказки со списками моделей, но поднять сервер. Обратный
-     * размен означал бы «сервер не запустился» и молчание вместо объяснения.
+     * Если `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).
      */
-    passport(): Promise<PackPassport | null>;
+    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).
      *
-     * Предохранителя параллельности здесь нет намеренно. Он в питоне
-     * (`engine/state.slot`) — файловые замки в `<дом>/busy`. Счётчик в
-     * памяти защищал только свой процесс: Claude Desktop и Claude Code поднимают
-     * по своему, и вместе они давали вдвое больше тяжёлой работы, чем разрешено.
+     * Применяется в `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).
      */
-    background(opts: {
-        place: EnginePlace;
-        executable: string;
-        args: (id: string) => string[];
-        startJob: string[];
-        advice: string;
-        /**
-         * Ключ подписки — ТОЛЬКО этому запуску, не общей среде питона.
-         *
-         * ⚠ БЕЗ НЕГО МОНТАЖ ОТКАЗЫВАЕТ КАЖДОМУ ПЛАТЯЩЕМУ. С 2026-09-09 движок
-         * спрашивает подписку сам (`client/engine/account/subscription.py`) и берёт ключ
-         * из `NAPARNIK_API_KEY`, а `pythonEnv()` его оттуда вычищает намеренно:
-         * иначе ключ уезжает в каждого потомка питона — ffmpeg, pip, чужой код
-         * пака. Поэтому не «вернуть ключ в среду», а доложить его точечно, ровно
-         * как уже сделано у скачивания движка (`run`, поле `key`).
-         */
-        key: string | undefined;
-    }): Promise<{
-        id: string;
-    } | {
-        refusal: string;
-    }>;
+    maxResultSizeChars?: number;
     /**
-     * Файл, куда фоновая работа пишет свой stderr.
-     *
-     * Лежит в доме, а не рядом с видео: у установки видео нет вовсе, а ответ на
-     * вопрос «что она успела сказать перед смертью» нужен одинаково обоим.
-     * Держим последние `KEEP_LOGS` — полоса загрузки модели пишет сотни
-     * килобайт, и вечная папка таких файлов была бы платой человека за то, что
-     * он однажды монтировал.
+     * Выполняет инструмент с заданными параметрами.
+     * @param input - Валидированные входные параметры
+     * @param ctx - Контекст выполнения (сессия, сигнал отмены, среда, временные метки файлов)
+     * @returns Результат выполнения или ошибка
      */
-    private openLog;
+    execute(input: TInput, ctx: ToolContext): Promise<ToolResult>;
+}
+
+/**
+ * «Не спи»: компьютер не засыпает, пока идёт наша работа, и ещё хвост после.
+ *
+ * ⚠ ЗАЧЕМ. Установка качает гигабайты, монтаж идёт минутами, и человек уходит
+ * от компьютера — ровно тогда, когда тот засыпает от простоя. Проснулся —
+ * скачивание оборвано, монтаж стоит. Просьба владельца 2026-09-24: держать
+ * компьютер бодрым на ЛЮБОЙ нашей команде, не только на тяжёлой, потому что
+ * модель может думать пять минут между вызовами.
+ *
+ * ⚠ ТЕМ ЖЕ СПОСОБОМ, ЧТО ВИДЕОПЛЕЕР, А НЕ ДВИЖЕНИЕМ МЫШИ. Плеер говорит
+ * системе «я занят» её же средством. Двигать мышь на macOS можно только с
+ * разрешением «Универсального доступа» — страшное системное окно, которого
+ * человек не ждёт, — и антивирусы такое не любят. Наши средства разрешений не
+ * просят: `caffeinate` на macOS, `SetThreadExecutionState` на Windows.
+ *
+ * ⚠ ЛАМП ДВА РОДА, И ЭТО НЕ ДУБЛЬ.
+ * - Лампа вызовов — ОДНА на программу. Каждый вызов инструмента держит её, пока
+ *   идёт, после последнего она горит ещё `TAIL_MS`. Держатели — множество
+ *   жетонов, а не счётчик запусков: снять один жетон дважды нельзя, поэтому
+ *   «пятьсот раз не спи, пятьсот раз усни» разойтись не может по построению.
+ *   Привязана к НАШЕМУ процессу: умерла оболочка — лампа погасла сама.
+ * - Лампа фоновой работы (монтаж, установка) — своя у каждой и привязана к
+ *   процессу САМОЙ РАБОТЫ. Ревью плана 2026-09-24: работа переживает закрытие
+ *   Claude Desktop (`engine.ts`, `background`), а лампа, привязанная к нам,
+ *   умерла бы вместе с нами — и компьютер уснул бы посреди монтажа ровно в том
+ *   случае, ради которого всё затевалось. Гасить её не нужно: система гасит
+ *   её сама, когда процесс работы кончился.
+ *
+ * ⚠ ЗАКРЫТУЮ КРЫШКУ НОУТБУКА ЭТО НЕ ДЕРЖИТ. Обойти её можно только командой с
+ * паролем администратора, и так мы не делаем. Поэтому человеку говорится
+ * словами — `AWAY_NOTE` в ответе на запуск работы.
+ */
+
+/** Горящая лампа: погасить руками или узнать, что она погасла сама. */
+interface Lamp {
+    stop(): void;
+    onExit(cb: () => void): void;
+}
+/** Зажечь лампу, которая горит, пока жив процесс `pid`. `null` — система не умеет. */
+type Blocker = (pid: number) => Lamp | null;
+/** Время — параметром, ради теста: ожидания по таймеру в тестах запрещены. */
+interface Clock {
+    now(): number;
+    /** Позвать `fire` через `ms`; вернуть отмену. */
+    later(ms: number, fire: () => void): () => void;
+}
+declare class Wakefulness {
+    private readonly blocker;
+    private readonly holders;
+    private until;
+    private lamp;
     /**
-     * Присмотр за фоновой работой: перевести её смерть в состояние задания.
+     * Система однажды лампу не дала — больше не просим. Иначе каждый вызов
+     * пытался бы заново запустить то, чего нет, а работа человека важнее.
+     */
+    private refused;
+    private cancelTail;
+    private readonly clock;
+    private readonly pid;
+    constructor(blocker: Blocker, opts?: {
+        clock?: Clock;
+        pid?: number;
+        tailMs?: number;
+    });
+    private readonly tailMs;
+    /** Держать компьютер бодрым; вернуть снятие. Снять второй раз — ничего не делает. */
+    hold(): () => void;
+    /**
+     * Держать, пока идёт работа, — и когда она кончилась успехом, и когда упала.
      *
-     * Один на монтаж и на установку. Двумя копиями это было бы двумя разными
-     * ответами человеку на одну и ту же беду.
+     * ⚠ Работа — функцией, а не готовым обещанием. Обещание уже запущено: тело
+     * async-функции до первого await идёт при вычислении аргумента, и начало
+     * работы оставалось без лампы (тест обёртки поймал ровно это).
      */
-    private watch;
+    during<T>(work: () => Promise<T>): Promise<T>;
+    /**
+     * Своя лампа для фоновой работы, привязанная к её процессу. Гаснет сама, когда
+     * работа кончилась, — даже если нас к тому времени уже закрыли.
+     */
+    follow(pid: number): void;
+    private sync;
+    private light;
 }
+
 /**
- * Путь, каким его понимает питон: с раскрытой тильдой и от нашей рабочей
- * папки, а не от чужой.
+ * Где внутри распакованной портативной сборки лежит сам интерпретатор.
  *
- * Нейросеть пишет «~/Movies/ролик.mp4» постоянно — тем более что описание
- * `style_new` само подсказывает «~/.naparnik/стиль» как образец.
- * `existsSync` тильду не раскрывает, и монтаж отвечал «Файла нет» о
- * существующем файле. Питон везде делает expanduser; тут делаем то же самое.
+ * ⚠ ТРИ ВАРИАНТА, А НЕ ДВА, И РОВНО ТЕ ЖЕ, ЧТО У ДВИЖКА. Источник правды —
+ * `engine/shell-contract.json` → `portable_python.inside`: оттуда их берёт и
+ * питон (`engine/setup/python_finder.py`). Копия здесь неизбежна — питон мы
+ * ищем ДО того, как есть чем запустить питон, — но прошлая копия знала два
+ * варианта из трёх: на сборке, где внутри лежит только `bin/python`, движок
+ * питон видел, а сервер MCP нет. Правится сначала JSON, потом сюда; расхождение
+ * ловит тест границы (`engine.test.ts`) сверкой с этим JSON.
  */
-declare function path(candidate: string): string;
+declare const INSIDE_PYTHON: string[];
+/** Дом по умолчанию — ровно тот же литерал, что в `engine/kit/home.py`. */
+declare const DEFAULT_HOME = "~/.naparnik";
 /**
- * Путь к существующему файлу — или человеческий отказ.
+ * Шаги установки, которые идут минутами и часами: их нельзя держать внутри
+ * вызова инструмента. Секундами считается только `check`.
  *
- * Копий этой проверки было четыре, слово в слово, и текст у них был хуже
- * питоновского: там на этот случай уже сказано, что ролик мог остаться в
- * «Загрузках» или его переименовали. Одна дверь.
+ * ⚠ «python» здесь вместе с портативной сборкой: шаг, который раньше лишь
+ * советовал сходить на python.org, теперь может качать от 24 до 104 МБ.
+ * Оставь его быстрым — и на медленной связи клиентская программа оборвала бы
+ * вызов по своему таймауту, а скачивание осталось бы сиротой; повтор начал бы
+ * второе.
  */
-declare function fileOrRefusal(candidate: string): {
-    path: string;
-} | {
-    refusal: string;
-};
+declare const LONG_STEPS: Set<string>;
 /**
- * Разбор неудачи команды движка — ОДИН на все её виды.
+ * Все шаги установки, которые понимает движок.
  *
- * Своё сообщение команды важнее сообщения запускателя: «Command failed: …» с
- * полным путём к python'у человеку не говорит ничего. Код 2 значит «чего-то не
- * хватает» или «задача не удалась» — это НОРМАЛЬНЫЙ ответ, а не сбой
- * инструмента: подай его ошибкой, и нейросеть начнёт извиняться вместо того,
- * чтобы доставить недостающее.
+ * ⚠ ЭТО ЗЕРКАЛО `STEPS` движка, и оно уже один раз разошлось: движок печатал
+ * «Шаг установки „вырез“», а здешний список о таком шаге не знал — клиент
+ * оказывался в тупике, потому что инструмент не принимал значение, которое
+ * движок сам же и назвал. Источник правды — `engine/shell-contract.json` →
+ * `install_steps`: оттуда `STEPS` берёт и `setup/install.py`. Правится сверху
+ * вниз: сначала JSON, потом сюда. Расхождение сторожит `engine.test.ts` сверкой
+ * с этим JSON.
  */
-declare function parseFailure(err: unknown, fallback: string): CommandOutcome;
-/** Последняя непустая строка вывода — там, где команда печатает результат. */
-declare function lastLine(output: string): string;
-
-/** Определение ресурса в 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;
-
+declare const INSTALL_STEPS: string[];
 /**
- * Типы и утилиты для инструментов агентного цикла.
+ * Паспорт пака: имена этапов, список моделей, чем запускать.
  *
- * Порт из packages/agent-core/src/tools/tool.ts с расширениями:
- * - readOnly флаг для параллельного выполнения
- * - group — категория инструмента для фильтрации и UI
- * - emitProgress в ToolContext — стриминг прогресса без возврата из execute
- * - agentId в ToolContext — для мульти-агентных сценариев
+ * Спрашивается у движка ОДНОЙ командой, а не переписывается сюда. Пока его не
+ * было, списки этапов и моделей жили здесь второй правдой, а точка входа была
+ * прибита строкой "scripts/edit.py".
  */
 /**
- * Примитивный тип JSON Schema для параметра инструмента.
- * Ограниченное подмножество JSON Schema — только то, что понимают LLM-провайдеры.
+ * ⚠ ИМЕНА ПОЛЕЙ — ОТВЕТ ПИТОНА, А НЕ НАШ ОБЪЕКТ. Паспорт печатает движок
+ * монтажа (`engine/passport.py` → `as_json`, команда `pack-description`), и
+ * имена полей — его. Переименование здесь ничего не меняет на той стороне:
+ * оболочка просто перестала бы находить поля и объявила бы «паспорт не
+ * прочитан» на каждом запуске. Поля, несущие имена, сверяет с настоящими
+ * `pack.json` и рецептом `tool-declaration.test.ts`.
  */
-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;
+interface PackPassport {
+    'name': string;
+    'title': string;
+    'entry': string;
+    'stages': string[];
+    'models': string[];
     /**
-     * Разрешить произвольные ключи в объекте (валидный JSON Schema keyword).
-     * Полезно для object-параметров с динамическими полями (params интеграций),
-     * где нужно явно подсказать LLM что это словарь произвольных ключей.
-     * При использовании совмещать с `properties: {}` для соответствия общему
-     * стилю кодовой базы.
+     * Движок распознавания → модель по умолчанию. Карта, а не одно имя: на
+     * видеокарте Apple берётся medium, на процессоре turbo — разница в скорости
+     * десятикратная, замерено.
      */
-    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;
+    'default_model': Record<string, string>;
     /**
-     * Временные метки последнего чтения файлов (путь → timestamp в мс).
+     * Что монтаж умеет СВЕРХ обязательного пути: имя ключа → вид и пояснение.
      *
-     * Заполняется инструментом чтения при каждом успешном обращении.
-     * Инструменты записи и редактирования проверяют этот словарь перед записью,
-     * чтобы обнаружить устаревшие правки (stale write detection).
+     * Объявляется паком, а не здесь: набор зависит от того, что пак умеет, и
+     * оболочка знать его заранее не может. Пока этого не было, шесть ключей
+     * (фон, свет, экран, слои, музыка, без акцентов) существовали только для
+     * того, кто печатает в терминале, — через инструмент их попросить было нечем.
+     * Старый пак поля не отдаёт: тогда схема остаётся с обязательными ключами.
+     */
+    'capabilities'?: Record<string, {
+        'kind': string;
+        'about': string;
+    }>;
+}
+/** Ответ команды движка в виде, пригодном для инструмента. */
+type CommandOutcome = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    text: string;
+};
+/** Где лежит установленная сборка движка. */
+interface EnginePlace {
+    /** Папка с `console.py`. */
+    engine: string;
+    /** Папка пака монтажа: `.venv`, `pack.json`, точка входа. */
+    pack: string;
+    /** Полный путь к `console.py`. */
+    consolePy: string;
+}
+declare class Engine {
+    private readonly env;
+    /**
+     * «Не спи» для фоновой работы (`keep-awake.ts`). По умолчанию выключено:
+     * тесты и одноразовые `new Engine()` для отката и паспорта систему не
+     * трогают. Движок, который качает и монтирует, заводит `wakefulEngine()`
+     * в `cli.ts` — и сервер, и установщик Codex.
+     */
+    private readonly awake;
+    private passportCache;
+    private versionAtStart;
+    private pythonChecked;
+    constructor(env?: NodeJS.ProcessEnv, 
+    /**
+     * «Не спи» для фоновой работы (`keep-awake.ts`). По умолчанию выключено:
+     * тесты и одноразовые `new Engine()` для отката и паспорта систему не
+     * трогают. Движок, который качает и монтирует, заводит `wakefulEngine()`
+     * в `cli.ts` — и сервер, и установщик Codex.
+     */
+    awake?: Wakefulness);
+    /**
+     * Корень Напарника на машине клиента.
      *
-     * Ключ: абсолютный путь к файлу.
-     * Значение: Date.now() в момент прочтения.
+     * ⚠ ПУСТАЯ СТРОКА — ЭТО «НЕ ЗАДАНО», А НЕ «ТЕКУЩАЯ ПАПКА». Прочитай мы её
+     * как путь — дом уехал бы в рабочий каталог процесса, и питон с TypeScript
+     * разошлись бы в том, где вообще живут задачи и стиль. Тот же `or` стоит в
+     * `engine/kit/home.py`.
+     *
+     * ⚠ И ШАБЛОН — ТОЖЕ «НЕ ЗАДАНО», см. `fromHost` в `config.ts`. Пустое поле
+     * настроек приезжает от Claude Desktop строкой `${user_config.engine_home}`,
+     * и до 2026-09-10 движок искался в папке с таким именем: у человека он лежал
+     * в `~/.naparnik`, а расширение отвечало «не установлен — монтировать нечем».
      */
-    readFileTimestamps: Record<string, number>;
+    home(): string;
     /**
-     * Содержимое прочитанных файлов (путь → текст).
+     * Значение переменной окружения — или undefined, если она пуста либо не
+     * задана. Наружу нужна затем, что окружение у Движка своё (передано в
+     * конструктор), а `process.env` в тестах не тот же самый.
      *
-     * Опциональный словарь для post-compact restore — заполняется инструментами
-     * чтения когда featureGates.postCompactRestore=true.
-     * Позволяет postCompactRestore() восстановить содержимое без повторного чтения с диска.
+     * ⚠ ПУСТАЯ СТРОКА И ШАБЛОН СЧИТАЮТСЯ «НЕ ЗАДАНО» — по той же причине, что
+     * и у дома: незаполненное поле настроек приезжает от Claude Desktop либо
+     * пустым, либо строкой `${user_config.…}` (`fromHost` в `config.ts`).
+     */
+    variable(name: string): string | undefined;
+    /** Папка версий движка: `<дом>/engine`. */
+    versionsDir(): string;
+    /**
+     * Какая версия движка объявлена рабочей.
      *
-     * Ключ: абсолютный путь к файлу (совпадает с readFileTimestamps).
-     * Значение: текстовое содержимое на момент последнего чтения.
+     * Обычный ТЕКСТОВЫЙ файл, а не симлинк: создание симлинка на Windows требует
+     * режима разработчика или прав администратора, а строка в файле переносима и
+     * переименовывается атомарно.
+     *
+     * ⚠ ЗАПОМИНАЕТСЯ НА ВСЮ ЖИЗНЬ ПРОЦЕССА, И ЭТО НЕСУЩЕЕ. Так работает обещание
+     * «подмена начинки — только на старте»: обновление меняет файл `current`, а
+     * запущенный процесс продолжает считать на той версии, с которой начал.
+     * Читай мы файл каждый раз — задача, заведённая старой версией, дочитывалась
+     * бы новой. У движка кэш по отпечаткам, и в отпечаток входит код шага: смесь
+     * двух версий внутри одной задачи не упала бы, а тихо смешала результаты.
+     *
+     * `freshVersion()` даёт незакэшированное значение — она нужна ровно двум местам:
+     * самому обновлению и рассказу человеку о том, что новая версия уже готова и
+     * подхватится после перезапуска.
      */
-    readFileContents?: Record<string, string>;
+    currentVersion(): string | null;
+    /** Что записано в файле `current` прямо сейчас, мимо памяти процесса. */
+    freshVersion(): string | null;
     /**
-     * Функция для эмиссии событий прогресса во время выполнения инструмента.
-     * Позволяет стримить промежуточные результаты в UI без завершения execute().
-     * Отсутствует, если потребитель не поддерживает стриминг прогресса.
+     * Где установлен движок — или null, если нигде.
+     *
+     * Порядок: явное указание переменной (лаборатория, тесты, ручная сборка) →
+     * версионная раскладка `<дом>/engine/<текущая>`. Третьего варианта нет
+     * намеренно: каждый «а ещё поищем вот тут» — это место, где TypeScript и
+     * питон однажды разойдутся.
      */
-    emitProgress?: (content: string) => void;
     /**
-     * Идентификатор агента в мульти-агентных сценариях.
-     * Используется для изоляции состояния между агентами и корректного логирования.
+     * Указан ли движок переменной вручную.
+     *
+     * ⚠ ЭТО НЕ МЕЛОЧЬ ДЛЯ ОБНОВЛЕНИЯ. Ручной путь ПОБЕЖДАЕТ версионную
+     * раскладку, а обновление умеет только её: оно распакует новую версию в
+     * `<дом>/engine/<версия>` и переставит указатель — на который эта машина не
+     * смотрит вовсе. Получилось бы обновление, которое честно отчитывается об
+     * успехе и не меняет ничего.
      */
-    agentId?: 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[];
+    pathSetByHand(): boolean;
+    place(): EnginePlace | null;
+    /** Явное место кандидата: не читает и не меняет current. */
+    placeForVersion(version: string): EnginePlace | null;
+    private assemble;
     /**
-     * Данные для ВИДЖЕТА, мимо контекста модели.
+     * Почему монтировать нечем — словами для нейросети клиента.
      *
-     * ⚠ РАЗДЕЛЕНИЕ НЕ РАДИ ПОРЯДКА, А РАДИ ДЕНЕГ И ТОЛКУ. Настоящий кадр ролика
-     * в base64 весит восемь килобайт; три кадра — двадцать четыре, и модель
-     * перечитывает их каждый ход, ничего в них не видя: base64 в тексте она
-     * «посмотреть» не может. Картинки нужны ГЛАЗАМ человека, то есть форме, а
-     * модели хватает названий словами. Уезжает как `structuredContent` в ответе
-     * `tools/call` — так это и разведено в спеке MCP.
+     * ⚠ ЭТО НЕ ОШИБКА ИНСТРУМЕНТА, а состояние машины. Отдай мы сюда `spawn
+     * python3 ENOENT` или молчание — модель начала бы извиняться и гадать
+     * вместо того, чтобы объяснить человеку один недостающий шаг.
      */
-    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;
+    whyNoEngine(): string;
     /**
-     * Название по-русски — для ЧЕЛОВЕКА, в отличие от `description` для модели.
-     * Уезжает хосту как `annotations.title` и показывается в настройках вместо
-     * имени из кода: без него человек читает «Choose variant», решая, разрешать
-     * ли инструмент.
+     * Забыть, где движок, — после того как мы его только что поставили.
+     *
+     * ⚠ БЕЗ ЭТОГО ПЕРВАЯ УСТАНОВКА НЕ ВИДНА САМОЙ СЕБЕ. `currentVersion`
+     * запоминается на всю жизнь процесса нарочно (подмена начинки — только на
+     * старте), и сразу после доставки следующий же вызов получил бы
+     * закэшированное «версии нет» про версию, которую мы сами и разложили.
+     * Здесь это не нарушает обещания: смешивать две версии внутри задачи нечем,
+     * до этого момента версии не было вовсе.
      */
-    title?: string;
-    /** JSON Schema входных параметров */
-    inputSchema: ToolInputSchema;
+    forgetPlace(): void;
+    /** Забыть ответ на вопрос «есть ли питон» — после того как мы его принесли. */
+    forgetPython(): void;
+    /** Python окружения пака — им считается монтаж. Может ещё не существовать. */
+    packPython(): string | null;
     /**
-     * Флаг «только чтение».
-     * readOnly-инструменты не изменяют внешнее состояние и могут выполняться
-     * параллельно с другими readOnly-инструментами без риска конфликтов.
-     * Агентский цикл использует этот флаг для параллельного выполнения.
+     * Портативный python, который движок доставил сам (шаг «python» установки).
+     *
+     * ⚠ ЗНАТЬ ПРО НЕГО ОБЯЗАНА И ЭТА СТОРОНА. Он лежит в `<дом>/bin/python` и в
+     * PATH не попадает намеренно — PATH человека мы не трогаем. Пропусти его
+     * здесь, и получится: установка принесла питон, окружение на нём собралось,
+     * а сервер MCP по-прежнему зовёт системный «python», которого нет или
+     * который заглушка из Microsoft Store.
      */
-    readOnly?: boolean;
+    ourPython(): string | null;
     /**
-     * Переписывает то, что у человека уже есть.
+     * Python для команд движка.
      *
-     * По умолчанию `false`, и это не оптимизм: монтаж кладёт НОВЫЙ файл рядом с
-     * исходником, обновление держит прежнюю версию на диске, установка кладёт
-     * недостающее в свою папку — ничего из этого не затирает чужого. `true`
-     * ставится там, где вызов переписывает содержимое, которое человек считал
-     * своим: например, готовый фильтр цвета в его паке стиля.
+     * Окружения пака может не быть вовсе — именно это и проверяет `check_setup`,
+     * поэтому запускать проверку его питоном нельзя: получилась бы курица и
+     * яйцо. Команды движка написаны на голой стандартной библиотеке и идут
+     * системным python'ом, когда своего ещё нет.
      */
-    destructive?: boolean;
+    enginePython(): string;
+    /** Python подготовки кандидата — намеренно без fallback на venv старого пака. */
+    bootstrapPython(): string;
+    /** Python ровно названного кандидата, а не текущей версии. */
+    candidatePython(place: EnginePlace): string | null;
     /**
-     * Виджет инструмента (MCP Apps): адрес `ui://…` ресурса, HTML которого хост
-     * рисует в ленте вместо текстового ответа. Ресурс регистрируется на
-     * сервере отдельно (`McpServer.addResource`); здесь только ссылка, и в
-     * `tools/list` она уезжает как `_meta.ui.resourceUri`.
+     * Среда для КАЖДОГО питона, которого мы запускаем.
+     *
+     * ⚠ БЕЗ ЭТОГО НА WINDOWS НЕ РАБОТАЕТ НИЧЕГО. Пока в питоне не включён режим
+     * UTF-8, он печатает в кодовой странице системы (cp1251 на русской, cp1252
+     * на английской), а Node декодирует ребёнка как UTF-8 — и весь ответ
+     * приезжал нечитаемым: «????? ???: /??? ??????.mp4». Отдельно ломался
+     * preview: строка JSON у нас с русскими ключами, и поле `файл` выходило
+     * undefined. Свой код мы чиним вызовом (`engine/kit/encoding.py`), а чужие
+     * библиотеки внутри того же процесса — только средой. Нужны оба заслона.
      */
-    ui?: {
-        resourceUri: string;
-    };
+    pythonEnv(): NodeJS.ProcessEnv;
     /**
-     * Флаг «обратимое действие» — действие остаётся в рамках текущего диалога
-     * с этим пользователем и не выходит наружу.
+     * Есть ли на машине python вообще — и словами, если нет.
      *
-     * `true` (по умолчанию) — безопасно вызывать без явного человеческого approve:
-     *   recall, web_search, view, create_file (в workspace), send_file_to_chat,
-     *   send_task_to_agent (внутреннему агенту), bash_tool (sandbox-изолирован),
-     *   integration_call с read-методами.
+     * Весь движок (включая проверку и установку) идёт через запуск python'а.
+     * Когда его нет, `execFile` бросает ENOENT, и клиентской нейросети
+     * доставалось «spawn python3 ENOENT» — текст, из которого человеку не понять
+     * ничего. Шаг «python», написанный ровно для этого случая, при этом
+     * недостижим по устройству: он сам запускается python'ом.
      *
-     * `false` — действие выходит наружу и должно сопровождаться явной формулировкой
-     *   подтверждения от пользователя (через диалог) перед выполнением:
-     *   отправка наружу (письмо/SMS внешнему адресату), запись в CRM/ERP,
-     *   финансовые операции, удаление persistent данных.
+     * На Windows есть отдельная беда: в PATH лежит заглушка Microsoft Store —
+     * `python` там есть, он печатает рекламу магазина и выходит с кодом 9009.
+     * Поэтому проверяем не наличие файла, а ответ на вопрос о версии.
+     */
+    pythonTrouble(): Promise<string | null>;
+    /**
+     * Запустить команду движка и отдать её текст как есть.
      *
-     * Используется для генерации списков в system prompt и (в будущем)
-     * для автоматического enforcement в loop.
+     * Умолчание таймаута заведомо БОЛЬШЕ внутренних таймаутов движка (самый
+     * долгий — опрос окружения пака, 180 с). Внешний таймаут короче внутреннего
+     * означает, что внутренний недостижим: пробник убивался снаружи, и его
+     * объяснение не доезжало до человека вовсе.
      */
-    reversible?: boolean;
+    command(args: string[], { maxBuffer, timeout, key, }?: {
+        maxBuffer?: number;
+        timeout?: number;
+        key?: string;
+    }): Promise<CommandOutcome>;
     /**
-     * Группа инструмента — для фильтрации, UI-группировки и политик доступа.
-     * Соответствует group:* из конфигурации OpenClaw sandbox.
+     * Сырой запуск консоли движка. Наружу нужен затем, что часть работы
+     * (заведение задания, показ кадра) читает не текст, а JSON.
      */
-    group?: ToolGroup;
+    run(place: EnginePlace, args: string[], { maxBuffer, timeout, key, }?: {
+        maxBuffer?: number;
+        timeout?: number;
+        key?: string;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    /** Запуск через явно выбранный Python нужен проверке кандидата до current. */
+    runWith(executable: string, place: EnginePlace, args: string[], { maxBuffer, timeout, key, }?: {
+        maxBuffer?: number;
+        timeout?: number;
+        key?: string;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    /** Одна строка вывода команды — например, номер заведённого задания. */
+    asString(place: EnginePlace, args: string[], key?: string): Promise<string>;
     /**
-     * Флаг «отложенная загрузка схемы» (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).
+     * ⚠ ТАЙМАУТ КОРОТКИЙ, И ЭТО НЕСУЩЕЕ. Паспорт читается НА СТАРТЕ, до
+     * регистрации инструментов, — то есть внутри рукопожатия, которое клиент
+     * ждёт по своему таймауту (у Codex это 10 секунд по умолчанию). Команда
+     * честно занимает доли секунды: запустить питон и прочитать pack.json.
+     * Не уложилась — с паком что-то не так, и правильный размен здесь такой:
+     * потерять подсказки со списками моделей, но поднять сервер. Обратный
+     * размен означал бы «сервер не запустился» и молчание вместо объяснения.
      */
-    isDeferred?: boolean;
+    passport(): Promise<PackPassport | null>;
     /**
-     * Максимальный размер `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>` тегов.
+     * Предохранителя параллельности здесь нет намеренно. Он в питоне
+     * (`engine/state.slot`) — файловые замки в `<дом>/busy`. Счётчик в
+     * памяти защищал только свой процесс: Claude Desktop и Claude Code поднимают
+     * по своему, и вместе они давали вдвое больше тяжёлой работы, чем разрешено.
+     */
+    background(opts: {
+        place: EnginePlace;
+        executable: string;
+        args: (id: string) => string[];
+        startJob: string[];
+        advice: string;
+        /**
+         * Ключ подписки — ТОЛЬКО этому запуску, не общей среде питона.
+         *
+         * ⚠ БЕЗ НЕГО МОНТАЖ ОТКАЗЫВАЕТ КАЖДОМУ ПЛАТЯЩЕМУ. С 2026-09-09 движок
+         * спрашивает подписку сам (`client/engine/account/subscription.py`) и берёт ключ
+         * из `NAPARNIK_API_KEY`, а `pythonEnv()` его оттуда вычищает намеренно:
+         * иначе ключ уезжает в каждого потомка питона — ffmpeg, pip, чужой код
+         * пака. Поэтому не «вернуть ключ в среду», а доложить его точечно, ровно
+         * как уже сделано у скачивания движка (`run`, поле `key`).
+         */
+        key: string | undefined;
+    }): Promise<{
+        id: string;
+    } | {
+        refusal: string;
+    }>;
+    /**
+     * Файл, куда фоновая работа пишет свой stderr.
      *
-     * Подробности — `new-version/docs/claude-code-optimizations.md` (Слой A).
+     * Лежит в доме, а не рядом с видео: у установки видео нет вовсе, а ответ на
+     * вопрос «что она успела сказать перед смертью» нужен одинаково обоим.
+     * Держим последние `KEEP_LOGS` — полоса загрузки модели пишет сотни
+     * килобайт, и вечная папка таких файлов была бы платой человека за то, что
+     * он однажды монтировал.
      */
-    maxResultSizeChars?: number;
+    private openLog;
     /**
-     * Выполняет инструмент с заданными параметрами.
-     * @param input - Валидированные входные параметры
-     * @param ctx - Контекст выполнения (сессия, сигнал отмены, среда, временные метки файлов)
-     * @returns Результат выполнения или ошибка
+     * Присмотр за фоновой работой: перевести её смерть в состояние задания.
+     *
+     * Один на монтаж и на установку. Двумя копиями это было бы двумя разными
+     * ответами человеку на одну и ту же беду.
      */
-    execute(input: TInput, ctx: ToolContext): Promise<ToolResult>;
+    private watch;
 }
+/**
+ * Путь, каким его понимает питон: с раскрытой тильдой и от нашей рабочей
+ * папки, а не от чужой.
+ *
+ * Нейросеть пишет «~/Movies/ролик.mp4» постоянно — тем более что описание
+ * `style_new` само подсказывает «~/.naparnik/стиль» как образец.
+ * `existsSync` тильду не раскрывает, и монтаж отвечал «Файла нет» о
+ * существующем файле. Питон везде делает expanduser; тут делаем то же самое.
+ */
+declare function path(candidate: string): string;
+/**
+ * Путь к существующему файлу — или человеческий отказ.
+ *
+ * Копий этой проверки было четыре, слово в слово, и текст у них был хуже
+ * питоновского: там на этот случай уже сказано, что ролик мог остаться в
+ * «Загрузках» или его переименовали. Одна дверь.
+ */
+declare function fileOrRefusal(candidate: string): {
+    path: string;
+} | {
+    refusal: string;
+};
+/**
+ * Разбор неудачи команды движка — ОДИН на все её виды.
+ *
+ * Своё сообщение команды важнее сообщения запускателя: «Command failed: …» с
+ * полным путём к python'у человеку не говорит ничего. Код 2 значит «чего-то не
+ * хватает» или «задача не удалась» — это НОРМАЛЬНЫЙ ответ, а не сбой
+ * инструмента: подай его ошибкой, и нейросеть начнёт извиняться вместо того,
+ * чтобы доставить недостающее.
+ */
+declare function parseFailure(err: unknown, fallback: string): CommandOutcome;
+/** Последняя непустая строка вывода — там, где команда печатает результат. */
+declare function lastLine(output: string): string;
 
 /**
  * Аргументы инструмента: ОДНА запись на объявление модели и на проверку входа.
@@ -1015,6 +1123,95 @@ interface Pace {
     rest: (ms: number) => Promise<void>;
 }
 
+interface ScrubContext {
+    /** Домашняя папка ОС (`os.homedir()`). */
+    home: string;
+    /** Имя пользователя ОС: оно бывает в путях чужих машин и в текстах ошибок. */
+    user: string;
+    /** Дом Напарника (`Engine.home()`): бывает задан не в `~/.naparnik`. */
+    naparnikHome: string;
+    /** Папка, из которой запущена сама оболочка. */
+    shellDir: string;
+    /**
+     * Строки из аргументов вызова: путь к ролику, папка, текст правки. Их
+     * знаем точно — и вычёркиваем в любом виде, в котором они встречаются.
+     */
+    secrets: string[];
+}
+
+/** Хост — программа, в которой живёт оболочка (`clientInfo` рукопожатия MCP). */
+type Host = {
+    name: string;
+    version: string;
+};
+/** Поломка до обезличивания: всё, что узнали на месте. */
+interface Crash {
+    where: 'tool' | 'job' | 'process';
+    tool: string | null;
+    stage: string | null;
+    errorType: string;
+    message: string;
+    trace: string;
+    /** Какой конец трейса ценнее: у питона — низ, у JS — верх. */
+    keep: 'head' | 'tail';
+    /** Кадры для отпечатка: «файл:функция» без версий и номеров строк. */
+    frames: string[];
+    python: string | null;
+    /** Строки из аргументов вызова — их вычёркиваем в любом виде. */
+    secrets: string[];
+    host: Host | null;
+    /** Строка для модели: суть одной строкой и место. */
+    essence: string;
+}
+interface CrashReporterDeps {
+    /** Клиент нашего сервера — тот же, что спрашивает подписку: ключ, отпечаток машины, версии. */
+    client: Pick<NaparnikApiClient, 'postMontage'>;
+    /** Дом Напарника — `Engine.home()`. */
+    home: string;
+    engineVersion: () => string | null;
+    /** Есть ли ключ: без него отчёт не уйдёт, и человеку это обещать нельзя. */
+    canSend: boolean;
+    now?: () => number;
+    /** Версия ffmpeg; спрашивается при отправке, мимо ответа инструмента. */
+    ffmpegVersion?: () => Promise<string | null>;
+    /** Папка, откуда запущена оболочка: её пути в трейсе — наши. */
+    shellDir?: string;
+    osHome?: string;
+    osUser?: string;
+    timeoutMs?: number;
+}
+/**
+ * Один на процесс оболочки: его держат и обёртка инструментов, и перехват
+ * падения процесса (`cli.ts`). Состояние, которое переживает перезапуск
+ * (очередь, частота, номера заданий), лежит на диске в `<дом>/crash-reports/`.
+ */
+declare class CrashReporter {
+    #private;
+    constructor(deps: CrashReporterDeps);
+    get canSend(): boolean;
+    get home(): string;
+    /** Запомнить программу-хост: при падении всего процесса контекста вызова нет. */
+    /** Запомнить строки аргументов вызова — чтобы вычеркнуть их из будущих отчётов. */
+    noteSecrets(secrets: string[]): void;
+    noteHost(host: Host | null): void;
+    /** Отправить отчёт мимо ответа. Для тестов и смоука — `settled()`. */
+    submit(crash: Crash): void;
+    /**
+     * Процесс падает: отчёт кладётся на диск СИНХРОННО и уходит на следующем
+     * запуске. Сеть здесь не трогаем — процессу осталось жить миллисекунды, и
+     * недоставленный наполовину запрос хуже файла, который точно дойдёт.
+     */
+    persist(crash: Crash): void;
+    /** Досылка очереди — не чаще раза в минуту. */
+    flushSoon(): void;
+    /** Дождаться всего, что ушло мимо ответа. Боевому пути не нужно. */
+    settled(): Promise<void>;
+    /** Задание уже разобрано: отчёт о нём ушёл раньше, в этом или прошлом запуске. */
+    jobSeen(id: string): boolean;
+    rememberJob(id: string): void;
+    scrubContext(secrets: string[]): ScrubContext;
+}
+
 /**
  * Набор инструментов покупателя — одним списком и под одними обёртками.
  *
@@ -1077,7 +1274,19 @@ baseUrl: string,
  * а цикл без подмены времени проверялся бы минутным прогоном — то есть
  * никогда. Умолчание обычное, вызывающему про это знать не надо.
  */
-pace?: Pace): Tool[];
+pace?: Pace, 
+/**
+ * «Не спи» (`keep-awake.ts`): один экземпляр на программу, его же держит
+ * движок. Параметром — чтобы тест проверил проводку НАСТОЯЩЕГО списка, не
+ * трогая систему; умолчание выключено по той же причине.
+ */
+awake?: Wakefulness, 
+/**
+ * Отчёты о поломках (`crash-report.ts`): один на программу, его же держит
+ * перехват падения процесса в `cli.ts`. `null` — отчётов нет: соседние тесты
+ * собирают набор без сервера и не должны слать ничего.
+ */
+crashes?: CrashReporter | null): Tool[];
 /**
  * Ресурсы виджетов — парой к `buildAll`, из того же файла: кто собирает
  * сервер из инструментов, здесь же берёт и HTML к ним. Сторож пары — тест
@@ -1309,9 +1518,9 @@ declare class NaparnikConfigError extends NaparnikError {
  * годится ли она для новой начинки: разойдись она с пакетом, и в логах будет
  * стоять чужое число, а обновление начнёт считать оболочку не той.
  */
-declare const VERSION = "0.10.21";
+declare const VERSION = "0.10.25";
 /** Как мы представляемся серверу Напарника. По нему в логах видно оболочку. */
-declare const USER_AGENT = "naparnik-mcp/0.10.21";
+declare const USER_AGENT = "naparnik-mcp/0.10.25";
 /**
  * Самая старая начинка (движок монтажа), с которой эта оболочка работает.
  * Обновление начинки ниже этой версии не ставится, а выше — требует оболочки