Files
ollama-plagin-swap/README.md
T
Andrew Emelyaneko d25aa7a686 Port OpenCode plugins to the V2 plugin API (2.2.5)
OpenCode 2.x uses a new plugin API; V1 plugins do not load at all. Both
example plugins are rewritten as `export default { id, setup }`.

Fixes, in order of severity:

- Default export with id/setup instead of a named `export const XPlugin`,
  which the V2 loader rejects with "Plugin must export a default definition
  with an id and an effect or setup function".
- Drop `client.app.log`: the V2 context has no client and no logging API.
  Poll results go to ~/.local/state/ollama-plagin-swap/client.log and to the
  console. A file log is required because the managed background service
  sends stdout to /dev/null.
- Replace the `server.connected` trigger with an immediate poll in `setup`;
  V2 never delivers that event to in-process plugins.
- Replace the `session.deleted` interval teardown with a cleanup function
  returned from `setup`, and unref the timer so monitoring never keeps the
  server alive.
- Use `ctx.location.directory` instead of `ctx.directory`.
- Read opencode.jsonc as well as opencode.json when inferring controls from
  providers, stripping comments and trailing commas; provider inference
  previously failed silently on JSONC configs.
- Switch from require() to ESM imports.
- TypeScript variant: import types from `@opencode/plugin`, not
  `@opencode-ai/plugin`; register tools via `ctx.tool.transform` with JSON
  Schema and return `{ content }` from executors.
- Give the tool variant the id `ollama-plagin-swap.tools`, since reusing
  `ollama-plagin-swap` makes OpenCode fail it with "Duplicate plugin ID".

Verified on a live OpenCode 2.2.5 server: both variants report `active` via
/api/plugin and the poller writes swap status every interval.
2026-11-02 14:27:37 +03:00

239 lines
9.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 <ip-клиента-opencode> 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 <token>" http://10.8.0.62:8731/health
curl -sS -H "Authorization: Bearer <token>" http://10.8.0.62:8731/status
```
Ручной запрос на перезапуск:
```sh
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 не стартует
до логина. Проверьте после перезагрузки:
```sh
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
не доставляется, поэтому старый триггер больше не используется.
Проверить загрузку:
```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: <name> (<error>)`.
### Установка 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 <path> serve`:
```xml
<string>--config</string>
<string>/Users/andrew/.config/ollama-plagin-swap/config.json</string>
<string>serve</string>
```
После правки выполните `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`.