nexus

Cuando hay que hacer varias tareas y quieres la prueba de que cada una se hizo, el agente Nexus puede mantenerlas en una ejecución duradera. El comando nexus es el libro de registro de esa ejecución. Describes las tareas en un plan JSON; cada tarea posee una carpeta o archivo que puede escribir (su alcance) y una lista de comandos de comprobación que deciden si su resultado es aceptable. El registro anota quién intentó qué (un intento), conserva el estado ante caídas, ejecuta él mismo las comprobaciones y solo entonces te deja aceptar la tarea. Que un worker diga «hecho» nunca es una prueba: las comprobaciones sí. Esta página es para quien maneja Nexus a mano, desde CI, o quiere saber qué hace el agente por dentro.

Sinopsis#

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>]

Las acciones#

Ejecución, verificación, aceptación#

Nexus mantiene separadas tres preguntas. Ejecución: ¿terminó el worker? Un host lo informa con record, o el supervisor en primer plano recoge la salida real del proceso que lanzó. Verificación: ¿pasa el trabajo las comprobaciones del plan? Nexus las ejecuta él mismo, con argumentos literales y sin shell, y compara los artefactos declarados y todo el alcance de escritura antes y después. Aceptación: ¿sigue siendo el espacio de trabajo actual el que pasó? accept vuelve a comprobar las huellas de los artefactos, los recursos protegidos y el estado aceptado de cada dependencia. Una comprobación fallida impide la aceptación aunque el worker haya tenido éxito. Nexus nunca hace commit, fusión, copia de archivos ni despliegue.

El archivo 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: host o proceso#

Por defecto una tarea es del host: tu asistente hace el trabajo con sus propias herramientas y comunica el resultado a Nexus con record. Después Nexus verifica. Añadir un objeto execution a una tarea la convierte en una tarea de proceso: launch arranca el programa en primer plano, lo espera y guarda un recibo con suma de comprobación de lo que realmente ocurrió. Hay dos adaptadores.

Límites#

Qué lee y qué escribe#

• Estado: .bmad-plus/nexus/runs/<run-id>.json, un sobre con suma de comprobación escrito mediante un archivo temporal volcado a disco y un renombrado atómico.
• Bloqueos: .bmad-plus/nexus/writer.lock (una modificación a la vez) y, durante una recuperación excepcional, .bmad-plus/nexus/recovery.lock. Un bloqueo retirado se archiva en .bmad-plus/nexus/lock-recovery/.
• inspect no escribe nada y sigue funcionando mientras corre una verificación. Todas las demás acciones salvo create modifican una ejecución existente; create la crea.
• Lee tu plan y tus archivos de entrada, los recursos y artefactos declarados, y toma una instantánea de los alcances de escritura. La verificación ejecuta tus comandos de comprobación; launch ejecuta el proceso de la tarea. Son los únicos procesos que Nexus inicia, y solo cuando los invocas.
• Los comandos de comprobación reciben un entorno mínimo (PATH, SYSTEMROOT, WINDIR, TEMP, TMP, TMPDIR más el idioma fijado en C y la zona UTC). No se reenvían credenciales ni NODE_OPTIONS. No pongas ningún secreto en los argumentos ni en la salida.

Códigos de salida#

Leer la salida#

El recorrido completo más corto necesita tres archivos pequeños junto a nexus-plan.json. El verificador es el que el plan declara como recurso; host.json es la identidad que tu asistente da a start; rec.json es el resultado que informa a record, con el id de intento que imprimió 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.
# Las palabras tras «acceptance=» y las líneas de pista adicionales dependen del estado de la ejecución; léelas con inspect --json.

Ejecutar verify justo después de create se rechaza, porque todavía no se ha registrado nada: Nexus: Nexus: Verification requires completed, unaccepted, reconciled work. Inicia y registra primero, como arriba. Fíjate en el prefijo duplicado: los mensajes propios del motor ya empiezan por Nexus:, y el comando añade el suyo.

Cada línea de tarea se lee <task>: <execution>; verification=<status>; acceptance=<state>, seguida del último intento con su backend. inspect --json añade, por tarea, resourcesCurrent, evidenceEligible, stale, staleReason y overdue, de modo que un registro aceptado antiguo no puede afirmar que archivos editados después sigan pasando. En modo JSON, los errores se imprimen como {"schemaVersion":1,"status":"error","error":"..."}.

Interrupciones, cancelación, reintentos#

• Un intento interrumpido o desconectado conserva su capacidad hasta que reconcile lo cierra. La observación exige ownerStopped: true, una declaración tuya de que lo comprobaste, no telemetría. Para una tarea no idempotent, el reintento exige además retrySafe: true.
• cancel solo registra una petición. En una tarea del host, el host detiene su propio trabajo; en una tarea de proceso, solo el supervisor original en primer plano puede enviar señales al proceso hijo que creó. Nexus nunca mata un PID guardado.
• retry (o launch con {"retry":true}) abre un intento nuevo y consume maxAttempts. Una sesión de backend nueva no reinicia el límite.
• Una verificación que agota el tiempo se registra como ambigua, porque descendientes de la comprobación aún podrían tener efectos. Inspecciona antes de reintentar.
• recover-lock toma la huella exacta del bloqueo que da inspect, ownerStopped: true y una note no vacía. Un escritor local vivo lo bloquea. La antigüedad por sí sola nunca autoriza la retirada.

Errores y qué hacer#

Los errores se imprimen como Nexus: <message> en el flujo de error. Los mensajes propios del motor ya empiezan por Nexus:, así que la mayoría de los errores muestran el prefijo dos veces (Nexus: Nexus: Run ID must use ...).

Ejemplos#

Nexus, divide el trabajo aprobado en tareas independientes, cada una con su carpeta de escritura y un comando de comprobación que yo pueda ejecutar. Crea una ejecución duradera con `bmad-plus nexus create`, inicia un intento por tarea y no aceptes nada hasta que `bmad-plus nexus verify` haya pasado para ella.

Nexus, inspecciona la ejecución `release-prep` con `bmad-plus nexus inspect release-prep --json`. Dime qué intentos están sin resolver y qué debo comprobar antes de que los reconcilies. No reintentes nada por tu cuenta.