nexus

Wenn mehrere Aufgaben erledigt werden müssen und du den Beleg willst, dass jede erledigt wurde, kann der Agent Nexus sie in einem dauerhaften Lauf führen. Der Befehl nexus ist das Register dieses Laufs. Du beschreibst die Aufgaben in einem JSON-Plan; jede Aufgabe besitzt einen Ordner oder eine Datei, die sie schreiben darf (ihren Schreibbereich), und eine Liste von Prüfbefehlen, die entscheiden, ob ihr Ergebnis akzeptabel ist. Das Register hält fest, wer was versucht hat (ein Versuch), bewahrt den Zustand über Abstürze hinweg, führt die Prüfungen selbst aus und lässt dich die Aufgabe erst danach abnehmen. Ein Worker, der „fertig“ sagt, ist nie ein Beleg: die Prüfungen sind es. Diese Seite ist für alle, die Nexus von Hand oder aus CI steuern oder wissen wollen, was der Agent im Hintergrund tut.

Syntax#

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

Die Aktionen#

Ausführung, Prüfung, Abnahme#

Nexus hält drei Fragen auseinander. Ausführung: Ist der Worker fertig? Ein Host meldet es mit record, oder der Vordergrund-Supervisor erfasst das echte Ende des von ihm gestarteten Prozesses. Prüfung: Besteht die Arbeit die Checks des Plans? Nexus führt sie selbst aus, mit wörtlichen Argumenten und ohne Shell, und vergleicht die deklarierten Artefakte und den ganzen Schreibbereich davor und danach. Abnahme: Ist der aktuelle Arbeitsstand noch der, der bestanden hat? accept prüft Artefakt-Hashes, geschützte Ressourcen und den abgenommenen Zustand jeder Abhängigkeit erneut. Ein fehlgeschlagener Check verhindert die Abnahme, auch wenn der Worker erfolgreich war. Nexus macht nie Commits, Merges, Dateikopien oder Deployments.

Die Plandatei#

{
  "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 oder Prozess#

Standardmäßig gehört eine Aufgabe dem Host: Dein Assistent erledigt die Arbeit mit seinen eigenen Werkzeugen und meldet Nexus das Ergebnis mit record. Danach prüft Nexus. Ein execution-Objekt macht die Aufgabe zur Prozess-Aufgabe: launch startet das Programm im Vordergrund, wartet darauf und speichert einen prüfsummengesicherten Beleg dessen, was wirklich geschah. Es gibt zwei Adapter.

Grenzen#

Was gelesen und geschrieben wird#

• Zustand: .bmad-plus/nexus/runs/<run-id>.json, ein prüfsummengesicherter Umschlag, geschrieben über eine auf Platte geleerte temporäre Datei und ein atomares Umbenennen.
• Sperren: .bmad-plus/nexus/writer.lock (eine Änderung zur Zeit) und bei einer außerordentlichen Wiederherstellung .bmad-plus/nexus/recovery.lock. Eine entfernte Sperre wird unter .bmad-plus/nexus/lock-recovery/ archiviert.
• inspect schreibt nichts und funktioniert weiter, während eine Prüfung läuft. Alle anderen Aktionen außer create verändern einen bestehenden Lauf; create legt ihn an.
• Liest deinen Plan und deine Eingabedateien, die deklarierten Ressourcen und Artefakte und macht Snapshots der Schreibbereiche. Die Prüfung führt deine Prüfbefehle aus; launch startet den Prozess der Aufgabe. Das sind die einzigen Prozesse, die Nexus startet, und nur auf deinen Aufruf.
• Prüfbefehle erhalten eine minimale Umgebung (PATH, SYSTEMROOT, WINDIR, TEMP, TMP, TMPDIR sowie feste Locale C und Zeitzone UTC). Zugangsdaten und NODE_OPTIONS werden nicht weitergegeben. Lege keine Geheimnisse in Argumente oder Ausgaben.

Exit-Codes#

Die Ausgabe lesen#

Der kürzeste vollständige Durchlauf braucht drei kleine Dateien neben nexus-plan.json. Der Prüfer ist derjenige, den der Plan als Ressource deklariert; host.json ist die Identität, die dein Assistent start übergibt; rec.json ist das Ergebnis, das er record meldet, mit der Versuchs-ID, die start ausgegeben hat.

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.
# Die Wörter nach „acceptance=“ und die zusätzlichen Hinweiszeilen hängen vom Zustand des Laufs ab; lies sie mit inspect --json.

verify direkt nach create wird abgelehnt, weil noch nichts erfasst wurde: Nexus: Nexus: Verification requires completed, unaccepted, reconciled work. Starte und erfasse zuerst, wie oben. Beachte das doppelte Präfix: Die eigenen Meldungen der Laufzeit beginnen bereits mit Nexus:, und der Befehl fügt sein eigenes hinzu.

Jede Aufgabenzeile lautet <task>: <execution>; verification=<status>; acceptance=<state>, gefolgt vom letzten Versuch mit seinem Backend. inspect --json ergänzt pro Aufgabe resourcesCurrent, evidenceEligible, stale, staleReason und overdue, damit ein alter abgenommener Eintrag nicht behaupten kann, später bearbeitete Dateien bestünden noch. Im JSON-Modus werden Fehler als {"schemaVersion":1,"status":"error","error":"..."} ausgegeben.

Unterbrechungen, Abbruch, Wiederholungen#

• Ein unterbrochener oder getrennter Versuch behält seine Kapazität, bis reconcile ihn abschließt. Die Beobachtung verlangt ownerStopped: true, eine Aussage von dir, dass du geprüft hast, keine Telemetrie. Bei einer nicht idempotenten Aufgabe braucht ein Retry zusätzlich retrySafe: true.
• cancel hält nur eine Anfrage fest. Bei einer Host-Aufgabe stoppt der Host seine eigene Arbeit; bei einer Prozess-Aufgabe darf nur der ursprüngliche Vordergrund-Supervisor dem von ihm erzeugten Kindprozess Signale senden. Nexus tötet nie eine gespeicherte PID.
• retry (oder launch mit {"retry":true}) eröffnet einen neuen Versuch und verbraucht maxAttempts. Eine neue Backend-Sitzung setzt das Limit nicht zurück.
• Eine Prüfung mit Zeitüberschreitung wird als mehrdeutig festgehalten, weil Nachkommen des Checks noch Wirkung haben könnten. Inspiziere vor einem Retry.
• recover-lock nimmt den exakten Lock-Hash aus inspect, ownerStopped: true und eine nicht leere note. Ein lebender lokaler Schreiber blockiert es. Das Alter allein erlaubt nie das Entfernen.

Fehler und was zu tun ist#

Fehler erscheinen als Nexus: <message> auf dem Fehlerstrom. Die eigenen Meldungen der Laufzeit beginnen bereits mit Nexus:, daher zeigen die meisten Fehler das Präfix doppelt (Nexus: Nexus: Run ID must use ...).

Beispiele#

Nexus, teile die freigegebene Arbeit in unabhängige Aufgaben auf, jede mit eigenem Schreibordner und einem Prüfbefehl, den ich ausführen kann. Lege mit `bmad-plus nexus create` einen dauerhaften Lauf an, starte pro Aufgabe einen Versuch und nimm nichts ab, bevor `bmad-plus nexus verify` dafür bestanden hat.

Nexus, inspiziere den Lauf `release-prep` mit `bmad-plus nexus inspect release-prep --json`. Sag mir, welche Versuche ungeklärt sind und was ich prüfen muss, bevor du sie abgleichst. Wiederhole nichts auf eigene Faust.