01b20b5b78
## Summary
- Qualify OpenCode **2.1.3** (latest stable, 22 October) with the
existing locked **2.1.0 client/plugin** dependencies, and **recommend**
it.
- Keep the technical **minimum at 2.1.2**: nothing CodeNomad consumes
changed, so the minimum has no new reason to move.
- A 2.1.2 daemon stays ready and gets an optional upgrade offer. 2.1.3
is the `tested` version. Newer and custom labels keep authenticated
contract recognition.
- The reviewed-contract fast path lists 2.1.3 beside the 2.1.2 minimum.
- The recommended version is updated in the help (all ten locales), both
READMEs, `dev-docs/OPENCODE_COMPATIBILITY.md` and the architecture
skill.
## Contract review (v2.1.2 → v2.1.3, 66 commits)
- **Authenticated OpenAPI:** 119 → **121 paths**, 144 → **146
operations**. Every consumed operation is unchanged. The only changes:
- added `GET /api/experimental/voice/models`;
- added `POST /api/experimental/voice/session/{sessionID}/instructions`;
- an optional hosted `session.id` in the `POST
/api/experimental/voice/session` response.
None of these is on the instance proxy allowlist, so they stay closed.
- **Published declarations:** the client adds only `voice.models` /
`voice.instructions`. The schema changes only typing (agent `color`
decoding, `Durable` as a tagged union). The plugin is unchanged.
- **Windows managed services** move their default port from **45278 to
28894** ([#57428](https://github.com/anomalyco/opencode/pull/57428)).
CodeNomad discovers the daemon through the selected CLI's `service
status` and the service registration, and assumes no port.
- Live check: this machine's shared daemon was upgraded to 2.1.3 and
restarted on 28894, and the running CodeNomad desktop kept working
through it.
- **Core:** mostly refactors, plus behaviour fixes that the native
suites below exercise:
- compaction summary output limit;
- `keepID` validated as a message ID;
- MCP media kept out of attachments;
- only changed instruction entries resent;
- relative-directory V1 migration;
- legacy `apply_patch` permission mapped to `edit`.
## Isolated Windows qualification
Base: dev `333d73452`, rebased on `853b14f2f` (#1097) for the final UI
unit run; Node **24.20.0**; exact official CLI **2.1.3**; 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 (9/9):**
- history from **2.0.3, beta-19271, 2.0.32, 2.1.0, 2.1.1 and 2.1.2** to
2.1.3;
- Git degraded/init;
- temporary workspaces.
- **Installation (3/3), with the 2.1.3 recommendation:**
- fresh install of the 2.1.2 minimum;
- native **2.0.15 → 2.1.3** upgrade, after which the already-running
daemon keeps its PID and 2.0.15 version;
- explicit OpenCode **1.18.10 → 2.1.3** replacement.
- **After the recommendation change:**
- admission/transport/update/setup units **36/36**;
- full server **2,463 passed, 8 skipped**, no failure or cancellation;
- UI units **1,694/1,694** (with #1097);
- 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.
The UI unit run on `333d73452` itself had two failures, in
`instances-pending-compaction.test.ts` (`toast.dismiss is not a
function`). They come from #1096 and also fail on unmodified `dev`;
#1097 fixes that fixture.
This is Windows automation evidence. In CI, `latest` now resolves to
2.1.3: 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.
10 KiB
Configuration d’OpenCode
CodeNomad se connecte à un service OpenCode partagé sur l’hôte d’exécution. Sélectionner une CLI, mettre à jour ses fichiers, redémarrer ce service et recharger la configuration sont des opérations différentes ; aucune ne remplace les autres.
Sélectionner ou installer la CLI
- Ouvrez Paramètres → OpenCode et utilisez la carte Binaire OpenCode, sous Version d’OpenCode, pour sélectionner l’exécutable.
- Laissez l’entrée automatique sélectionnée pour privilégier le PATH du serveur, sauf s’il contient un OpenCode plus ancien, puis son installation npm utilisateur d’OpenCode 2 ; ou utilisez Parcourir le binaire…, ou saisissez un chemin et choisissez Ajouter.
- Utilisez Vérifier l’état et les mises à jour. Si OpenCode manque, choisissez Installer et démarrer OpenCode ; vérifiez d’abord l’hôte et la portée d’installation.
- Si la configuration propose Connecter et continuer, utilisez-le après résolution du problème signalé.
L’installation utilise Node/npm fournis pour une installation utilisateur standard partagée avec d’autres clients. Installer pour l’utilisateur et configurer le PATH change la configuration du terminal de cet utilisateur ; ouvrez ensuite un nouveau terminal. Un navigateur se connecte au serveur CodeNomad : son sélecteur de fichiers et son choix d’exécutable concernent ce serveur, pas l’appareil de navigation.
Lorsqu’un OpenCode plus ancien apparaît en premier dans le PATH, l’action proposée dépend de son mode d’installation. Pour OpenCode 1.x installé avec npm, Remplacer OpenCode {version} par OpenCode 2 demande une confirmation, retire ce paquet npm et installe OpenCode 2 dans le même dossier npm ; le dossier de données d’OpenCode est conservé, et OpenCode 2 importe lui-même les conversations 1.x. Un OpenCode plus ancien ou inutilisable installé autrement (winget, Homebrew, manuellement) n’est jamais modifié : Installer OpenCode 2 pour CodeNomad installe OpenCode 2 dans le dossier npm de l’utilisateur à côté de lui, et CodeNomad utilise ensuite cette copie. Si cette ancienne commande se trouve elle-même dans le dossier npm de l’utilisateur (par exemple un lien dans ~/.local/bin), ou si ce dossier n’est pas accessible en écriture, la configuration en indique la raison au lieu de proposer l’action : déplacez ou renommez la commande, ou corrigez les droits du dossier, puis choisissez Vérifier l’état et les mises à jour. La commande opencode d’un terminal peut encore lancer l’ancienne version. Un exécutable personnalisé explicitement sélectionné n’est jamais remplacé.
L’exécutable installé et le service actif peuvent avoir des versions différentes. Comparez Version installée et Service en cours dans la carte Version d’OpenCode au lieu de supposer que sélectionner un autre exécutable a remplacé le démon actif ; Détails des versions indique les versions minimale et recommandée. Si l’installation est occupée ou l’exécutable verrouillé, attendez sa libération par l’installateur ou le processus et vérifiez l’état avant de réessayer ; ne lancez pas des installateurs concurrents.
Versions requises, recommandées et non vérifiées
| Classification | Exigence actuelle | Signification |
|---|---|---|
| Minimum | OpenCode 2.1.2 | Ordre correct d’exécution des tâches JavaScript dans Code Mode, ainsi que le format natif de rejeu et de compaction de la 2.1 ; les conversations enregistrées par les versions antérieures restent lisibles après la mise à jour. |
| Recommandée | OpenCode 2.1.3 | Cible qualifiée, distincte du minimum technique. |
| Non vérifiée | Version plus récente ou personnalisée non entièrement validée | Non rejetée simplement parce que non testée ; les contrats API réels du service connecté sont vérifiés. |
Les contrats requis de session, permission, Form, boîte de réception et environnement de session doivent aussi être disponibles. Une version d’exécutable seule ne prouve pas que le service connecté les prend en charge. Si la configuration signale un service actif non pris en charge, sélectionnez/installez une CLI prise en charge et utilisez le redémarrage explicite du service partagé lorsque vous êtes prêt.
Hôte, WSL et portée du service partagé
Sous Windows, un exécutable WSL sélectionné s’exécute dans la distribution choisie. Installez/mettez-le à jour là-bas et utilisez des chemins valides dans cette distribution. La connectivité WSL dépend du transfert localhost de Windows. Une CLI Windows et une CLI WSL ne sont pas des environnements d’exécution interchangeables.
OpenCode possède l’enregistrement global de son service, ses sessions, messages et base de données. CodeNomad ne crée pas une base OpenCode privée par fenêtre ou projet. Fermer un onglet de projet ferme ce projet dans CodeNomad ; les sessions continuent dans OpenCode et réapparaissent quand vous rouvrez le projet. CodeNomad ne décharge jamais les Locations natives. Fermer une fenêtre entière, quitter ou recharger conserve les connexions de projet pour la restauration ; ni ces actions ni l’arrêt du backend n’arrêtent le démon partagé. Voir Projets.
Mettre à jour, redémarrer ou recharger
- Dans Paramètres → OpenCode, choisissez Vérifier l’état et les mises à jour.
- Pour remplacer les fichiers CLI installés, choisissez Mettre à jour vers OpenCode {version} si proposé. Attendez la fin.
- Vérifiez l’état du service actif. Utilisez Redémarrer le service partagé seulement pour activer volontairement l’installation sélectionnée pour tous les clients connectés.
- Pour redémarrer le processus sans rien installer, développez Dépannage et choisissez Redémarrer le service OpenCode, puis confirmez.
| Action | Portée et effet | Récupération sûre |
|---|---|---|
| Mettre à jour la CLI | Change l’exécutable installé pris en charge ; ne redémarre pas implicitement le démon actif. | Vérifiez les versions installée et active après un échec ; réessayez explicitement après résolution de l’erreur seulement. |
| Redémarrer le service | Remplace le processus partagé et interrompt le travail actif de tous les clients OpenCode connectés ; l’historique reste. | Reconnectez-vous et inspectez conversations et Missions planifiées ; un redémarrage n’est pas une continuation automatique. |
| Recharger la configuration OpenCode | Conserve le processus mais reconstruit chaque Location chargée pour tous les clients. Annule les permissions/Forms en attente et ferme terminaux/commandes en arrière-plan ; le travail actif peut être interrompu. | Revérifiez ressources et travaux en attente après rechargement. Ne répétez pas un prompt ou une modification simplement parce que sa réponse a été perdue. |
Utilisez explicitement Recharger la configuration OpenCode, sous Dépannage lorsque le service actif le prend en charge, lorsqu’une configuration enregistrée ou un plugin installé reste indisponible et que l’interruption est acceptable. Ce n’est pas une actualisation d’affichage anodine. CodeNomad n’utilisera pas une CLI sélectionnée plus ancienne pour rétrograder un démon actif plus récent.
Environnement de session
- Ouvrez Paramètres → Avancé et développez Variables d'environnement.
- Ajoutez, modifiez ou retirez les remplacements du profil ; chaque changement est enregistré immédiatement.
- Envoyez le prochain prompt, commande personnalisée ou demande shell de session via CodeNomad pour appliquer l’environnement courant à cette conversation.
C’est un réglage de profil de configuration, appliqué côté serveur avant chaque envoi. Simplement ouvrir/lire une conversation ou enregistrer les paramètres ne modifie pas une session native. Retirer un remplacement restaure la valeur héritée de l’hôte d’exécution, ou la supprime si elle y est absente. Un échec d’application bloque l’envoi au lieu d’utiliser des valeurs périmées.
L’environnement contrôle les lancements shell locaux suivants de cette session native. Les processus déjà actifs gardent leur environnement. Il ne reconfigure pas les fournisseurs, serveurs MCP/LSP, terminaux indépendants ni shells en arrière-plan propres à une Location. Les prompts en file ne capturent pas chacun leur environnement, et un autre client OpenCode peut remplacer celui de la même session. Ne supposez pas que les sessions enfants créées entièrement dans OpenCode reçoivent une mise à jour CodeNomad au moment de l’envoi.
Les variables autorisées sont aussi transmises au démarrage d’un service arrêté ; se connecter à un démon existant ne change pas son environnement de processus. Dans WSL, les valeurs sont combinées avec l’environnement d’exécution Linux, pas le PATH/HOME Windows. Changer ces remplacements ne déplace pas la base de données ni l’enregistrement du service OpenCode.
Modifier les fichiers de configuration natifs
- Ouvrez Paramètres → Fichiers de configuration et sélectionnez Fichier.
- Vérifiez le chemin affiché, modifiez, puis choisissez Enregistrer.
- Utilisez Recharger pour relire le fichier ; ce n’est pas Recharger la configuration OpenCode.
Cet éditeur expose uniquement les fichiers globaux opencode.json et opencode.jsonc listés dans le répertoire .config/opencode de l’utilisateur du serveur CodeNomad. Ce n’est ni un éditeur arbitraire de fichiers, ni un sélecteur de configuration Projet, ni une garantie qu’un démon WSL/à découverte personnalisée lit ce fichier. Vérifiez la cible avec le chemin affiché ; utilisez les outils du démon pour les autres racines.
Enregistrer écrit le fichier comme texte ; cela ne valide pas toute la configuration native et ne redémarre/recharge pas OpenCode. Coordonnez vos modifications avec les autres clients : cette interface ne propose pas de fusion des changements externes. Gardez une copie avant de remplacer une configuration importante. Changer de fichier ou recharger un brouillon modifié demande s’il faut l’abandonner.
Consultez Intégrations, Fournisseurs, Missions et la documentation OpenCode pour les procédures propres à la configuration.