39c0fa5833
## Summary
- Qualify OpenCode **2.1.4** (latest stable, 23 October) with the
existing locked **2.1.0 client/plugin** dependencies, and **recommend**
it.
- Keep the technical **minimum at 2.1.2**: no consumed contract changed,
so the minimum has no new reason to move.
- 2.1.2 and 2.1.3 daemons stay ready and get an optional upgrade offer.
2.1.4 is the `tested` version. Newer and custom labels keep
authenticated contract recognition.
- The reviewed-contract fast path lists the 2.1.2 minimum and the 2.1.4
target.
- The recommended version is updated in the help (all ten locales), both
READMEs, `CONTRIBUTING.md`, `dev-docs/OPENCODE_COMPATIBILITY.md` and the
architecture skill.
## Contract review (v2.1.3 → v2.1.4, 72 commits)
- **Authenticated OpenAPI:** 121 → **124 paths**, 146 → **149
operations**. No operation changed. The changes:
- added `POST /api/experimental/client-mcp/token`;
- added `GET /api/experimental/client-mcp` (WebSocket);
- added `POST /api/debug/heap-dump`;
- `Config.InfoEncoded` gains the opt-in
`experimental.background_compaction`.
The session event (`V2EventEncoded`) and message schemas are unchanged.
None of the new routes is on the instance proxy allowlist, and the proxy
relays WebSockets only for SideCars and previews.
- **Published declarations:**
- the client adds `mcp.client.token` and `debug.heapDump`;
- the schema and plugin changes are type refactors and unused-export
removals, among them `SessionID.descending`, `SessionEvent.Source` and
`PromptInput.FileAttachment.create`; `Session.Message.ID.fromEvent` now
takes any string instead of an event ID. CodeNomad uses none of these,
and every host module its native plugin bundles import
(`@opencode/plugin`, `/effect`, `/promise/adapter`, `/rpc`,
`@opencode/schema/location`, `/session`) still exists.
- **MCP elicitation forms**
([#58184](https://github.com/anomalyco/opencode/pull/58184)): an MCP
server asking for input during a tool call now creates a global-session
Form whose `form.created` event carries the server's location.
CodeNomad's live path requires that location for global Forms and shows
them as a **Project request**. Review found that the live path dropped
the location from the queued Form, so its reply lacked
`x-opencode-directory` and failed for a worktree or subdirectory until a
pending-request rescan. **#1127** fixes that; recovery already kept it.
A native probe (minimal stdio MCP server, a real Code Mode `execute`
call, CodeNomad-style reply) gives:
| Runtime | Form listed for the location | `form.created` carries the
location | Reply completes the tool |
| --- | --- | --- | --- |
| 2.1.3 | yes | **no** | yes |
| 2.1.4 | yes | **yes** | yes (`action: accept`, `channel: stable`) |
On 2.1.3 such a request only appeared after a pending-request rescan; on
2.1.4 it appears live. The probe sends the location header itself, so it
checks the runtime contract; #1127 covers CodeNomad's live reply path.
- **Other changes** are covered by the native suites below:
- compaction (oldest-first shortening, ignored buffers, overflow
detection);
- the agent's model for sessions without one;
- V2 agent files;
- V1 global-session import attribution;
- MCP lifecycle fixes.
- **Live check:** this machine's shared daemon runs 2.1.4, and the
CodeNomad desktop session works through it.
## Isolated Windows qualification
Base: dev `9ac792fff`; Node **24.20.0**; exact official CLI **2.1.4**;
unchanged locked client/plugin **2.1.0**.
- **Build and checks:** production server/UI/native plugin builds,
server and root typechecks, native bundle guard.
- **Native runtime (9/9):**
- Code Mode job ordering, plugin runtime, automation;
- complete pruning, history, ownership, worktree and event relay;
- loaded-only pending snapshot;
- Missions contract, family control, native and Compare/Wayfinder
trajectory.
- **Sessions (15/15):** environment, fork, aside, interrupt, lifecycle,
blank cleanup, prompt skills, provider usage/accounts/selection, service
usage, web search, plugin packages, output limit, Promise-tool failure.
- **Recurring (5/5):** all **11 recurring Mission journeys**, subagent
depth, **2 MiB** compaction, permission receipts.
- **Migrations (10/10):**
- history from **2.0.3, beta-19271, 2.0.32, 2.1.0, 2.1.1, 2.1.2 and
2.1.3** to 2.1.4;
- Git degraded/init;
- temporary workspaces.
- **Installation (3/3), with the 2.1.4 recommendation:**
- fresh install of the 2.1.2 minimum;
- native **2.0.15 → 2.1.4** upgrade, after which the already-running
daemon keeps its PID and 2.0.15 version;
- explicit OpenCode **1.18.10 → 2.1.4** replacement.
- **After the recommendation change:**
- admission, transport, update, installation and instance proxy units
**116 passed, 1 POSIX-only skipped**;
- full server **2,471 passed, 8 skipped**, no failure or cancellation;
- UI units **1,699/1,699**;
- focused browser **126/126**;
- native pruning with the real rendered UI;
- the exact CI invocation of the Code Mode regression (without tsx);
- ten-locale help checks (**9/9**).
This is Windows automation evidence. In CI, `latest` resolves to 2.1.4:
the compatibility job runs the native suites against the minimum and
latest on Windows, and the migration and Git-degraded certification runs
them on Ubuntu, Windows and macOS. WSL, packaged desktop,
installers/updater end-to-end and real mobile devices keep their
separate release gates.
9 KiB
Установка CodeNomad
Выберите локальное настольное приложение или запустите отдельный сервер. В обоих случаях общей нативной службой и историей владеет OpenCode.
Загрузка настольного приложения
- Откройте последний релиз.
- Выберите сборку для своей операционной системы и процессора.
- Распакуйте ZIP либо установите/запустите пакет для платформы, затем запустите CodeNomad.
| Платформа | Релиз Electron | Релиз Tauri | Примечания |
|---|---|---|---|
| macOS | ZIP, Intel или Apple Silicon | ZIP, Intel или Apple Silicon | Встроенная среда выполнения требует macOS 13.5 или новее. |
| Windows | ZIP, x64 | Установщик, x64 | Windows 10 или новее; Tauri использует WebView2. |
| Linux | Пакет Debian, x64 | AppImage, x64 | Собрано и проверено на Ubuntu 24.04; совместимость со старыми дистрибутивами не гарантируется. |
Настольные релизы включают ресурсы среды выполнения, необходимые серверной части и установщику OpenCode, поэтому отдельно устанавливать Node.js/npm не нужно. Git не входит в комплект. Нативная автоматизация браузера поддерживается в Electron и Windows Tauri; на других платформах Tauri используется предпросмотр iframe.
Если проверенная загрузка блокируется при запуске, см. устранение проблем платформы. Никогда не запускайте недоверенный архив только ради обхода предупреждения.
Установка в Linux
В папке с загруженным релизом подставьте его фактическую версию и имя файла:
sudo apt install ./CodeNomad-Electron-linux-x64-<version>.deb
Для Tauri AppImage:
chmod +x CodeNomad-Tauri-linux-x64-<version>.AppImage
./CodeNomad-Tauri-linux-x64-<version>.AppImage
Если FUSE недоступен, используйте режим распаковки и запуска AppImage:
./CodeNomad-Tauri-linux-x64-<version>.AppImage --appimage-extract-and-run
Установка Electron из пакета Debian настраивает песочницу Chromium. Не отключайте песочницу для обхода проблем установки. Для графических проблем Linux Tauri существует целевой обходной путь WebKit.
Требования
| Требование | Где должно быть доступно | Текущее требование |
|---|---|---|
| OpenCode CLI | Выбранный хост выполнения, включая выбранный дистрибутив WSL, если применимо | Минимум 2.1.2; 2.1.4 — рекомендуемая/проверенная цель. Для новых и пользовательских версий проверяются контракты, а не вводится запрет на непроверенные версии. |
| Git | PATH учётной записи серверной части CodeNomad |
Необходим для идентификации репозитория, операций Git и worktree. |
| Node.js/npm | Хост отдельного сервера и сборки из исходников | Node.js 24 LTS; воспроизводимые сборки из исходников используют .node-version (24.20.0). Входит в ресурсы выполнения/установки настольного приложения. |
| Папка рабочего пространства | Диск, доступный серверной части | Явно открытая физическая папка, а не локальная папка устройства, предполагаемая удалённым браузером. |
В Windows установите Git for Windows с доступом из командной строки и сторонних приложений. Достаточно установки для одного пользователя с правом записи. В macOS/Linux следуйте инструкциям Git для платформы.
После изменения PATH полностью закройте и снова запустите настольное приложение либо перезапустите отдельную серверную часть под нужной учётной записью. Перезагрузка браузера не обновляет окружение серверной части. Git, доступный только внутри WSL, не удовлетворяет требованию Git для серверной части Windows.
Без Git можно открыть физическую папку и использовать разговоры в пределах каталога, в том числе попросить агента помочь с установкой. Операции с репозиторием/worktree недоступны; доступ к сессиям ограничен ровно этой папкой. CodeNomad сообщает агенту о доступности Git в серверной части перед запросами/пользовательскими командами и удаляет это указание после восстановления. Хост выполнения агента может отличаться от хоста серверной части, поэтому установите Git для серверной части, а не только для оболочки агента.
Выбор OpenCode при первом запуске
- При настройке выберите совместимый существующий исполняемый файл или используйте предложенную установку OpenCode.
- Проверьте статус среды выполнения перед открытием проекта.
- Откройте Настройки → OpenCode, чтобы отдельно управлять исполняемым файлом, установкой и общей службой.
CodeNomad предпочитает совместимые исполняемые файлы из PATH и поддерживает явно выбранный файл. Если PATH запускает более старый OpenCode, настройка после подтверждения предлагает заменить OpenCode 1.x, установленный через npm, или установить OpenCode 2 для CodeNomad рядом с установкой, сделанной иначе, которую она никогда не изменяет; см. настройку OpenCode. Установка/обновление CLI не перезапускает уже работающую общую службу без вашего ведома. Последствия перезапуска/перезагрузки, WSL и окружение сессии описаны в разделе настройки OpenCode.
Использование браузера
Установите Node.js/npm, Git и OpenCode на серверный хост, затем следуйте процедурам запуска сервера. Подключитесь по напечатанному адресу с настроенной аутентификацией и доверенным сертификатом. Браузеру/PWA нужна работающая серверная часть; это не автономная копия проектов.
Порты, привязки и TLS описаны в разделе прямого доступа. Для сопряжения устройства без открытия входящих портов используйте удалённое управление. Команды разработки и упаковки см. в разделе сборки из исходников.