nexus

Quand plusieurs tâches doivent être faites et que vous voulez la preuve que chacune l’a été, l’agent Nexus peut les garder dans une exécution durable. La commande nexus est le registre de cette exécution. Vous décrivez les tâches dans un plan JSON ; chaque tâche possède un dossier ou un fichier qu’elle peut écrire (son périmètre) et une liste de commandes de contrôle qui décident si son résultat est acceptable. Le registre consigne qui a essayé quoi (une tentative), conserve l’état malgré les pannes, lance lui-même les contrôles, et ne laisse accepter la tâche qu’ensuite. Un worker qui dit « terminé » n’est jamais une preuve : les contrôles le sont. Cette page s’adresse à qui pilote Nexus à la main, depuis la CI, ou veut savoir ce que fait l’agent en coulisses.

Synopsis#

npx bmad-plus nexus create --plan <file> [--json] [-d <path>]
npx bmad-plus nexus inspect [run] [--json] [-d <path>]
npx bmad-plus nexus recover-lock --input <file> [--json] [-d <path>]
npx bmad-plus nexus <start|launch|collect|record|reconcile|verify|retry|cancel|accept> <run> <task> [--input <file>] [--json] [-d <path>]

Les actions#

Exécution, vérification, acceptation#

Nexus garde trois questions séparées. Exécution : le worker a-t-il terminé ? Un hôte le rapporte avec record, ou le superviseur au premier plan recueille la vraie sortie du processus qu’il a lancé. Vérification : le travail passe-t-il les contrôles du plan ? Nexus les lance lui-même, avec des arguments littéraux et sans shell, et compare les artefacts déclarés et tout le périmètre d’écriture avant et après. Acceptation : l’espace de travail actuel est-il toujours celui qui a réussi ? accept revérifie les empreintes des artefacts, les ressources protégées et l’état accepté de chaque dépendance. Un contrôle en échec empêche l’acceptation même si le worker a réussi. Nexus ne fait jamais de commit, de fusion, de copie de fichiers ni de déploiement.

Le fichier de plan#

{
  "id": "example",
  "maxParallel": 1,
  "config": { "language": "English" },
  "tasks": [
    {
      "id": "result",
      "objective": "Produce the requested result in work/result.txt.",
      "acceptance": ["The result satisfies the independent check."],
      "dependsOn": [],
      "scope": ["work"],
      "artifacts": ["work/result.txt"],
      "resources": ["checks/check-result.cjs"],
      "checks": [
        {
          "id": "result-content",
          "command": "node",
          "args": ["checks/check-result.cjs"],
          "cwd": ".",
          "timeoutMs": 30000
        }
      ],
      "maxAttempts": 2,
      "deadlineMs": 3600000,
      "idempotent": true,
      "authorizations": ["Edit work/ and run the listed local check."]
    }
  ]
}

Backends : hôte ou processus#

Par défaut, une tâche appartient à l’hôte : votre assistant fait le travail avec ses propres outils et dit à Nexus le résultat avec record. Nexus vérifie ensuite. Ajouter un objet execution à une tâche en fait une tâche de processus : launch démarre le programme au premier plan, l’attend et conserve un reçu à somme de contrôle de ce qui s’est réellement passé. Il existe deux adaptateurs.

Limites#

Ce qu’elle lit et écrit#

• État : .bmad-plus/nexus/runs/<run-id>.json, une enveloppe à somme de contrôle écrite par un fichier temporaire vidé sur disque puis un renommage atomique.
• Verrous : .bmad-plus/nexus/writer.lock (une modification à la fois) et, pendant une récupération exceptionnelle, .bmad-plus/nexus/recovery.lock. Un verrou retiré est archivé sous .bmad-plus/nexus/lock-recovery/.
• inspect n’écrit rien et continue de fonctionner pendant une vérification. Toutes les autres actions sauf create modifient une exécution existante ; create la crée.
• Lit votre plan et vos fichiers d’entrée, les ressources et artefacts déclarés, et prend un instantané des périmètres d’écriture. La vérification lance vos commandes de contrôle ; launch lance le processus de la tâche. Ce sont les seuls processus que Nexus démarre, et seulement quand vous les invoquez.
• Les commandes de contrôle reçoivent un environnement minimal (PATH, SYSTEMROOT, WINDIR, TEMP, TMP, TMPDIR, plus la langue fixée à C et le fuseau UTC). Identifiants et NODE_OPTIONS ne sont pas transmis. Ne mettez aucun secret dans les arguments ni dans la sortie.

Codes de sortie#

Lire la sortie#

Le parcours complet le plus court demande trois petits fichiers à côté de nexus-plan.json. Le vérificateur est celui que le plan déclare comme ressource ; host.json est l’identité que votre assistant donne à start ; rec.json est le résultat qu’il rapporte à record, avec l’identifiant de tentative qu’a affiché start.

const fs = require("node:fs");
const text = fs.readFileSync("work/result.txt", "utf8");
if (!text.includes("done")) {
  console.error("work/result.txt must contain done");
  process.exit(1);
}

{ "backend": { "kind": "host", "id": "my-assistant", "sessionId": "session-1" } }

{
  "attemptId": "c3bbafd1-62ef-4b8b-ac72-0d9b09932427",
  "backend": { "kind": "host", "id": "my-assistant", "sessionId": "session-1" },
  "outcome": "completed",
  "summary": "Wrote work/result.txt."
}

$ npx bmad-plus nexus create --plan nexus-plan.json
Nexus run example — durable task coordination
result: not started; verification=pending; acceptance=pending
Use inspect --json for recorded evidence and reconciliation observations.
$ npx bmad-plus nexus start example result --input host.json
Nexus run example — durable task coordination
result: running; verification=pending; acceptance=pending
  Attempt: c3bbafd1-62ef-4b8b-ac72-0d9b09932427; host: my-assistant/session-1
Use inspect --json for recorded evidence and reconciliation observations.
$ npx bmad-plus nexus record example result --input rec.json
Nexus run example — durable task coordination
result: completed; verification=pending; acceptance=pending
  Attempt: c3bbafd1-62ef-4b8b-ac72-0d9b09932427; host: my-assistant/session-1
Use inspect --json for recorded evidence and reconciliation observations.
$ npx bmad-plus nexus verify example result
Nexus run example — durable task coordination
result: completed; verification=passed; acceptance=pending
  Attempt: c3bbafd1-62ef-4b8b-ac72-0d9b09932427; host: my-assistant/session-1
Use inspect --json for recorded evidence and reconciliation observations.
$ npx bmad-plus nexus accept example result
Nexus run example — durable task coordination
result: completed; verification=passed; acceptance=accepted
  Attempt: c3bbafd1-62ef-4b8b-ac72-0d9b09932427; host: my-assistant/session-1
Use inspect --json for recorded evidence and reconciliation observations.
$ npx bmad-plus nexus inspect example
Nexus run example — durable task coordination
result: completed; verification=passed; acceptance=accepted
  Attempt: c3bbafd1-62ef-4b8b-ac72-0d9b09932427; host: my-assistant/session-1
  Accept only after rechecking current artifacts and resources.
Use inspect --json for recorded evidence and reconciliation observations.
# Les mots après « acceptance= » et les lignes d’indice supplémentaires dépendent de l’état de l’exécution ; lisez-les avec inspect --json.

Lancer verify juste après create est refusé, car rien n’a encore été enregistré : Nexus: Nexus: Verification requires completed, unaccepted, reconciled work. Démarrez et enregistrez d’abord, comme ci-dessus. Notez le préfixe doublé : les messages propres au moteur commencent déjà par Nexus:, et la commande ajoute le sien.

Chaque ligne de tâche se lit <task>: <execution>; verification=<status>; acceptance=<state>, suivie de la dernière tentative avec son backend. inspect --json ajoute, par tâche, resourcesCurrent, evidenceEligible, stale, staleReason et overdue : un ancien enregistrement accepté ne peut donc pas prétendre que des fichiers modifiés depuis passent encore. En mode JSON, les erreurs sont affichées sous la forme {"schemaVersion":1,"status":"error","error":"..."}.

Interruptions, annulation, reprises#

• Une tentative interrompue ou déconnectée garde sa capacité jusqu’à ce que reconcile la règle. L’observation exige ownerStopped: true, une déclaration de votre part que vous avez vérifié, pas de la télémétrie. Pour une tâche non idempotent, une reprise exige aussi retrySafe: true.
• cancel ne fait que consigner une demande. Pour une tâche d’hôte, l’hôte arrête son propre travail ; pour une tâche de processus, seul le superviseur d’origine au premier plan peut envoyer un signal au processus fils qu’il a créé. Nexus ne tue jamais un PID enregistré.
• retry (ou launch avec {"retry":true}) ouvre une nouvelle tentative et consomme maxAttempts. Une nouvelle session de backend ne remet pas la limite à zéro.
• Une vérification qui dépasse son délai est consignée comme ambiguë, car des descendants du contrôle pourraient encore avoir des effets. Inspectez avant de reprendre.
• recover-lock prend l’empreinte exacte du verrou donnée par inspect, ownerStopped: true et une note non vide. Un écrivain local vivant le bloque. L’âge seul n’autorise jamais le retrait.

Erreurs et que faire#

Les erreurs sont affichées sous la forme Nexus: <message> sur le flux d’erreur. Les messages propres au moteur commencent déjà par Nexus:, si bien que la plupart des erreurs montrent le préfixe deux fois (Nexus: Nexus: Run ID must use ...).

Exemples#

Nexus, découpe le travail approuvé en tâches indépendantes, chacune avec son dossier d’écriture et une commande de contrôle que je peux lancer. Crée une exécution durable avec `bmad-plus nexus create`, démarre une tentative par tâche et n’accepte rien tant que `bmad-plus nexus verify` n’a pas réussi pour elle.

Nexus, inspecte l’exécution `release-prep` avec `bmad-plus nexus inspect release-prep --json`. Dis-moi quelles tentatives sont non résolues et ce que je dois vérifier avant que tu les réconcilies. Ne reprends rien de ta propre initiative.