Andrew Emelyaneko d3b72ad69a Ignore local OpenCode state and Python caches
.opencode/ holds a scratch node_modules tree and pilot-* run artifacts
(62 MB total) that are specific to this checkout, and the Python caches
regenerate on every test run.
2026-11-02 14:31:55 +03:00
2026-10-31 22:04:00 +03:00

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

./scripts/install-client.sh

Устанавливаются файлы:

~/.config/opencode/plugins/ollama-swap.js
~/.config/ollama-plagin-swap/clients.json

Отредактируйте clients.json и укажите URL и токен удалённого агента Ollama.

Установка агента на сервере Ollama

Подключитесь по SSH к серверу 10.8.0.62 под пользователем с правами администратора/root. Пример:

ssh admin@10.8.0.62

Сервер Ollama на macOS

Выполните на сервере Ollama:

mkdir -p ~/src/ollama-plagin-swap
# Сначала скопируйте файлы репозитория на сервер, затем:
cd ~/src/ollama-plagin-swap
./scripts/install-agent.sh

Установщик создаёт файлы:

~/.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, затем перезапустите агент:

launchctl unload ~/Library/LaunchAgents/com.ollama.swap-agent.plist 2>/dev/null || true
launchctl load -w ~/Library/LaunchAgents/com.ollama.swap-agent.plist

Сам сервис Ollama агент перезапускает командами:

launchctl unload ~/Library/LaunchAgents/com.ollama.serve.plist 2>/dev/null
launchctl load -w ~/Library/LaunchAgents/com.ollama.serve.plist

Сервер Ollama на Ubuntu

Выполните на сервере Ollama под root:

cd /opt/ollama-plagin-swap
sudo ./scripts/install-agent.sh

Установщик создаёт файлы:

/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, затем выполните:

sudo systemctl daemon-reload
sudo systemctl enable --now ollama-swap-agent

При необходимости откройте доступ с клиентского IP:

sudo ufw allow from <ip-клиента-opencode> to any port 8731 proto tcp

Сам сервис Ollama агент перезапускает командой:

sudo systemctl restart ollama

Генерация токена

Токен не выдаётся внешним сервисом: придумайте одинаковый секрет и впишите его и в серверный config.json, и в клиентский clients.json. Например:

openssl rand -hex 32

Порог swap

По умолчанию агент сравнивает общий объём используемого swap с конкретным размером: swap_threshold_mb = 3048. Процентный режим выключен (swap_threshold_percent = null).

Чтобы оставить прежнее процентное поведение, задайте, например:

{
  "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/.

Проверка агента на сервере

curl -sS -H "Authorization: Bearer <token>" http://10.8.0.62:8731/health
curl -sS -H "Authorization: Bearer <token>" http://10.8.0.62:8731/status

Ручной запрос на перезапуск:

curl -sS -X POST \
  -H "Authorization: Bearer <token>" \
  -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 не стартует до логина. Проверьте после перезагрузки:

launchctl list | grep com.ollama.swap-agent
curl -sS -H "Authorization: Bearer <token>" http://127.0.0.1:8731/health

Проверка клиентского плагина OpenCode

OpenCode 2.x автоматически подключает глобальный плагин из ~/.config/opencode/plugins/ollama-swap.js и вызывает setup(ctx) сразу при загрузке — именно на этом шаге выполняется первый опрос агента. server.connected плагинам в OpenCode 2.x не доставляется, поэтому старый триггер больше не используется.

Проверить загрузку:

opencode plugin list

Результат опроса пишется в файл ~/.local/state/ollama-plagin-swap/client.log (фоновый сервис OpenCode направляет stdout в /dev/null, поэтому собственный лог надёжнее) и дублируется в консоль сервера. Строка вида:

2026-11-02T11:21:09.728Z [info] ollama-remote: swap 663.19/2048 MB (32.38%), recommendation=none

При превышении порога уровень меняется на [warn], при недоступном агенте пишется agent unreachable: <name> (<error>).

Установка TS-варианта с инструментами

ollama-swap.ts регистрирует инструменты, поэтому его нужно ставить как каталог-плагин:

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 <path> serve:

<string>--config</string>
<string>/Users/andrew/.config/ollama-plagin-swap/config.json</string>
<string>serve</string>

После правки выполните launchctl unload ... && launchctl load -w ....

Локальные проверки перед установкой

/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.

S
Description
OpenCode plugin swap control ollama server
Readme
106 KiB