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.
239 lines
9.9 KiB
Markdown
239 lines
9.9 KiB
Markdown
# 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`.
|