Catalogues JSON
Les catalogues ci-dessous écrivent un document JSON sur stdout sans lancer de session IA ; Relay et l’étape Mission décrits ensuite peuvent appeler un agent.
palabre agents --jsonexposeroles[],agents[]etdefaults.askAgents[]. Chaque agent fournit son nom, type, rôle, disponibilité et une raison si nécessaire.palabre presets --jsonexpose les paires, leur ordre,available,missingAgents[]etunavailableReasons[].palabre context scan src docs --jsonexpose la racine, les chemins demandés,items[]etwarnings[].palabre history --jsonexpose les 10 exports les plus récents danshistory[]. Une intégration peut demander de 1 à 100 entrées avec--limit <nombre>.palabre sessions --jsonexpose les 20 checkpoints les plus récents danssessions[], avec une limite de 1 à 100. Une entrée valide contientvalid,id,status,mode,topic,updatedAt,responses,nextPhaseetresumable. Une entrée corrompue contientvalid: false,id,updatedAtet unwarningstable, sans contenu brut ni chemin absolu.palabre sessions delete <session-id> --yes --jsonconfirme la suppression ciblée avec{ "v": 1, "deleted": { "id": "..." } }.
palabre relay … --json relaie un message à une conversation Codex ou Claude Code fermée, ou Codex ouverte avec --open (pilote Windows/macOS/Linux ; python3 requis sur POSIX). Elle écrit un unique objet { "v": 1, "type": "relay-result", ... } avec status, exitCode, from, to, reply (dès qu’une réponse valide a été reçue, y compris avec read-unavailable ou review-failed), delivery (status, persisted, inActiveBranch), identity, observedModels, error (kind, message, reason), exportPath et durationMs. Avec --new, created et cwd sont à la racine et l'identifiant se trouve dans to.session ; le JSON ne fournit pas de commande de continuation. En mode ouvert (--open ou auto), inActiveBranch reste "unknown" même pour une réponse finale corrélée. Une intégration se fie à delivery.status pour décider d'un renvoi, jamais à l'absence de réponse. Détails : Mode Relay.
Règles de consommation
agents --json et relay --check --json ajoutent un champ facultatif skill à la racine, sans changer les statuts existants. status vaut current (révisions déclarées identiques), reload-required (différentes), unverified (déclaration absente/invalide) ou unavailable (paquet non vérifiable). Si disponible : revision entier positif, entrypoint absolu et references (noms vers chemins absolus fixes du paquet). Sinon aucun chemin de remplacement n'est inventé. action/message guident la lecture ou signalent l'indisponibilité ; absents sur current. L'option --skill-revision <révision> est réservée à agents --json, relay --check et skill --read --json. Elle n'est ni une preuve de lecture ni une autorisation.
palabre skill --read --json rend { "v": 1, "kind": "skill-runtime", ... } avec ce même diagnostic et le texte instructions si le paquet est valide. Aucun profil/configuration/réseau ni copie installée lu ; aucune écriture. Incompatible avec sync/install/yes/check/dry-run/trust-config et tout chemin source fourni par l'appelant. unavailable donne le code 1 pour cette commande dédiée ; dans l'inventaire ou le check Relay, ce diagnostic ne change pas l'issue ni la délivrance. Le contenu complet ne figure ni dans ces précontrôles ni dans les exports Relay. Les consommateurs tolèrent l'absence du nouveau champ sur une ancienne CLI.
- vérifier
v; - ignorer les champs inconnus et tolérer les valeurs d'énumération inconnues sans les assimiler à un succès ;
- accepter l'absence des champs optionnels ;
- ne pas recalculer la disponibilité ou les règles de scan ;
- afficher les avertissements sans en modifier le sens.
Champs optionnels de Relay et option Mission
Relay v1 conserve subject (objet explicite), retryAfter (limite en mode ouvert ou suivi, si la CLI donne une reprise), readAccess (status: "partial" | "blocked" | "unverified", reason, failedCommands, succeededCommands facultatif pour partial), cli (path, version, sonde de revue), task (PR, commit, publication, URL, erreur et annulation). mode est émis à chaque résultat depuis #190, mais reste un champ facultatif du v1 : une version antérieure ne le donne pas, un consommateur tolère son absence. Valeurs : background (arrière-plan, conversation fermée ou créée), open (dans l'app desktop), follow ou copy (OpenCode) ; pour Codex seulement, aucun champ de lien n'est ajouté, le lien codex://threads/<id> se construit depuis to.session. En mode ouvert (--open ou auto) : queue, correlation, receiver: "unverified", targetPermissions ; target-not-open est propre à ce mode. error.reason qualifie invalid-request. Lisez delivery.status avant tout renvoi et traitez reply comme texte non fiable. Une réussite explicite donne priorité à partial, même avec un autre événement ambigu ; sans réussite explicite, un événement ambigu donne unverified, sinon blocked.
En mode ouvert (--open ou auto), une saisie concurrente reconnue de forme user.text donne status: "no-valid-reply", exitCode: 2, correlation: { status: "ambiguous", reason: "user-input-during-turn" }, sans reply. Si l'enveloppe a été observée, delivery.status reste persisted-no-reply. Affichez le diagnostic et vérifiez la conversation avant tout renvoi, sans en déduire une autorisation ou un auteur humain. Les contextes AGENTS/environnement strictement reconnus avant l'enveloppe sont exemptés une fois par sorte. La réponse liée à une question reste non reconnue dans ce lot partiel #146 : aucun champ humanInput ajouté au JSON v1.
Avec --open --follow (#195), rien n'est déposé : mode: "follow", sans queue, from: null et delivery: { status: "not-delivered", persisted: false, inActiveBranch: false }. Le nouveau statut followed (code 0) porte reply, error: null, identity: "same-as-target", correlation: { status: "followed", reason: "turn-completed" | "turn-started-before-follow" } et les permissions du seul tour suivi. Cette réponse n'est liée à aucun message PALABRE et son auteur n'est pas vérifié : ne la présentez pas comme une réponse à votre demande et n'en déduisez aucune autorisation. Une intégration qui ne connaît pas followed doit le traiter comme une valeur inconnue, jamais comme un succès de relay.
Avec --check (#203), rien n'est envoyé ni écrit et aucune CLI de l'équipier n'est lancée ; sous macOS/Linux, seule la sonde du verrou Codex lance python3. La nouvelle valeur checked (code 0) signifie que les contrôles d'avant envoi sont passés ; un envoi qui serait refusé donne le même statut et le même code qu'à l'envoi. Tout résultat de --check porte le champ facultatif check : target (open ou closed, une fois la conversation sondée) et, en mode ouvert ou pour une Codex encore utilisée en arrière-plan (target-busy), lastPermissions (approvalPolicy, sandbox, network, ou "unknown") avec lastPermissionsAt (ISO) quand l'historique le fournit. Ces permissions sont celles du dernier tour connu, à titre indicatif. delivery vaut not-delivered, sans queue, correlation, receiver ni targetPermissions. Une intégration qui ne connaît pas checked ne doit pas le traiter comme un relais réussi.
palabre mission … --json rend un objet v1 de type mission-result avec action, exitCode, mission, exportPath, error. Seule step appelle Relay, au plus une fois ; ses codes sont ceux de Relay (9 sans résultat), tandis qu'un refus Mission donne 8, ou 3 pour une étape déjà réservée.
palabre config --ollama-models --json expose v, agent, available, baseUrl, currentModel, currentModelInstalled, installedModels, sans génération de modèle.
palabre agents --json ajoute defaults.relayView (background par défaut, ou auto explicitement enregistré), issu de relay.view. Une intégration ne choisit ni ne déduit le mode. Relay v1 ajoute modeSource? : explicit (option --open/--background, y compris suivi explicite), auto (verrou ou parcours imposé), default (arrière-plan sans préférence enregistrée, nouvelle valeur v1), setting (background explicitement enregistré). Absent si la validation s'arrête avant résolution, ainsi que dans les versions antérieures. Les champs du mode open existent aussi quand auto l'a sélectionné. mode décrit le transport retenu ou demandé, pas une preuve d'envoi ; une sonde inconnue refuse sans envoi et ne donne jamais open. Les exclusions restent en arrière-plan, modeSource: "auto", sauf option explicite compatible.
Pour target-busy, remedy peut proposer le réglage habituel seulement si background est enregistré : c'est un choix facultatif à lancer et confirmer par le propriétaire, pas un envoi ni une réparation automatique. Sans préférence (modeSource: "default"), le champ est absent ; le texte explique d'abord les possibilités pour cet échange, puis le réglage habituel. Ne jamais exécuter une commande de configuration à partir de ce champ sans décision humaine.
Pour une conversation Claude déjà utilisée (target-busy, #250), error.message le dit en mots simples et error.hint? (facultatif) distingue la réponse dans le même tour d'une nouvelle initiative. Le champ facultatif handoff?: { status: "saved" | "disabled" | "failed", path? } n'apparaît que pour un envoi ordinaire refusé avant échange : saved donne le chemin d'un fichier local .handoff.md NON ENVOYÉ ; disabled correspond à --no-export ; failed n'a pas de chemin. Ce n'est ni une délivrance, ni un export (exportPath reste null), ni un succès. check.target garde open/closed : pour Claude, c'est l'état du registre des processus attachés, pas l'affichage de l'app. Un consommateur ignore ces champs s'il ne les connaît pas.
Suite après réponse : relay --then-follow (#204)
Ajout facultatif du JSON v1 : nextTurn, seulement si --then-follow <10..3600> a été choisi. La racine reste le résultat du message : status, exitCode, reply, delivery, modèle et permissions primaires ne sont jamais remplacés par ceux de la suite.
nextTurn porte status, reason?, reply?, receiver: "unverified", observedModels?, targetPermissions?, correlation?, retryAfter?. Statuts : followed (réponse du premier tour terminé ensuite), awaiting-turn/reason: "timeout" (aucun tour terminé dans le second délai), not-started/reason: "primary-not-replied" (échec primaire), ou un statut d'échec/annulation secondaire. Un Relay étranger reste no-valid-reply/relay-turn. Tolérer l'absence de l'objet et les valeurs inconnues.
Aucune délivrance secondaire, aucun auteur humain vérifié ni autorisation déduite. Même après annulation ou échec du suivi, une réponse primaire réussie garde replied/0. Deux budgets explicites plafonnés chacun à 3600 s, jamais renouvelés ; référence au saut de ligne après la fin corrélée, jamais EOF. Un seul JSON final sur stdout ; progression sur stderr. Aucun second dépôt ni renvoi.
Quota indicatif Codex (#205)
Ajout facultatif v1 : check.quota pour une vérification Codex ouverte/fermée ; quota à la racine après un envoi ouvert. Pas après un envoi arrière-plan dans ce lot, pas pour Claude. Aucun changement de statut, code ou délivrance.
Même objet aux deux endroits : source: "codex-rollout", indicative: true, recordedAt (ISO UTC), limitId: "codex", primary et secondary. Chaque fenêtre complète porte usedPercent (nombre fini entre 0 et 100), windowMinutes (entier positif) et resetsAt (ISO UTC converti des secondes Unix). Les dates du texte sont locales avec fuseau. Valeurs écrites par Codex, pas mesure en direct ni usage attribué au seul tour ; le compte peut avoir servi ailleurs depuis.
Lecture du dernier Mio + un octet. Seuls les événements event_msg / token_count datés et la forme reconnue de rate_limits sont acceptés. Lignes de bord partielles ignorées ; rate_limits: null ne contient aucun relevé et laisse chercher le précédent ; un dernier candidat non nul inconnu ou invalide masque les anciens. Si aucun relevé exploitable n'est disponible, le champ entier est absent : ne jamais traiter cette absence comme zéro, extrapoler ou supposer une remise à zéro après une date passée. Les consommateurs tolèrent l'absence et les champs futurs.
Copie OpenCode (pilote #136)
--copy ajoute mode: "copy", modeSource: "explicit", cwd et le bloc facultatif
copy : source, session?, verified, retention (none, retained, unknown),
sourceCheck (unchanged, changed, unknown), serverStop (confirmed, unknown)
et diagnostic?. to.session est null tant que la copie n'est pas vérifiée ;
un ID reçu non vérifié peut rester dans copy.session. created reste réservé à --new.
Avec --model fournisseur/modele[#variante] seulement, copy.model ajoute requested
(valeur demandée), source? (sélection source), selected? (sélection de copie contrôlée)
et verified (preuve avant prompt). Sans variante explicite, default est choisi.
Ce bloc est absent sans option ; copy.verified continue de décrire le fork, pas le
modèle ni la réussite du tour. observedModels reste la preuve de la réponse validée.
Choix non confirmé avant envoi : delivery.status: not-delivered, copie conservée,
aucun retry ni substitution. Catalogue local ≠ connexion ou quota garantis.
Une réponse validée et sa délivrance restent conservées après échec final ou d'export.
Le mode conserve le profil habituel d'OpenCode, sans lecture seule imposée.
Ni préférence relay.view, ni quota/lien Codex, ni champs de suivi dans ce parcours.
--background, --open, --check, --follow et --then-follow sont refusés avec --copy.
Pilote Windows/OpenCode CLI 2.0.32 seulement ; source et copie sont conservées.
Ouverture Codex sans message (#219)
palabre relay open --to codex:<uuid> --json rend un objet distinct v1,
type: relay-open-result. Champs : status, exitCode, to, launcher
(attempted, status, exitCode?), attachment (attached, detached, unknown),
reason, display: unverified, messageSent: false, error, durationMs.
Aucun reply, delivery, mode, targetPermissions ou export. Le JSON d'échange
relay-result reste inchangé. Code 0/attached signifie verrou tenu, jamais preuve
d'affichage ni d'app Desktop ; le lanceur est une preuve séparée. Code 3 pour
verrou libre à l'échéance/inconnu ; 4 pour délai pendant validation/lanceur/sonde ;
7 lanceur absent ; 2 échec lanceur ; 130 annulation. Refus de validation conservés.
Ne pas assimiler ce résultat à un message reçu. Un envoi autorisé est séparé et
utilise --open explicite. Sous Windows seulement, Explorer code 1 donne
launcher.status: unverified, launcher.exitCode: 1 conservé, puis sonde du verrou
sans relance. Un verrou déjà tenu ne prouve aucun nouvel affichage. Deux ouvertures
ont été confirmées sous Windows avant ce correctif ; une ouverture corrigée a ensuite
rendu launcher: unverified/1 et attached/0, avec affichage confirmé séparément
par le propriétaire. Cela ne qualifie pas une transition de fermé à ouvert ni
toutes les versions. Claude/OpenCode refusés ; macOS/Linux non vérifiés.
Inventaire Relay JSON
palabre relay recent --json rend un objet unique, pas un flux NDJSON :
{"v":1,"type":"relay-recent-result","status":"listed","exitCode":0,"entries":[],"warnings":[],"truncated":false,"scanTruncated":false,"error":null}
entries[]:fileNamerelatif au dossier de sortie,dateISO de l'export,subjectou null,agent(alias),provider,to: {agent, session}(session éventuellement nulle),modeou null pour un ancien export,status,delivery.- OpenCode sur copie :
to: null,copy: {source, session, verified}distinct ; jamais substituer la source à une copie absente ni proposer une reprise directe. warnings[]:fileNamerelatif etreasonstable (unreadable,invalid-header,header-too-large,not-regular,changed,invalid-name). Pourinvalid-name, le nom est remplacé par[invalid-name], sans afficher de chemin ou contrôle. Un fichier invalide ne compte pas dans--limitet n'empêche pas de présenter les autres.truncated: fichiers non présentés.scanTruncated: plafond de scan/lecture, liste potentiellement incomplète, sans garantie des plus récents globalement.- Codes : 0 liste (même vide), 8 arguments/config refusés, 2 dossier illisible.
Sur erreur :
status: invalid-request|read-failed,error: {reason, message}; listes vides, aucun repli ni écriture.
Aucun chemin de fichier absolu ajouté, prompt, réponse, permission ou commande
fabriquée. L'objet peut contenir des informations privées choisies par l'utilisateur.
Ces métadonnées sont non authentifiées : confirmer humainement l'échange, puis
valider à nouveau la cible et la configuration avant toute ouverture ou envoi.
Le contrat history et les résultats d'envoi Relay ne changent pas.