# ollama-plagin-swap Удалённый контроль swap для серверов Ollama, используемых через API OpenCode. ## Что устанавливается - `src/ollama_swap_agent.py` и `src/ollama_swap_common.py`: Python-агент для macOS и Ubuntu. - `examples/opencode/ollama-swap.js`: канонический клиентский плагин OpenCode без зависимостей. - `examples/opencode/ollama-swap.ts`: необязательный TypeScript-плагин с пользовательскими инструментами (`ollama_swap_status`, `ollama_swap_restart`) и runtime-guard. Требует установки как каталог-плагин с `package.json` (см. ниже). - Агент предоставляет `GET /health`, `GET /status` и `POST /restart`. Оба плагина написаны под **API плагинов OpenCode 2.x** (проверено на 2.2.5): экспортируют `export default { id, setup }` и возвращают cleanup-функцию. Плагины V1 API (`export const XPlugin = async (ctx) => ({...})`) в OpenCode 2.x не загружаются. ## Почему раньше дублировались плагины OpenCode автоматически загружает все файлы плагинов из `.opencode/plugins/` проекта и из `~/.config/opencode/plugins/`. Если один и тот же файл лежит в обоих местах, он загружается дважды. Поэтому исходники перенесены в `examples/opencode/`, а устанавливается только один глобальный файл. ## Установка клиента на текущий macOS ```sh ./scripts/install-client.sh ``` Устанавливаются файлы: ```text ~/.config/opencode/plugins/ollama-swap.js ~/.config/ollama-plagin-swap/clients.json ``` Отредактируйте `clients.json` и укажите URL и токен удалённого агента Ollama. ## Установка агента на сервере Ollama Подключитесь по SSH к серверу `10.8.0.62` под пользователем с правами администратора/root. Пример: ```sh ssh admin@10.8.0.62 ``` ### Сервер Ollama на macOS Выполните на сервере Ollama: ```sh mkdir -p ~/src/ollama-plagin-swap # Сначала скопируйте файлы репозитория на сервер, затем: cd ~/src/ollama-plagin-swap ./scripts/install-agent.sh ``` Установщик создаёт файлы: ```text ~/.local/share/ollama-plagin-swap/ollama_swap_agent.py ~/.local/share/ollama-plagin-swap/ollama_swap_common.py ~/.config/ollama-plagin-swap/config.json ~/Library/LaunchAgents/com.ollama.swap-agent.plist ``` Измените токен в `~/.config/ollama-plagin-swap/config.json`, затем перезапустите агент: ```sh launchctl unload ~/Library/LaunchAgents/com.ollama.swap-agent.plist 2>/dev/null || true launchctl load -w ~/Library/LaunchAgents/com.ollama.swap-agent.plist ``` Сам сервис Ollama агент перезапускает командами: ```sh launchctl unload ~/Library/LaunchAgents/com.ollama.serve.plist 2>/dev/null launchctl load -w ~/Library/LaunchAgents/com.ollama.serve.plist ``` ### Сервер Ollama на Ubuntu Выполните на сервере Ollama под root: ```sh cd /opt/ollama-plagin-swap sudo ./scripts/install-agent.sh ``` Установщик создаёт файлы: ```text /opt/ollama-plagin-swap/ollama_swap_agent.py /opt/ollama-plagin-swap/ollama_swap_common.py /etc/ollama-plagin-swap/config.json /etc/systemd/system/ollama-swap-agent.service ``` Измените `/etc/ollama-plagin-swap/config.json`, затем выполните: ```sh sudo systemctl daemon-reload sudo systemctl enable --now ollama-swap-agent ``` При необходимости откройте доступ с клиентского IP: ```sh sudo ufw allow from to any port 8731 proto tcp ``` Сам сервис Ollama агент перезапускает командой: ```sh sudo systemctl restart ollama ``` ## Генерация токена Токен не выдаётся внешним сервисом: придумайте одинаковый секрет и впишите его и в серверный `config.json`, и в клиентский `clients.json`. Например: ```sh openssl rand -hex 32 ``` ## Порог swap По умолчанию агент сравнивает общий объём **используемого** swap с конкретным размером: `swap_threshold_mb = 3048`. Процентный режим выключен (`swap_threshold_percent = null`). Чтобы оставить прежнее процентное поведение, задайте, например: ```json { "swap_threshold_percent": 25, "swap_threshold_mb": null } ``` ## Поведение агента - Каждые `poll_interval_seconds` (по умолчанию 60) снимает метрики swap и состояние `/api/ps`. - При превышении порога останавливает загруженные модели через `ollama stop` (`unload_models_before_restart`) и перезапускает сервис; если нужно, `restart_force_after_seconds` позволяет принудительный restart. - `last_restart`, `restart_times` и навязчиво оставшийся `restart_in_progress` теперь корректно сохраняются и сбрасываются после нового запуска агента. - После перезапуска ждёт `/api/tags` не более `restart_health_timeout_seconds`. - Действует cooldown и лимит restart-ов в час для защиты от штормов. - Логи и state хранятся в `~/.local/state/ollama-plagin-swap/`. ## Проверка агента на сервере ```sh curl -sS -H "Authorization: Bearer " http://10.8.0.62:8731/health curl -sS -H "Authorization: Bearer " http://10.8.0.62:8731/status ``` Ручной запрос на перезапуск: ```sh curl -sS -X POST \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{"reason":"manual","force":false}' \ http://10.8.0.62:8731/restart ``` ## Перезагрузка сервера После reboot Mac mini агент запустится автоматически при входе пользователя, потому что записан в `~/Library/LaunchAgents` с `RunAtLoad=true`. Если автоматического входа нет, agent не стартует до логина. Проверьте после перезагрузки: ```sh launchctl list | grep com.ollama.swap-agent curl -sS -H "Authorization: Bearer " http://127.0.0.1:8731/health ``` ## Проверка клиентского плагина OpenCode OpenCode 2.x автоматически подключает глобальный плагин из `~/.config/opencode/plugins/ollama-swap.js` и вызывает `setup(ctx)` сразу при загрузке — именно на этом шаге выполняется первый опрос агента. `server.connected` плагинам в OpenCode 2.x не доставляется, поэтому старый триггер больше не используется. Проверить загрузку: ```sh opencode plugin list ``` Результат опроса пишется в файл `~/.local/state/ollama-plagin-swap/client.log` (фоновый сервис OpenCode направляет stdout в `/dev/null`, поэтому собственный лог надёжнее) и дублируется в консоль сервера. Строка вида: ```text 2026-11-02T11:21:09.728Z [info] ollama-remote: swap 663.19/2048 MB (32.38%), recommendation=none ``` При превышении порога уровень меняется на `[warn]`, при недоступном агенте пишется `agent unreachable: ()`. ### Установка TS-варианта с инструментами `ollama-swap.ts` регистрирует инструменты, поэтому его нужно ставить как каталог-плагин: ```sh mkdir -p ~/.config/opencode/plugins/ollama-tools cp examples/opencode/ollama-swap.ts ~/.config/opencode/plugins/ollama-tools/index.ts printf '{ "name": "ollama-swap-tools", "type": "module", "exports": { ".": "./index.ts" } }\n' \ > ~/.config/opencode/plugins/ollama-tools/package.json ``` Его id — `ollama-plagin-swap.tools`, поэтому он не конфликтует с обычным файловым плагином: OpenCode отклоняет второй плагин с тем же `id` с ошибкой `Duplicate plugin ID`. Держать оба одновременно обычно не нужно — инструменты лишь дублируют фоновый опрос. ## Неполадки LaunchAgent Если лог показывает `unrecognized arguments: --config ...`, plist вызывает `serve --config ...`. Переведите аргументы в порядок `--config serve`: ```xml --config /Users/andrew/.config/ollama-plagin-swap/config.json serve ``` После правки выполните `launchctl unload ... && launchctl load -w ...`. ## Локальные проверки перед установкой ```sh /usr/bin/python3 -m py_compile src/*.py tests/*.py /opt/homebrew/bin/pytest -q node --check examples/opencode/ollama-swap.js ``` Для `.ts`-варианта нужен `@opencode/plugin` версии 2.x в `devDependencies` и проверка через `tsc`.