@naparnik/mcp 0.1.0 → 0.10.11

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Tool } from '@naparnik/super-agent-core/mcp';
+import { z } from 'zod/v4';
 
 interface NaparnikMcpConfig {
     apiKey: string;
@@ -18,23 +18,1194 @@ declare function loadConfig(env?: NodeJS.ProcessEnv): NaparnikMcpConfig;
 
 declare class NaparnikApiClient {
     private readonly config;
-    constructor(config: NaparnikMcpConfig);
+    private readonly machine;
     /**
-     * POST к sdk-эндпоинту. Все automation-эндпоинты только POST — таково
-     * ограничение VerbFilter на сервере, отдельного GET-пути нет.
+     * Какая начинка стоит на этой машине. `null` — не стоит вовсе.
      *
-     * @param path путь относительно /api/internal/automation/sdk
-     * @param body тело запроса
-     * @param opts long: использовать увеличенный таймаут (генерация, поиск)
+     * ⚠ ЗАВИСИМОСТЬЮ, А НЕ ЧТЕНИЕМ ДИСКА ЗДЕСЬ. По той же причине, что и
+     * отпечаток: клиент, который сам лезет в файлы, нечем проверить, не трогая
+     * настоящую машину. Спрашивается на каждом запросе, а не один раз при
+     * запуске: начинка ставится и обновляется прямо во время работы, и
+     * запомненная версия врала бы ровно после установки.
      */
-    post<T>(path: string, body?: unknown, opts?: {
+    private readonly engineVersion;
+    /**
+     * @param config ключ, адрес и таймауты
+     * @param machine отпечаток этой машины или `null`, если опознать не удалось
+     *
+     * ⚠ ОТПЕЧАТОК ПРИХОДИТ СНАРУЖИ, А НЕ СЧИТАЕТСЯ ЗДЕСЬ. Счёт лезет в систему —
+     * запускает команду, читает файл в домашней папке, — и клиент, который это
+     * делает сам, нечем проверить: тест либо трогает настоящую машину, либо
+     * подменяет модуль. Зависимостью же обе стороны проверяются простой
+     * функцией: «прислали отпечаток» и «машину не опознали».
+     */
+    constructor(config: NaparnikMcpConfig, machine: () => string | null, 
+    /**
+     * Какая начинка стоит на этой машине. `null` — не стоит вовсе.
+     *
+     * ⚠ ЗАВИСИМОСТЬЮ, А НЕ ЧТЕНИЕМ ДИСКА ЗДЕСЬ. По той же причине, что и
+     * отпечаток: клиент, который сам лезет в файлы, нечем проверить, не трогая
+     * настоящую машину. Спрашивается на каждом запросе, а не один раз при
+     * запуске: начинка ставится и обновляется прямо во время работы, и
+     * запомненная версия врала бы ровно после установки.
+     */
+    engineVersion?: () => string | null);
+    /**
+     * POST к НАШЕМУ серверу монтажа.
+     *
+     * ⚠ ОТДЕЛЬНЫЙ МЕТОД, А НЕ ФЛАГ В `post`. Адресатов ровно два, и они разные во
+     * всём: у нашего сервера свой контракт и свой релизный цикл, у чужого API
+     * Напарника — чужие. Пока метод был один, вопрос о подписке уходил под чужой
+     * префикс, и в день гашения монолита отличить «наш сервер молчит» от «чужого
+     * больше нет» было бы нечем. Вызывающий обязан знать, куда идёт, — поэтому
+     * знание вынесено в имя метода, а не спрятано в параметр.
+     */
+    postMontage<T>(path: string, body?: unknown, opts?: {
         long?: boolean;
+        billable?: boolean;
+        timeoutMs?: number;
+        once?: boolean;
     }): Promise<T>;
+    /**
+     * GET к НАШЕМУ серверу монтажа: ответ разбирается как JSON.
+     *
+     * ⚠ ОТДЕЛЬНЫЙ МЕТОД РЯДОМ С `postMontage`, А НЕ ФЛАГ В НЁМ. Тело и заголовки
+     * у GET другие: пустого JSON-тела он не шлёт вовсе, а `Content-Type` без тела
+     * — это заголовок, обещающий то, чего нет. Прятать это в параметр значило бы
+     * заводить в одном методе две формы запроса, которые расходятся молча.
+     */
+    getMontage<T>(path: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<T>;
+    /**
+     * GET к нашему серверу за ТЕКСТОМ, а не за JSON.
+     *
+     * ⚠ ТЕКСТ НУЖЕН ОТДЕЛЬНО, ПОТОМУ ЧТО ЗНАНИЯ ЕДУТ РАЗМЕТКОЙ. Оберни мы их в
+     * JSON ради единообразия — модель получала бы экранированные переводы строк
+     * и первым делом просила бы их распутать. Разбор ОШИБОК при этом остаётся
+     * общим: у ошибок тело json и на этом пути тоже.
+     */
+    getMontageText(path: string, opts?: {
+        timeoutMs?: number;
+        accept?: string;
+    }): Promise<string>;
+    /**
+     * Отправка. Адрес собирает `postMontage` — других адресатов у пакета нет.
+     *
+     * ⚠ БЫЛО ДВА, ОСТАЛСЯ ОДИН. Второй метод ходил в PHP API монолита: рилсы,
+     * баланс, распаковка бренда, генерация. Полка данных убрана из поставки
+     * 2026-09-02 вместе с обменом стилем — монолит гасится (docs/architecture.md,
+     * раздел 20), и инструмент, который в тот день начнёт отвечать «сервер не
+     * ответил», хуже отсутствующего.
+     *
+     * Метод оставлен приватным намеренно: снаружи виден только `postMontage`, и
+     * добавить хождение на чужой сервер, не объявив нового публичного метода,
+     * теперь нельзя.
+     */
+    private send;
     private attempt;
+    /**
+     * Заголовки запроса. Ключ есть всегда, отпечаток машины — когда он есть.
+     *
+     * ⚠ ОТПЕЧАТКА МОЖЕТ НЕ БЫТЬ, И ЭТО НЕ ОШИБКА. На урезанной машине команду не
+     * запустить и в домашнюю папку не записать. Пустой заголовок был бы хуже
+     * отсутствующего: сервер отличает «машину не назвали» от «назвали не ту», и
+     * пустая строка спутала бы одно с другим. Поэтому либо значение, либо ничего.
+     *
+     * Почему это заголовок, а не поле тела, — в контракте
+     * (`contracts/sdk-headers.ts`); второй копии этого объяснения быть не должно.
+     */
+    private headers;
     private parse;
 }
 
-declare function createNaparnikTools(client: NaparnikApiClient): Tool[];
+/**
+ * Где внутри распакованной портативной сборки лежит сам интерпретатор.
+ *
+ * ⚠ ТРИ ВАРИАНТА, А НЕ ДВА, И РОВНО ТЕ ЖЕ, ЧТО У ДВИЖКА
+ * (`engine/env.py` → `_INSIDE_PYTHON`). Копия здесь неизбежна — питон мы
+ * ищем ДО того, как есть чем запустить питон, — но прошлая копия знала два
+ * варианта из трёх: на сборке, где внутри лежит только `bin/python`, движок
+ * питон видел, а сервер MCP нет. Обе стороны сверяет тест границы
+ * (`engine.test.ts`), и он читает питоновский исходник, а не повторяет список.
+ */
+declare const INSIDE_PYTHON: string[];
+/** Дом по умолчанию — ровно тот же литерал, что в `engine/home.py`. */
+declare const DEFAULT_HOME = "~/.naparnik";
+/**
+ * Шаги установки, которые идут минутами и часами: их нельзя держать внутри
+ * вызова инструмента. Секундами считается только `check`.
+ *
+ * ⚠ «python» здесь вместе с портативной сборкой: шаг, который раньше лишь
+ * советовал сходить на python.org, теперь может качать от 24 до 104 МБ.
+ * Оставь его быстрым — и на медленной связи клиентская программа оборвала бы
+ * вызов по своему таймауту, а скачивание осталось бы сиротой; повтор начал бы
+ * второе.
+ */
+declare const LONG_STEPS: Set<string>;
+/**
+ * Все шаги установки, которые понимает движок.
+ *
+ * ⚠ ЭТО ЗЕРКАЛО `install.py` → `STEPS`, и оно уже один раз разошлось: движок печатал
+ * «Шаг установки „вырез“», а здешний список о таком шаге не знал — клиент
+ * оказывался в тупике, потому что инструмент не принимал значение, которое
+ * движок сам же и назвал. Правится сверху вниз: сначала `install.py` → `STEPS`,
+ * потом сюда. Расхождение сторожит `engine.test.ts` — он читает питоновский
+ * исходник, а не повторяет список.
+ */
+declare const INSTALL_STEPS: string[];
+/**
+ * Паспорт пака: имена этапов, список моделей, чем запускать.
+ *
+ * Спрашивается у движка ОДНОЙ командой, а не переписывается сюда. Пока его не
+ * было, списки этапов и моделей жили здесь второй правдой, а точка входа была
+ * прибита строкой "scripts/edit.py".
+ */
+/**
+ * ⚠ КЛЮЧИ РУССКИЕ, ПОТОМУ ЧТО ЭТО ОТВЕТ ПИТОНА, А НЕ НАШ ОБЪЕКТ. Паспорт
+ * печатает движок монтажа (`pack.json` и команда паспорта), и имена полей — его.
+ * Переименование здесь ничего не меняет на той стороне: оболочка просто
+ * перестала бы находить поля и объявила бы «паспорт не прочитан» на каждом
+ * запуске. Обе стороны сверяет тест границы (`engine.test.ts`), и он читает
+ * питоновский исходник, а не повторяет список.
+ */
+interface PackPassport {
+    'name': string;
+    'title': string;
+    'entry': string;
+    'stages': string[];
+    'models': string[];
+    /**
+     * Движок распознавания → модель по умолчанию. Карта, а не одно имя: на
+     * видеокарте Apple берётся medium, на процессоре turbo — разница в скорости
+     * десятикратная, замерено.
+     */
+    'default_model': Record<string, string>;
+    /**
+     * Что монтаж умеет СВЕРХ обязательного пути: имя ключа → вид и пояснение.
+     *
+     * Объявляется паком, а не здесь: набор зависит от того, что пак умеет, и
+     * оболочка знать его заранее не может. Пока этого не было, шесть ключей
+     * (фон, свет, экран, слои, музыка, без акцентов) существовали только для
+     * того, кто печатает в терминале, — через инструмент их попросить было нечем.
+     * Старый пак поля не отдаёт: тогда схема остаётся с обязательными ключами.
+     */
+    '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;
+    private passportCache;
+    private versionAtStart;
+    private pythonChecked;
+    constructor(env?: NodeJS.ProcessEnv);
+    /**
+     * Корень Напарника на машине клиента.
+     *
+     * ⚠ ПУСТАЯ СТРОКА — ЭТО «НЕ ЗАДАНО», А НЕ «ТЕКУЩАЯ ПАПКА». Прочитай мы её
+     * как путь — дом уехал бы в рабочий каталог процесса, и питон с TypeScript
+     * разошлись бы в том, где вообще живут задачи и стиль. Тот же `or` стоит в
+     * `engine/home.py`.
+     *
+     * ⚠ И ШАБЛОН — ТОЖЕ «НЕ ЗАДАНО», см. `fromHost` в `config.ts`. Пустое поле
+     * настроек приезжает от Claude Desktop строкой `${user_config.engine_home}`,
+     * и до 2026-09-10 движок искался в папке с таким именем: у человека он лежал
+     * в `~/.naparnik`, а расширение отвечало «не установлен — монтировать нечем».
+     */
+    home(): string;
+    /**
+     * Значение переменной окружения — или undefined, если она пуста либо не
+     * задана. Наружу нужна затем, что окружение у Движка своё (передано в
+     * конструктор), а `process.env` в тестах не тот же самый.
+     *
+     * ⚠ ПУСТАЯ СТРОКА И ШАБЛОН СЧИТАЮТСЯ «НЕ ЗАДАНО» — по той же причине, что
+     * и у дома: незаполненное поле настроек приезжает от Claude Desktop либо
+     * пустым, либо строкой `${user_config.…}` (`fromHost` в `config.ts`).
+     */
+    variable(name: string): string | undefined;
+    /** Папка версий движка: `<дом>/engine`. */
+    versionsDir(): string;
+    /**
+     * Какая версия движка объявлена рабочей.
+     *
+     * Обычный ТЕКСТОВЫЙ файл, а не симлинк: создание симлинка на Windows требует
+     * режима разработчика или прав администратора, а строка в файле переносима и
+     * переименовывается атомарно.
+     *
+     * ⚠ ЗАПОМИНАЕТСЯ НА ВСЮ ЖИЗНЬ ПРОЦЕССА, И ЭТО НЕСУЩЕЕ. Так работает обещание
+     * «подмена начинки — только на старте»: обновление меняет файл `current`, а
+     * запущенный процесс продолжает считать на той версии, с которой начал.
+     * Читай мы файл каждый раз — задача, заведённая старой версией, дочитывалась
+     * бы новой. У движка кэш по отпечаткам, и в отпечаток входит код шага: смесь
+     * двух версий внутри одной задачи не упала бы, а тихо смешала результаты.
+     *
+     * `freshVersion()` даёт незакэшированное значение — она нужна ровно двум местам:
+     * самому обновлению и рассказу человеку о том, что новая версия уже готова и
+     * подхватится после перезапуска.
+     */
+    currentVersion(): string | null;
+    /** Что записано в файле `current` прямо сейчас, мимо памяти процесса. */
+    freshVersion(): string | null;
+    /**
+     * Где установлен движок — или null, если нигде.
+     *
+     * Порядок: явное указание переменной (лаборатория, тесты, ручная сборка) →
+     * версионная раскладка `<дом>/engine/<текущая>`. Третьего варианта нет
+     * намеренно: каждый «а ещё поищем вот тут» — это место, где TypeScript и
+     * питон однажды разойдутся.
+     */
+    /**
+     * Указан ли движок переменной вручную.
+     *
+     * ⚠ ЭТО НЕ МЕЛОЧЬ ДЛЯ ОБНОВЛЕНИЯ. Ручной путь ПОБЕЖДАЕТ версионную
+     * раскладку, а обновление умеет только её: оно распакует новую версию в
+     * `<дом>/engine/<версия>` и переставит указатель — на который эта машина не
+     * смотрит вовсе. Получилось бы обновление, которое честно отчитывается об
+     * успехе и не меняет ничего.
+     */
+    pathSetByHand(): boolean;
+    place(): EnginePlace | null;
+    /** Явное место кандидата: не читает и не меняет current. */
+    placeForVersion(version: string): EnginePlace | null;
+    private assemble;
+    /**
+     * Почему монтировать нечем — словами для нейросети клиента.
+     *
+     * ⚠ ЭТО НЕ ОШИБКА ИНСТРУМЕНТА, а состояние машины. Отдай мы сюда `spawn
+     * python3 ENOENT` или молчание — модель начала бы извиняться и гадать
+     * вместо того, чтобы объяснить человеку один недостающий шаг.
+     */
+    whyNoEngine(): string;
+    /**
+     * Забыть, где движок, — после того как мы его только что поставили.
+     *
+     * ⚠ БЕЗ ЭТОГО ПЕРВАЯ УСТАНОВКА НЕ ВИДНА САМОЙ СЕБЕ. `currentVersion`
+     * запоминается на всю жизнь процесса нарочно (подмена начинки — только на
+     * старте), и сразу после доставки следующий же вызов получил бы
+     * закэшированное «версии нет» про версию, которую мы сами и разложили.
+     * Здесь это не нарушает обещания: смешивать две версии внутри задачи нечем,
+     * до этого момента версии не было вовсе.
+     */
+    forgetPlace(): void;
+    /** Забыть ответ на вопрос «есть ли питон» — после того как мы его принесли. */
+    forgetPython(): void;
+    /** Python окружения пака — им считается монтаж. Может ещё не существовать. */
+    packPython(): string | null;
+    /**
+     * Портативный python, который движок доставил сам (шаг «python» установки).
+     *
+     * ⚠ ЗНАТЬ ПРО НЕГО ОБЯЗАНА И ЭТА СТОРОНА. Он лежит в `<дом>/bin/python` и в
+     * PATH не попадает намеренно — PATH человека мы не трогаем. Пропусти его
+     * здесь, и получится: установка принесла питон, окружение на нём собралось,
+     * а сервер MCP по-прежнему зовёт системный «python», которого нет или
+     * который заглушка из Microsoft Store.
+     */
+    ourPython(): string | null;
+    /**
+     * Python для команд движка.
+     *
+     * Окружения пака может не быть вовсе — именно это и проверяет `check_setup`,
+     * поэтому запускать проверку его питоном нельзя: получилась бы курица и
+     * яйцо. Команды движка написаны на голой стандартной библиотеке и идут
+     * системным python'ом, когда своего ещё нет.
+     */
+    enginePython(): string;
+    /** Python подготовки кандидата — намеренно без fallback на venv старого пака. */
+    bootstrapPython(): string;
+    /** Python ровно названного кандидата, а не текущей версии. */
+    candidatePython(place: EnginePlace): string | null;
+    /**
+     * Среда для КАЖДОГО питона, которого мы запускаем.
+     *
+     * ⚠ БЕЗ ЭТОГО НА WINDOWS НЕ РАБОТАЕТ НИЧЕГО. Пока в питоне не включён режим
+     * UTF-8, он печатает в кодовой странице системы (cp1251 на русской, cp1252
+     * на английской), а Node декодирует ребёнка как UTF-8 — и весь ответ
+     * приезжал нечитаемым: «????? ???: /??? ??????.mp4». Отдельно ломался
+     * preview: строка JSON у нас с русскими ключами, и поле `файл` выходило
+     * undefined. Свой код мы чиним вызовом (`engine/encoding.py`), а чужие
+     * библиотеки внутри того же процесса — только средой. Нужны оба заслона.
+     */
+    pythonEnv(): NodeJS.ProcessEnv;
+    /**
+     * Есть ли на машине python вообще — и словами, если нет.
+     *
+     * Весь движок (включая проверку и установку) идёт через запуск python'а.
+     * Когда его нет, `execFile` бросает ENOENT, и клиентской нейросети
+     * доставалось «spawn python3 ENOENT» — текст, из которого человеку не понять
+     * ничего. Шаг «python», написанный ровно для этого случая, при этом
+     * недостижим по устройству: он сам запускается python'ом.
+     *
+     * На Windows есть отдельная беда: в PATH лежит заглушка Microsoft Store —
+     * `python` там есть, он печатает рекламу магазина и выходит с кодом 9009.
+     * Поэтому проверяем не наличие файла, а ответ на вопрос о версии.
+     */
+    pythonTrouble(): Promise<string | null>;
+    /**
+     * Запустить команду движка и отдать её текст как есть.
+     *
+     * Умолчание таймаута заведомо БОЛЬШЕ внутренних таймаутов движка (самый
+     * долгий — опрос окружения пака, 180 с). Внешний таймаут короче внутреннего
+     * означает, что внутренний недостижим: пробник убивался снаружи, и его
+     * объяснение не доезжало до человека вовсе.
+     */
+    command(args: string[], { maxBuffer, timeout, key, }?: {
+        maxBuffer?: number;
+        timeout?: number;
+        key?: string;
+    }): Promise<CommandOutcome>;
+    /**
+     * Сырой запуск консоли движка. Наружу нужен затем, что часть работы
+     * (заведение задания, показ кадра) читает не текст, а JSON.
+     */
+    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>;
+    /**
+     * Паспорт пака. Читается один раз за жизнь процесса: состав пака при
+     * работающей программе не меняется, а спрашивать его подпроцессом на каждый
+     * вызов инструмента — лишние полсекунды на ровном месте.
+     *
+     * ⚠ ТАЙМАУТ КОРОТКИЙ, И ЭТО НЕСУЩЕЕ. Паспорт читается НА СТАРТЕ, до
+     * регистрации инструментов, — то есть внутри рукопожатия, которое клиент
+     * ждёт по своему таймауту (у Codex это 10 секунд по умолчанию). Команда
+     * честно занимает доли секунды: запустить питон и прочитать pack.json.
+     * Не уложилась — с паком что-то не так, и правильный размен здесь такой:
+     * потерять подсказки со списками моделей, но поднять сервер. Обратный
+     * размен означал бы «сервер не запустился» и молчание вместо объяснения.
+     */
+    passport(): Promise<PackPassport | null>;
+    /**
+     * Запустить фоновую работу движка, заранее заведя под неё задание.
+     *
+     * Задание заводится ДО запуска и отдельной командой: если запуск не удастся,
+     * задача всё равно видна, и человеку есть что показать. Формат файла знает
+     * только питон — эта сторона его не пишет, чтобы у файла не было двух хозяев
+     * на разных языках.
+     *
+     * Предохранителя параллельности здесь нет намеренно. Он в питоне
+     * (`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/subscription.py`) и берёт ключ
+         * из `NAPARNIK_API_KEY`, а `pythonEnv()` его оттуда вычищает намеренно:
+         * иначе ключ уезжает в каждого потомка питона — ffmpeg, pip, чужой код
+         * пака. Поэтому не «вернуть ключ в среду», а доложить его точечно, ровно
+         * как уже сделано у скачивания движка (`run`, поле `key`).
+         */
+        key: string | undefined;
+    }): Promise<{
+        id: string;
+    } | {
+        refusal: string;
+    }>;
+    /**
+     * Файл, куда фоновая работа пишет свой stderr.
+     *
+     * Лежит в доме, а не рядом с видео: у установки видео нет вовсе, а ответ на
+     * вопрос «что она успела сказать перед смертью» нужен одинаково обоим.
+     * Держим последние `KEEP_LOGS` — полоса загрузки модели пишет сотни
+     * килобайт, и вечная папка таких файлов была бы платой человека за то, что
+     * он однажды монтировал.
+     */
+    private openLog;
+    /**
+     * Присмотр за фоновой работой: перевести её смерть в состояние задания.
+     *
+     * Один на монтаж и на установку. Двумя копиями это было бы двумя разными
+     * ответами человеку на одну и ту же беду.
+     */
+    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;
+
+/** Определение ресурса в 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;
+}
+/**
+ * Текстовый блок в результате инструмента.
+ * Используется внутри 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>;
+}
+
+/**
+ * Аргументы инструмента: ОДНА запись на объявление модели и на проверку входа.
+ *
+ * ⚠ ЧТО ЗДЕСЬ БЫЛО ДО 2026-09-09 И ПОЧЕМУ ЭТО ПРИШЛОСЬ ПЕРЕДЕЛАТЬ. Форма
+ * аргументов была написана ДВАЖДЫ: JSON Schema рядом с каждым инструментом (её
+ * читает модель — иначе она не знает, что слать) и разбор этой же схемы руками в
+ * `arg-check.ts` (без него `arguments` от модели уходили в питон как есть).
+ * Обе копии были верны по отдельности и разойтись могли только МОЛЧА: схема
+ * обещает модели одно, проверка требует другого, а узнаёт об этом человек —
+ * отказом на то, что ему разрешили, или опиской, уехавшей внутрь платной
+ * операции. Ни один тест такого расхождения не видел: каждая половина
+ * проверялась своей.
+ *
+ * Теперь схема пишется на zod один раз, а JSON Schema ВЫВОДИТСЯ из неё
+ * (`docs/architecture.md` р. 24, «Один источник правды — схема на zod»).
+ * Расхождение стало невозможным по построению, а не по договорённости.
+ *
+ * ⚠ ПОЧЕМУ `zod/v4`, А НЕ КОРЕНЬ ПАКЕТА. Вывод JSON Schema из схемы умеет сама
+ * библиотека — `z.toJSONSchema`, и он есть только в четвёртой версии. Пакет
+ * `zod@3.25` отдаёт её подпутём `zod/v4`, поэтому ставить ничего не пришлось. И
+ * поэтому же на `zod/v4` переведены ВСЕ места пакета: две копии библиотеки в
+ * бандле — это 726 КБ вместо 398 КБ на машине покупателя (замерено сборкой), а
+ * бандл уезжает целиком, `node_modules` внутри `.mcpb` нет.
+ *
+ * ⚠ СВОЮ ФУНКЦИЮ ВЫВОДА МЫ НЕ ПИШЕМ НАМЕРЕННО. Наше подмножество JSON Schema
+ * маленькое (строка, число, флаг, список, перечисление, пояснение), и обойти
+ * его в шестьдесят строк можно. Но такая функция читает приватное устройство
+ * схем zod, то есть становится ровно той второй правдой, от которой мы здесь
+ * избавляемся, — только уже про чужой формат.
+ */
+
+/** Схема аргументов инструмента: всегда объект — таков контракт MCP. */
+type ArgsSchema = z.ZodObject;
+/**
+ * Инструмент, у которого схема аргументов есть.
+ *
+ * ⚠ ПОЛЕ ОБЯЗАТЕЛЬНОЕ, И ЭТО НЕСУЩЕЕ. Заслон навешивается при сборке набора
+ * (`tool-registry.ts`), а не внутри каждого `execute`. Будь схема
+ * необязательной, инструмент без неё зарегистрировался бы молча и остался бы
+ * единственным без проверки — то есть повторилась бы беда, из-за которой заслон
+ * и появился. Здесь это ловит не тест, а тип: собрать такой инструмент нечем.
+ */
+interface CheckedTool extends Tool {
+    readonly argsSchema: ArgsSchema;
+}
+/** Что не так с аргументами — или `null`, если всё сходится. */
+declare function refusalFor(schema: ArgsSchema, input: Record<string, unknown>): string | null;
+/**
+ * Объявление для модели — выводом из схемы.
+ *
+ * `$schema` снимается: клиент MCP ждёт схему аргументов, а не самостоятельный
+ * документ, и лишний ключ у части клиентов уезжает в промпт модели как есть.
+ *
+ * `required` отдаётся списком всегда, даже пустым: пропавшее поле разные клиенты
+ * читают по-разному, пустой список — одинаково. Так же выглядели все схемы до
+ * перехода на zod, и менять форму объявления мы не собирались.
+ */
+declare function jsonSchemaOf(schema: ArgsSchema): ToolInputSchema;
+/**
+ * Инструмент из схемы: объявление выведено, вход разобран, тело получает свой тип.
+ *
+ * ⚠ РАЗБОР ЕСТЬ И ЗДЕСЬ, И В ОБЁРТКЕ `withArgs`, И ЭТО НЕ ДВЕ ПРАВДЫ. Правило
+ * одно — схема, — а вызовов проверки два, потому что задачи разные. Обёртка
+ * стоит на регистрации и отбивает описку ДО заслона подписки, то есть до сети.
+ * Разбор здесь страхует прямой вызов: обёртку однажды снимут «для отладки» или
+ * забудут навесить на новую полку, и без этой страховки `execute` получил бы
+ * `arguments` от модели как есть — ровно то, из-за чего заслон и появился.
+ * Второй `safeParse` над уже чистым объектом стоит микросекунды против минут
+ * работы питона.
+ */
+declare function defineTool<S extends ArgsSchema>(spec: {
+    name: string;
+    description: string;
+    args: S;
+    /** Название по-русски — его человек видит в настройках хоста */
+    title?: string;
+    readOnly?: boolean;
+    /** Переписывает то, что у человека уже есть (`protocol/tool.ts`) */
+    destructive?: boolean;
+    /**
+     * Виджет инструмента (MCP Apps): адрес `ui://…` ресурса с HTML формы.
+     *
+     * ⚠ ПРОХОДИТ ЧЕРЕЗ ЭТУ ЖЕ ДВЕРЬ НАМЕРЕННО. Инструмент с формой в ленте — это
+     * всё тот же инструмент: аргументы у него разбираются той же схемой, и
+     * заводить ему второй способ объявиться значило бы завести полку, на которой
+     * заслон аргументов однажды забудут навесить.
+     */
+    ui?: {
+        resourceUri: string;
+    };
+    /**
+     * Тело инструмента. Контекст вызова — вторым доводом и необязательным.
+     *
+     * ⚠ НЕОБЯЗАТЕЛЕН ПОТОМУ, ЧТО ЕГО МОЖЕТ НЕ БЫТЬ: прямой вызов из теста
+     * контекста не передаёт, а у чужого клиента может не быть `emitProgress`
+     * (рассказ о ходе работы он не просил). Инструменты, которым ход не нужен,
+     * второй довод просто не объявляют.
+     */
+    execute: (args: z.output<S>, ctx?: ToolContext) => Promise<ToolResult>;
+}): CheckedTool;
+/**
+ * Тот же инструмент, но со сверкой аргументов перед вызовом.
+ *
+ * Обёртка, а не правка каждого `execute`: инструментов четырнадцать, и
+ * четырнадцать копий одной проверки — это четырнадцать мест, где её однажды
+ * забудут. Порядок в `tool-registry.ts` несущий: эта обёртка СНАРУЖИ заслона
+ * подписки, иначе описка в аргументах сначала гнала бы запрос в сеть.
+ */
+declare function withArgs<T extends CheckedTool>(tool: T): T;
+
+/**
+ * Ход работы словами: что делаю сейчас, что дальше, сколько примерно осталось.
+ *
+ * Решение владельца 2026-09-10: «ты сидишь, ждёшь и не понимаешь, что
+ * происходит, на каком этапе, сколько осталось — и с установкой то же самое».
+ * Отсюда два куска, и они про разное время:
+ *
+ *   - ЛЕСТНИЦА ШАГОВ — говорится СРАЗУ, до того как работа уйдёт в фон: что
+ *     будет сделано и в каком порядке. Ближние шаги подробнее, дальние одной
+ *     строкой;
+ *   - `followJob` — рассказ ПО ХОДУ: пока задание считается, каждая новая
+ *     строка его состояния уходит человеку, и опрашивать инструмент вручную
+ *     раз в полминуты больше не нужно.
+ *
+ * ⚠ ВНУТРЕННОСТЕЙ В ЭТИХ СЛОВАХ БЫТЬ НЕ МОЖЕТ: ни команд, ни путей в недрах,
+ * ни имён библиотек, ни трейсбеков. Человек должен понять, где он сейчас, а не
+ * узнать, как продукт устроен. Сторожит это `progress.test.ts` — по настоящим
+ * строкам, собранным с прогона инструментов, а не по копии списка слов.
+ *
+ * ⚠ ПОЧЕМУ ЛЕСТНИЦА ПЕРЕВОДИТ ИМЕНА ЭТАПОВ, А НЕ БЕРЁТ ГОТОВЫЕ СЛОВА. Список
+ * этапов один и лежит в паспорте пака (`stages`), но человеческих названий у
+ * этапов паспорт не отдаёт — они лежат в паспортах шагов (`step.json`, ключ
+ * `title`), и оболочка их не читает. Поэтому здесь СЛОВАРЬ ИМЯ → РЕЧЬ, а не
+ * второй список этапов: порядок и состав по-прежнему приходят из паспорта, а
+ * незнакомое имя просто не попадает в рассказ. Появятся названия в паспорте —
+ * словарь уйдёт, и это будет правильнее.
+ */
+
+/**
+ * Время и ожидание — снаружи, а не таймером в теле.
+ *
+ * ⚠ ЭТО НЕ УКРАШЕНИЕ РАДИ ТЕСТА, А ЕДИНСТВЕННЫЙ СПОСОБ ЕГО НАПИСАТЬ. Ждать
+ * по-настоящему в тесте нельзя (`docs/testing.md`: ожидания по таймеру и
+ * `sleep` запрещены), а цикл опроса без подмены времени проверяется только
+ * минутным прогоном — то есть не проверяется никогда.
+ */
+interface Pace {
+    /** Сколько прошло, в миллисекундах. */
+    now: () => number;
+    /** Подождать столько миллисекунд. */
+    rest: (ms: number) => Promise<void>;
+}
+
+/**
+ * Набор инструментов покупателя — одним списком и под одними обёртками.
+ *
+ * ⚠ ИХ ВОСЕМЬ, И ЭТО РЕШЕНИЕ ВЛАДЕЛЬЦА 2026-09-17 («у модели шесть рабочих
+ * инструментов»). Рабочих действительно шесть: `setup`, `plan`, `plan_edit`,
+ * `render`, `preview`, `choose_variant`. Ещё два добавлены механикой хоста, а
+ * не желанием: `wait` — потому что полоса хода работы объявлена НА
+ * ИНСТРУМЕНТЕ (`protocol/server.ts`), и ожидание тем же `render` рисовало бы
+ * новую полосу на каждый вызов; `variant_chosen` — потому что в Codex виджетов
+ * нет, выбор приходит словами, и звать запись модель должна сама.
+ *
+ * ⚠ ДО 2026-09-18 ИХ БЫЛО ДВАДЦАТЬ ПЯТЬ, И ЭТО БЫЛО ДОРОГО НЕ КРАСОТОЙ. Каждое
+ * объявление модель перечитывает каждым ходом, а ход стоит 8–19 секунд
+ * (`docs/architecture.md` р. 26). Двадцать пять дверей к пятнадцати работам
+ * означали и второй счёт: модель путала соседние двери — «покажи варианты» шло
+ * в `style_check`, который без движка отвечал отказом. Одна дверь на работу,
+ * ветку внутри выбирают аргументы.
+ *
+ * ⚠ ЗАЧЕМ ОТДЕЛЬНЫЙ МОДУЛЬ РАДИ ДВУХ СТРОК. Проверять надо ТОТ САМЫЙ список,
+ * который уезжает клиенту, а не собранную рядом копию: сними обёртку сверки —
+ * и тест по копии остался бы зелёным (проверено мутацией, так и вышло). Пока
+ * список жил в `cli.ts`, отдельно от сборки сервера его было не достать.
+ *
+ * ⚠ И ЭТОТ ДОВОД ПЕРЕПИСАН ДВАЖДЫ. Сначала здесь стояло «`cli.ts` при импорте
+ * ПОДНИМАЕТ СЕРВЕР» — неправда с тех пор, как авто-запуск закрыт проверкой
+ * `launchedDirectly()`. Потом вместо этого стояла ссылка на `cli.test.ts`, а
+ * он ушёл 2026-09-17 вместе с агентами покупателя: проверять в старте стало
+ * нечего. Довод остался один, тот, что в начале: ЗДЕСЬ СОБИРАЕТСЯ НАСТОЯЩИЙ
+ * СПИСОК, и тесты берут его отсюда.
+ *
+ * ⚠ ПОЛКА ОСТАЛАСЬ ОДНА, И ЭТО РЕШЕНИЕ, А НЕ УПРОЩЕНИЕ. Раньше их было три:
+ * монтаж, данные Напарника (рилсы, баланс, распаковка, генерация) и обмен
+ * фирменным стилем. Вторая и третья ходили в PHP API монолита —
+ * `company.naparnik.ai`, — а монолит гасится (docs/architecture.md, раздел 20).
+ * Инструмент, который в день гашения начнёт врать «сервер не ответил», хуже
+ * отсутствующего: человек будет чинить связь вместо того, чтобы узнать, что
+ * фичи больше нет. Поэтому обе полки убраны из поставки целиком.
+ *
+ * Что осталось: монтаж, который идёт НА КОМПЬЮТЕРЕ КЛИЕНТА, и заслон подписки,
+ * который спрашивает НАШ сервер. Больше этот пакет никуда не ходит.
+ */
+
+declare function buildAll(client: NaparnikApiClient, engine: Engine, passport: PackPassport | null, 
+/**
+ * Ключ Напарника. Нужен трём разным работам, и все три — за деньги:
+ * установщику движка (раздача закрыта авторизацией), черновику плана и цвету
+ * по двум кадрам (обе команды движка стоят в `UNDER_SUBSCRIPTION`).
+ */
+key: string | undefined, 
+/**
+ * Адрес нашего сервера. Он же адрес раздачи: указатель начинки лежит на том
+ * же хосте, что и API (`config.ts`, `DEFAULT_BASE_URL`).
+ */
+baseUrl: string, 
+/**
+ * Время и ожидание — для цикла `wait`, который ждёт задание и рассказывает ход.
+ *
+ * ⚠ ПАРАМЕТРОМ, А НЕ ТАЙМЕРОМ В ТЕЛЕ, И ЭТО ЕДИНСТВЕННЫЙ СПОСОБ ПРОВЕРИТЬ
+ * ЦИКЛ. Ожидания по таймеру и `sleep` в тестах запрещены (`docs/testing.md`),
+ * а цикл без подмены времени проверялся бы минутным прогоном — то есть
+ * никогда. Умолчание обычное, вызывающему про это знать не надо.
+ */
+pace?: Pace): Tool[];
+/**
+ * Ресурсы виджетов — парой к `buildAll`, из того же файла: кто собирает
+ * сервер из инструментов, здесь же берёт и HTML к ним. Сторож пары — тест
+ * «у каждого инструмента с виджетом есть ресурс» в `tool-declaration.test.ts`.
+ */
+declare function buildResources(): Array<{
+    resource: McpResource;
+    contents: McpResourceItemContent[];
+}>;
+
+/** Что скачали и чем это оказалось. */
+interface Downloaded {
+    file: string;
+    bytes: number;
+    sha256: string;
+}
+/** Беда доставки, у которой есть человеческий текст. */
+declare class DeliveryError extends Error {
+    constructor(message: string);
+}
+/**
+ * Скачать файл целиком и сверить сумму.
+ *
+ * Пишем во времянку рядом и переименовываем: недокачанный файл не должен ни
+ * секунды выглядеть готовым — на этом уже обжигались в питоновской докачке.
+ */
+declare function downloadFile(opts: {
+    url: string;
+    dest: string;
+    sha256: string;
+    bytes?: number;
+    timeoutMs?: number;
+    report?: (text: string) => void;
+    /**
+     * Ключ Напарника. Раздача движка закрыта авторизацией: без ключа приедет 403.
+     * Необязателен, потому что этим же загрузчиком качается открытая поставка
+     * расширения — заставлять её носить ключ значило бы обещать связь, которой нет.
+     */
+    /**
+     * Ключ Напарника — или явное `null`, если его нет.
+     *
+     * ⚠ ПОЛЕ ОБЯЗАТЕЛЬНОЕ, ХОТЯ ЗНАЧЕНИЕ МОЖЕТ БЫТЬ ПУСТЫМ. Пока оно было
+     * необязательным (`key?`), забыть его по дороге было нечем поймать: ключ
+     * протаскивается через шесть вызовов подряд, и пропуск на любом из них давал
+     * молчаливое скачивание без авторизации. Раньше это было незаметно — раздача
+     * стояла открытой. Теперь она закрыта, и та же описка превратилась бы в
+     * «не принял ключ» у платящего человека, причём без единой подсказки, что
+     * ключ просто не доехал. Обязательное поле заставляет вызывающего сказать
+     * вслух, что ключа нет.
+     */
+    key: string | null;
+}): Promise<Downloaded>;
+interface TarEntry {
+    name: string;
+    kind: 'file' | 'dir' | 'symlink' | 'hardlink';
+    mode: number;
+    body: Buffer;
+    target: string;
+}
+/**
+ * Разобрать `.tar` (уже распакованный из gzip) на записи.
+ *
+ * ⚠ СВОЙ РАЗБОР, А НЕ ВЫЗОВ `tar`. Системный `tar` есть не везде (на Windows
+ * он появился только в свежих сборках), а на macOS он ещё и молча впитывает
+ * обратно свои двойники `._имя` — то есть показывает не то, что получит
+ * клиент. Формат простой и стабильный: заголовок в 512 байт, тело кратно 512.
+ */
+declare function tarEntries(data: Buffer): TarEntry[];
+/**
+ * Остаётся ли путь внутри целевой папки.
+ *
+ * ⚠ ПРОВЕРЯЕМ СОБРАННЫМ ПУТЁМ, А НЕ НАЛИЧИЕМ «..» В СТРОКЕ. Архив приезжает из
+ * интернета, и «../../.ssh/authorized_keys» в имени члена — известный приём
+ * (zip slip); хитрое имя обходит проверку строкой, но не проверку путём. Тот
+ * же заслон и теми же словами стоит в питоне (`install._inside`).
+ */
+declare function inside(root: string, path: string): boolean;
+/**
+ * Разложить `.tar.gz` целиком в папку.
+ *
+ * Всё, что пытается выйти за `dest` (именем члена или целью ссылки), — ОТКАЗ
+ * ЦЕЛИКОМ, а не «пропустим этот файл». Наполовину распакованное дерево
+ * выглядит установленным и падает потом, в чужом месте.
+ */
+declare function unpackArchive(archive: string, dest: string): void;
+
+interface StepOutcome {
+    ok: boolean;
+    text: string;
+}
+interface FirstInstallTestHooks {
+    afterPublishRename?(): void;
+}
+/** Где внутри начинки лежит общая таблица источников питона. */
+declare const SOURCES_FILE = "python-sources.json";
+interface PythonSource {
+    url: string;
+    sha256: string;
+    mb: number;
+}
+/**
+ * Ключ платформы ровно в том виде, в каком его пишет питон:
+ * `platform.system()`-`platform.machine()`. Совпадение обязано быть точным —
+ * таблица одна на две стороны.
+ */
+declare function platformKey(os?: NodeJS.Platform, arch?: string): string | null;
+/** Прочитать таблицу питона из установленной начинки. */
+declare function pythonSource(engineDir: string, key?: string | null): PythonSource | null;
+/**
+ * Доставить начинку, когда движка нет вовсе.
+ *
+ * Согласие спрашивается ровно так же, как у остальных шагов установки: это
+ * трафик человека, его диск и чужой исполняемый код на его машине.
+ */
+declare function installPayload(engine: Engine, opts: {
+    consent: boolean;
+    manifestUrl: string;
+    key?: string | undefined;
+}, hooks?: FirstInstallTestHooks): Promise<StepOutcome>;
+/**
+ * Доставить портативный python, когда системного нет.
+ *
+ * ⚠ ЭТО НЕ ДУБЛЬ ШАГА «python» ДВИЖКА, А ЕГО ЕДИНСТВЕННЫЙ ДОСТУПНЫЙ ПУТЬ НА
+ * ЧИСТОЙ МАШИНЕ. Как только питон появился, шаг движка снова работает и делает
+ * ровно то же самое — оттуда и таблица источников, и место установки.
+ */
+declare function installPython(engine: Engine, opts: {
+    consent: boolean;
+    version?: string;
+}): Promise<StepOutcome>;
 
 /**
  * Иерархия ошибок клиента Напарника.
@@ -72,19 +1243,27 @@ declare class NaparnikScopeError extends NaparnikError {
  */
 declare class NaparnikInsufficientBalanceError extends NaparnikError {
     readonly details: {
-        /** Что упёрлось: баланс компании или дневной потолок ключа. */
-        limit: 'company_balance' | 'token_daily';
+        /**
+         * Что упёрлось. Пока единственная причина — баланс компании; поле
+         * оставлено перечислением, чтобы форма не менялась, если появится
+         * второй источник отказа.
+         */
+        limit: 'company_balance';
         balanceRub: number;
         requiredRub: number;
-        /** Куда идти пополнять (или менять лимит ключа). */
+        /** Куда идти пополнять. */
         actionUrl: string;
     };
     constructor(message: string, details: {
-        /** Что упёрлось: баланс компании или дневной потолок ключа. */
-        limit: 'company_balance' | 'token_daily';
+        /**
+         * Что упёрлось. Пока единственная причина — баланс компании; поле
+         * оставлено перечислением, чтобы форма не менялась, если появится
+         * второй источник отказа.
+         */
+        limit: 'company_balance';
         balanceRub: number;
         requiredRub: number;
-        /** Куда идти пополнять (или менять лимит ключа). */
+        /** Куда идти пополнять. */
         actionUrl: string;
     });
 }
@@ -115,4 +1294,299 @@ declare class NaparnikTimeoutError extends NaparnikError {
 declare class NaparnikConfigError extends NaparnikError {
 }
 
-export { NaparnikApiClient, NaparnikAuthError, NaparnikClientError, NaparnikConfigError, NaparnikError, NaparnikInsufficientBalanceError, type NaparnikMcpConfig, NaparnikScopeError, NaparnikServerError, NaparnikTimeoutError, createNaparnikTools, loadConfig };
+/**
+ * Версия оболочки.
+ *
+ * ⚠ РАНЬШЕ ЭТОТ ФАЙЛ СОБИРАЛСЯ, ТЕПЕРЬ ПРАВИТСЯ РУКАМИ. Генератор жил в
+ * монолите и в этот репозиторий пока не переехал — он в одной связке
+ * со сборкой поставки, а движок монтажа ещё в монолите. Значит правится два
+ * места сразу: `version` в package.json и строка ниже.
+ *
+ * Чтобы «два места» не разъехались молча, за ними смотрит `version.test.ts`.
+ * Версия — это то, чем оболочка представляется серверу и по чему сервер решает,
+ * годится ли она для новой начинки: разойдись она с пакетом, и в логах будет
+ * стоять чужое число, а обновление начнёт считать оболочку не той.
+ */
+declare const VERSION = "0.10.11";
+/** Как мы представляемся серверу Напарника. По нему в логах видно оболочку. */
+declare const USER_AGENT = "naparnik-mcp/0.10.11";
+/**
+ * Самая старая начинка (движок монтажа), с которой эта оболочка работает.
+ * Обновление начинки ниже этой версии не ставится, а выше — требует оболочки
+ * не старше, чем объявлено в самой начинке.
+ *
+ * ⚠ ЭТО ВТОРАЯ ПОЛОВИНА ЗАМКА, И ПОДНИМАТЬ ЕЁ НАДО ВМЕСТЕ С ПЕРВОЙ. Первая —
+ * `min_shell` в `client/engine/version.json` («ниже этой оболочки начинку не
+ * отдавать»), вторая здесь («ниже этой начинки обновление не брать»). Подними
+ * одну — и свежая оболочка честно поставит себе начинку, которая лежит в
+ * раздаче СЕЙЧАС, старого вида. Обе половины названы в `docs/architecture.md`
+ * р. 24 и поднимаются одним коммитом.
+ *
+ * ⚠ ПОЧЕМУ ИМЕННО «2026.09.13-1». Волна цвета подняла договор
+ * вопросов формы на naparnik-choices/3 и завела команды capabilities и
+ * choose-apply: начинка старше их не знает, и эта оболочка с ней осталась бы без
+ * каталога и без памяти выбора — с отказом словами, но без формы. Номер сборки
+ * выводится выкладкой как «<дата UTC>-<номер конвейера>»
+ * (`tools/delivery/build-engine.ts`), значит сборка волны и любая следующая за
+ * ней дают число не меньше этого, а всё прежнее отсекается. Число совпадает с
+ * `version` в `client/engine/version.json`: там оно тоже поднято волной.
+ * Прежний замок — «2026.09.09-192», волна латиницы.
+ *
+ * ⚠ ЧИСЛО ОТСЕКАЕТ ПРОШЛУЮ ВОЛНУ, А НЕ УГАДЫВАЕТ СВОЮ. Сборка этой волны
+ * получит номер «2026.09.13-<номер конвейера>» — он больше, и замок её
+ * пропустит; начинка прошлой волны («2026.09.12-230») не знает вида «range» и
+ * отсекается. Ревью 2026-09-13 поймало ровно это: обе половины замка обязаны
+ * подниматься вместе, иначе свежая оболочка честно ставит себе начинку без
+ * ползунков и встречает человека отказом договора.
+ *
+ * ⚠ ДАТА В НОМЕРЕ — UTC, А НЕ МЕСТНАЯ. Сначала здесь стояло «2026.09.13-1» —
+ * по московскому календарю верно, а выкладка в тот же час собрала
+ * «2026.09.12-230»: по UTC было ещё двенадцатое. Замок отверг собственную
+ * сборку, и прогон покупателя на стенде честно встал на install_engine со
+ * словами «раздача ещё не обновилась». Номер берётся из УЖЕ СОБРАННОГО
+ * артефакта этой волны, а не сочиняется по календарю.
+ */
+declare const MIN_ENGINE = "2026.09.19-355";
+
+/**
+ * Что вышло из установки или отката — одними словами у начинки и у тела.
+ *
+ * ⚠ ТИП ЗДЕСЬ, А НЕ У КАЖДОГО СВОЙ. Копий было две, и вторая приехала с
+ * подписью «теми же словами, что и у начинки» — то есть автор уже знал, что это
+ * копия. Модель читает оба ответа одинаково; разойдись форма, и половина
+ * разговора про обновление стала бы другой.
+ */
+interface InstallOutcome {
+    ok: boolean;
+    text: string;
+}
+/** Прежний публичный минимум хранения; GC не применяет его без leases. */
+declare const KEEP_VERSIONS = 2;
+/** Не чаще раза в столько часов дёргаем сеть на старте. */
+declare const PAUSE_HOURS = 6;
+/**
+ * Сравнение версий по числовым кускам: «2026.08.20-1» и «0.3.0» одинаково
+ * раскладываются на числа. Строковое сравнение здесь врёт на первом же
+ * двузначном числе («0.10.0» оказывалось бы меньше «0.9.0»).
+ */
+declare function compare(a: string, b: string): number;
+
+/** Указатель на свежую начинку — НАШ объект, собранный разбором ниже. */
+interface EngineManifest {
+    /** Версия начинки. Она же станет именем папки на диске человека. */
+    version: string;
+    /** Полный адрес архива. Обязан лежать на том же хосте, что и указатель. */
+    url: string;
+    sha256: string;
+    bytes: number;
+    /** Ниже этой версии оболочка эту начинку не примет. */
+    minShellVersion: string;
+}
+/** Что вышло из разбора: объект — или причина, по которой его нет. */
+type ManifestOutcome = Parsed<EngineManifest>;
+/**
+ * Разобрать указатель.
+ *
+ * @param raw что приехало по сети — доверять нечему, тип `unknown` намеренно
+ * @param from адрес самого указателя: по нему проверяется, что архив лежит рядом
+ */
+declare function parseEngineManifest(raw: unknown, from: string): ManifestOutcome;
+/**
+ * Что вышло из разбора: наш объект — или причина, по которой его нет.
+ * Одна форма на оба указателя.
+ */
+type Parsed<T> = {
+    ok: true;
+    manifest: T;
+} | {
+    ok: false;
+    why: string;
+};
+
+/** Умолчание: раздача прода. Одна правда с адресом API — `config.ts`. */
+declare const MANIFEST_URL: string;
+/** Потолок ожидания манифеста — общий с указателем оболочки. */
+declare const MANIFEST_TIMEOUT_MS = 2000;
+/**
+ * Указатель начинки и его разбор живут в `manifest.ts` — там же кончается чужой
+ * формат с русскими ключами. Здесь ходит уже НАШ объект.
+ */
+type Decision = {
+    what: 'nothing';
+} | {
+    what: 'shell_too_old';
+    manifest: EngineManifest;
+} | {
+    what: 'newer_available';
+    manifest: EngineManifest;
+};
+
+/** Спросить указатель начинки. Механика — общая, `manifest.ts`, `askPointer`. */
+declare function fetchManifest(url?: string, timeoutMs?: number, key?: string): Promise<ManifestOutcome>;
+/** Что делать с тем, что приехало в манифесте. */
+declare function decide(installed: string | null, manifest: EngineManifest | null, shellVersion?: string): Decision;
+declare function timeToCheck(engine: UpdateDeps, now?: number): boolean;
+declare function markChecked(engine: UpdateDeps, now?: number): void;
+/** Какая версия была рабочей до последнего обновления. */
+declare function previousVersion(engine: UpdateDeps): string | null;
+/** Сделать версию рабочей. */
+declare function markCurrent(engine: UpdateDeps, version: string): void;
+/** Убрать всё, кроме текущей и предыдущей; улику `broken-*` бережём. */
+declare function tidyOld(engine: UpdateDeps): string[];
+
+/**
+ * Что обновлению нужно от движка — интерфейсом, а не классом.
+ *
+ * ⚠ ЭТО ШОВ ДЛЯ ПРОВЕРКИ, А НЕ УКРАШЕНИЕ. Настоящий `Engine` на каждый шаг
+ * поднимает питон; живой прогон против настоящего движка лежит рядом —
+ * `update.test.ts`, «дымовой прогон против настоящего движка». А решения, ради
+ * которых обновление и написано, — переключать или нет, что сохранить при
+ * откате, что снести, — проверяются подставным прогоном там же, и проверяются
+ * ПОЛНОСТЬЮ, включая ветку «скачалось, но не запускается», которую живым
+ * прогоном воспроизвести нечем.
+ *
+ * ⚠ Раньше здесь стояла ссылка на `mcp-editor/test-update.ts` — папки такой в
+ * репозитории нет. Обещание «живое проверено где-то там» и было единственным,
+ * что стояло между нами и полугодовым молчанием этой границы.
+ */
+interface UpdateDeps {
+    place(): EnginePlace | null;
+    whyNoEngine(): string;
+    versionsDir(): string;
+    freshVersion(): string | null;
+    command(args: string[], opts?: {
+        timeout?: number;
+        key?: string;
+    }): Promise<CommandOutcome>;
+    enginePython(): string;
+    pythonEnv(): NodeJS.ProcessEnv;
+}
+interface DeployTestHooks {
+    afterPublishRename?(): void;
+}
+/**
+ * Скачать, разложить, проверить запуском и переключиться.
+ *
+ * ⚠ КАЧАЕТ ТЕКУЩАЯ УСТАНОВЛЕННАЯ ВЕРСИЯ. Это не хитрость, а единственный
+ * способ не заводить второй загрузчик: докачка с обрыва, разбор 416 и сверка
+ * суммы уже написаны в движке и покрыты тестами. Движка нет вовсе — это не
+ * обновление, а первая установка, и она идёт через `install_engine`.
+ */
+declare function deploy(engine: UpdateDeps, manifest: EngineManifest, trial?: Trial, 
+/** Ключ для закрытой раздачи движка: без него скачивание получит 403. */
+key?: string, hooks?: DeployTestHooks): Promise<InstallOutcome>;
+/**
+ * Дымовой прогон новой сборки: запускается ли она вообще и та ли это версия.
+ * Возвращает текст беды или null, если всё в порядке.
+ */
+type Trial = (engine: UpdateDeps, consolePy: string) => Promise<{
+    stdout: string;
+}>;
+/** Запуск `console.py версия` новой сборки — тем же питоном, что и всё прочее. */
+declare function probe(engine: UpdateDeps, consolePy: string): Promise<{
+    stdout: string;
+}>;
+/** Вернуться на предыдущую версию. */
+declare function rollback(engine: UpdateDeps): InstallOutcome;
+
+/** Имя сервера в конфиге Codex. Оно же — имя блока. */
+declare const SERVER_NAME = "naparnik";
+/**
+ * Пометка владения. Стоит СТРОКОЙ ВЫШЕ заголовка блока: по ней мы отличаем
+ * «наше, можно переписывать» от «человек написал сам, руки прочь».
+ */
+declare const MARKER = "# \u0443\u0441\u0442\u0430\u043D\u043E\u0432\u043B\u0435\u043D\u043E \u041D\u0430\u043F\u0430\u0440\u043D\u0438\u043A\u043E\u043C, \u043E\u0431\u043E\u043B\u043E\u0447\u043A\u0430";
+/**
+ * Сколько ждать старта сервера и ответа инструмента.
+ *
+ * Умолчания Codex — 10 и 60 секунд. Старт мы укладываем и в 10 (паспорт пака
+ * читается с потолком в 8), но запас нужен на холодной машине, где питон ещё не
+ * в кэше файловой системы. А вот 60 секунд на инструмент мало: `inspect_video`
+ * на длинном ролике делает холодный проход ffprobe, ebur128 и silencedetect.
+ *
+ * ⚠ ЧИСЛА — ПРЕДПОЛОЖЕНИЕ. Проверить их можно только на живом Codex, которого у
+ * нас нет; здесь они записаны явно, чтобы правились одним местом, а не
+ * подбирались заново.
+ */
+declare const START_SEC = 20;
+declare const TOOL_SEC = 120;
+/**
+ * Что установщик сделал с конфигом.
+ *
+ * ⚠ ЗНАЧЕНИЯ ЛАТИНИЦЕЙ, ХОТЯ НАРУЖУ ОНИ НЕ ЕЗДЯТ. Это код, а код у нас
+ * английский (правило №0): человеку показывается `words` рядом, и вот он
+ * русский. Волна латиницы 2026-09-09 забрала их вместе с остальным проводом —
+ * ни один сторож эти значения не видит, значит сами они не почистились бы
+ * никогда.
+ */
+type Action = 'created' | 'added' | 'updated' | 'unchanged' | 'removed' | 'nothing_to_remove';
+interface Outcome {
+    file: string;
+    action: Action;
+    /** Куда положили копию прежнего файла. */
+    copy?: string;
+    words: string;
+}
+/** Чужой блок с нашим именем: не трогаем, показываем человеку. */
+declare class ForeignBlockError extends Error {
+    readonly block: string;
+    constructor(block: string, file: string);
+}
+/**
+ * Живём ли мы во временной распаковке `npx`.
+ *
+ * ⚠ ПРОПИСАТЬ ЭТОТ ПУТЬ В КОНФИГ — ЗНАЧИТ ОДНАЖДЫ ЕГО СЛОМАТЬ. `npx` кладёт
+ * пакет в `~/.npm/_npx/<хеш>/` — неуправляемый кэш, который сносят `npm cache
+ * clean`, чистильщики диска и корпоративные политики на `%LOCALAPPDATA%`
+ * (на этой машине там уже полсотни таких каталогов). После уборки Codex вечно
+ * рапортует «сервер не запустился», а в конфиге стоит путь, которого нет.
+ * Отказываемся ДО записи, а не разбираемся после пропажи.
+ */
+declare function fromNpxCache(path: string): boolean;
+/** Путь к общему конфигу Codex. Переменная — для тестов и нестандартных домов. */
+declare function configPath(env?: NodeJS.ProcessEnv): string;
+/** Наш блок целиком, включая пометку владения. */
+declare function buildBlock(entryFile: string, key?: string): string;
+interface FoundBlock {
+    start: number;
+    end: number;
+    text: string;
+    ours: boolean;
+}
+/**
+ * Где в файле лежит наш блок.
+ *
+ * ⚠ ДОЧЕРНИЕ ТАБЛИЦЫ ВХОДЯТ В БЛОК. `[mcp_servers.naparnik.env]` — это
+ * заголовок в первой колонке, и наивное «до следующего заголовка» обрезало бы
+ * блок перед ним. Тогда при обновлении старая таблица env оставалась бы в
+ * файле сиротой, а в ней лежит ключ: человек менял ключ, а работал старый.
+ */
+declare function findBlock(text: string): FoundBlock | null;
+/**
+ * Заведён ли наш сервер ВНУТРИ таблицы `[mcp_servers]`, а не своим заголовком.
+ *
+ * ⚠ ЭТО НЕ ЭКЗОТИКА, А ВТОРАЯ ЗАКОННАЯ ФОРМА ЗАПИСИ TOML. Человек мог написать
+ *
+ *     [mcp_servers]
+ *     naparnik = { command = "node", args = [...] }
+ *
+ * Наш поиск ищет только заголовок `[mcp_servers.naparnik]`, не находит его и
+ * дописывает блок — а TOML получает ДВА определения одного ключа и перестаёт
+ * разбираться целиком. Тогда у человека отваливаются ВСЕ серверы, а не только
+ * наш. Отказываемся так же, как при чужом блоке: показать и не трогать.
+ */
+declare function keyInTable(text: string): string | null;
+/** Сколько копий прежнего конфига держим рядом. */
+declare const KEEP_COPIES = 3;
+interface Settings {
+    /** Полный путь к `cli.js`, который будет запускать Codex. */
+    entryFile: string;
+    key?: string;
+    env?: NodeJS.ProcessEnv;
+}
+/** Прописать сервер в конфиг Codex. */
+declare function install(n: Settings): Outcome;
+/** Убрать наш блок и ничего кроме него. */
+declare function remove(env?: NodeJS.ProcessEnv): Outcome;
+
+export { type ArgsSchema, type CheckedTool, type CommandOutcome, DEFAULT_HOME, type Decision, DeliveryError, Engine, type EngineManifest, type EnginePlace, ForeignBlockError, INSIDE_PYTHON, INSTALL_STEPS, type InstallOutcome, KEEP_COPIES, KEEP_VERSIONS, LONG_STEPS, MANIFEST_TIMEOUT_MS, MANIFEST_URL, MARKER, MIN_ENGINE, type ManifestOutcome, NaparnikApiClient, NaparnikAuthError, NaparnikClientError, NaparnikConfigError, NaparnikError, NaparnikInsufficientBalanceError, type NaparnikMcpConfig, NaparnikScopeError, NaparnikServerError, NaparnikTimeoutError, type Outcome, PAUSE_HOURS, type PackPassport, SERVER_NAME, SOURCES_FILE, START_SEC, type Settings, TOOL_SEC, type Trial, USER_AGENT, type UpdateDeps, VERSION, buildAll, buildBlock, buildResources, compare, configPath, decide, defineTool, deploy, downloadFile, fetchManifest, fileOrRefusal, findBlock, fromNpxCache, inside, install, installPayload, installPython, jsonSchemaOf, keyInTable, lastLine, loadConfig, markChecked, markCurrent, parseEngineManifest, parseFailure, path, platformKey, previousVersion, probe, pythonSource, refusalFor, remove, rollback, tarEntries, tidyOld, timeToCheck, unpackArchive, withArgs };