v0.23.1: Eine 2-MiB-Grenze hat deinen Plugin-Katalog still in der Vergangenheit eingefroren


Ein Kollege wirft einen Plugin-Namen in den Team-Channel und schreibt „installier das, ist richtig gut“. Du tippst den Install-Befehl, und Hermes antwortet, dass es dieses Plugin nicht findet. Du gehst von einem Tippfehler aus, probierst eine andere Schreibweise, gleiche Antwort. Du öffnest die Katalogseite: da steht es, mit Version, Repo und Beschreibung.

Mit deinem Netz oder deiner Rechtschreibung ist nichts falsch. Seit dem 9. November ist die offiziell veröffentlichte Katalogdatei größer, als der Client akzeptiert — und wenn der Client entscheidet, dass eine Datei zu groß ist, beschwert er sich nicht. Er fällt still auf die Kopie zurück, die in deiner Release mitgeliefert wird. Was du durchsuchen kannst, ist ein Schnappschuss vom Tag, an dem diese Release geschnitten wurde. v0.23.1 hebt die Grenze an, damit wieder der Live-Katalog greift.

Drei Dinge lohnen sich zu verstehen: wie die Grenze zubeißt, warum „still“ hier der teure Teil ist, und wie du deine eigene Installation prüfst. Dazu der Rest des Fensters.

Die Kurzfassung: updaten

hermes update

Danach akzeptiert der Client bis zu 16 MiB statt 2 MiB. Der Live-Katalog lädt wieder, also sieht hermes plugins install neu gelistete Plugins, löst aktuelle Pins statt der in deiner Release ausgelieferten auf und respektiert neuere removed-Einträge.

Ein Vorbehalt, der zählt: der Fix steckt im Client. Installationen, die auf v0.23.0 oder älter bleiben, fallen weiter zurück, bis sie updaten. Wenn also jemand schwört, ein Plugin existiere nicht, frag nach hermes version, bevor du irgendetwas anderes debuggst.

Wie eine Grenze zubeißt

Der Plugin-Katalog ist ein öffentliches JSON-Dokument, das beim Stöbern oder Installieren geladen und dann sechs Stunden lokal gecacht wird. Zwei Quellen, in strikter Prioritätsreihenfolge:

  1. Der Live-Katalog (plugin-catalog.json), veröffentlicht von der Docs-Seite — neueste Einträge, neueste Versions-Pins, neueste Removals;
  2. Der In-Tree-Katalog, der mit deiner Installation ausgeliefert wird — nie aktualisiert, nur genutzt, wenn der Live-Katalog nicht geladen werden kann.

Der Fetch-Pfad hat eine Größenprüfung. Über der Grenze gilt die Antwort als kaputt: es wird ein Fehler geworfen, eine Zeile auf debug-Level geloggt und „kein Live-Katalog“ zurückgegeben. Jeder Aufrufer weiter oben sieht „nichts“, fällt auf die In-Tree-Kopie zurück und sagt dir nichts.

Am 9. November maß das veröffentlichte Dokument 2.109.306 Bytes über 1.268 Einträge — rund 1,7 KB pro Eintrag — und überschritt die 2-MiB-Linie. Seitdem:

  • neu gelistete Plugins existierten auf deiner Maschine nicht;
  • Plugins, die auf einen neueren Commit re-gepinnt wurden, installierten auf dem Pin, den deine Release ausgeliefert hat;
  • neuere „removed / unmaintained“-Einträge waren unsichtbar.

Der dritte Punkt ist der, bei dem man kurz sitzen bleiben sollte. Ein Plugin, das offiziell zurückgezogen wurde, sieht auf deiner Installation nicht mehr zurückgezogen aus — es sieht weiter installierbar aus.

Mal eben das Live-Dokument gemessen: 1.380 Einträge, 2.310.445 Bytes. Das liegt schon 10 % über der alten Grenze. Ohne die Anhebung würde das nur häufiger, nicht seltener.

Warum „still“ der teure Teil war

Nüchtern betrachtet ist der Bug eine Konstante, die zu klein gesetzt war. Schwierig ist der Fehlermodus: jeder Fehler wurde geschluckt.

Das Design ist für sich genommen richtig. Ein fehlender Katalog sollte eine Installation nie blockieren — wenn das Netz weg ist oder die Docs-Seite einen schlechten Tag hat, solltest du trotzdem aus der Kopie installieren können, die du schon hast. Bei jedem Fehler zurückzufallen ist die richtige Politik.

Das Problem ist, dass „das Dokument ist zu groß“ und „ich habe kein Netz“ im selben Topf landeten. Das erste heißt: dein Katalog ist veraltet, und das sollte dich kümmern. Das zweite heißt: warte eine Minute und versuch es erneut. Für Nutzerinnen und Nutzer sah beides gleich aus, die nötigen Schritte waren entgegengesetzt. Der Bug lebte von dieser Mehrdeutigkeit, bis jemand fehlende Plugins bemerkte und die Spur bis zur Konstante zurückverfolgte.

So sehen die meisten Infrastruktur-Bugs aus: nichts stürzt ab, nichts weckt jemanden, keine Logzeile wird rot — die Welt wird einfach still älter. Du machst alles richtig und bekommst die falsche Antwort.

Was sich geändert hat

Der Fix ist eine Konstante, aber der Kommentar, der mitkam, lohnt sich, weil er die Grenze benennt:

  • die Grenze wandert von 2 * 1024 * 1024 auf 16 * 1024 * 1024;
  • bei aktuellen Eintragsgrößen passen in 16 MiB rund 9.000 Einträge;
  • die Grenze ist nicht weg. Sie begrenzt weiterhin eine feindliche oder kaputte Antwort — sie bestraft nur kein normales Wachstum mehr.

Dieselbe Datei trägt die umgebenden Fallback-Regeln, und wer sie kennt, weiß, auf welchem Katalog er unterwegs ist:

Regel Wert Was sie bedeutet
Normaler Cache 6 Stunden wiederholte Aufrufe im Fenster überspringen den Download
Veralteter Cache nutzbar für 24 Stunden ältere Caches verwerfen Einträge und behalten nur die Removals-Liste
Fehler-Gedächtnis 60 Sekunden nach einem Fehler kein Retry für 60 s
Request-Timeout 5 Sekunden Netz-Timeout pro Versuch

Die eigene Installation prüfen

Der ehrliche Test ist ein Verhaltenstest: versuch ein kürzlich gelistetes Plugin zu installieren und schau, ob es aufgelöst wird. Die hermes plugins-Referenzseite listet den kompletten Satz an Subcommands.

Zwei Gewohnheiten lohnen sich:

  • wenn ein Plugin „nicht existiert“, zuerst hermes version laufen lassen — dann den Katalog in Betracht ziehen;
  • wenn ein Plugin sich wie eine Version verhält, die du nicht installiert hast, den aufgelösten Pin prüfen, bevor du das Plugin verantwortlich machst.

Wenn du unseren früheren Text dazu gelesen hast, wie der Plugin-Katalog funktioniert, ist das eine direkte Folge dieses Designs: der Katalog ist Daten, kein Code, und Datenwachstum drückt irgendwann auf die Annahmen des Clients. Dieselbe Logik zeigt sich an der öffentlichen Plugin-API-Oberfläche — stabile Schnittstellen sind das, was Daten wachsen lässt, und Clients müssen dafür Platz lassen.

Was sonst im Fenster steckt

v0.23.1 ist ein Patch-Tag: 618 gemergte PRs seit v0.23.0, gerollt in eine stabile Release für das GitHub-Release (CLI und Installer), die Microsoft-Store-App, Docker und Hermes Cloud. Gemessen auf Commit 3b421578588 enthält das Fenster 2.578 Non-Merge-Commits über 2.781 geänderte Dateien (+151.690 / −62.595) und 409 geschlossene Issues.

Die Release Notes sagen klar, dass ein Teil der Features in diesem Fenster bewusst undokumentiert bleibt und die vollständigen kuratierten Notes zusammen mit v0.24.0 erscheinen. Genannt werden:

  • Esc-Backtrack in der TUI und der klassischen CLI, das den Rewind-Listen-Picker ersetzt;
  • Gruppenchats, die auf einem Gateway ohne Desktop laufen und Bots von anderen Rechnern aufnehmen können;
  • gespeicherte Gateway-Verbindungen, die Desktop und Webapp teilen;
  • der In-App-Browser, der sich mit deinem echten Browser-Profil anmeldet und gespeicherte Logins aus der Adressleiste füllt;
  • hermes gateway attach für lokale Clients;
  • hermes clipboard image --json;
  • neue Plugin-API-Oberfläche: sitzungsbezogene Environment-Werte, Plugin-JSON-RPC-Methoden und -Events, llm.oneshot-Hilfsaufgaben, eine kompressionsstabile conversation_id, ein on_session_open-Hook im Gateway und ein post_curator_run-Hook;
  • schnellere Transcript- und Handoff-Reads plus ein großer Schwung neuer Katalog-Einträge.

Das meiste davon haben wir separat behandelt: den Esc-Backtrack-Workflow in eine Konversation zurückspulen, ohne sie zu verlieren, die Katalog-Pflege in wie Katalog-Einträge im Batch durchgesehen werden, und das große Bild auf der v0.23.0-Release-Seite.

Upgrade

# CLI
hermes update

# oder den Installer-Einzeiler erneut ausführen
# Docker / Hermes Cloud: nousresearch/hermes-agent:stable

Die Microsoft-Store-App aktualisiert über den Store. Eine Desktop-App aus dem .exe/.dmg-Installer ändert sich in dieser Release nicht; sie bekommt den Fix mit der nächsten gebündelten Release.

Eine Sache lohnt sich nach dem Update: das Plugin installieren, das „nicht existierte“, und prüfen, ob es aufgelöst wird. Wenn nicht, schau in hermes plugins list und auf deine Client-Version — dann liegt das Problem am Plugin-Eintrag oder am Repo, nicht am Katalog-Cache.

Vollständige Notes: die v0.23.1-Release-Seite.