Drei stille gateway-Bugs: ein falsch geschriebener float, eine Maske, die job keys frisst, und ein verschobener sys.path


Dein Alert-Router pingt dich an, weil ein Job in der falschen Queue gelandet ist. Du öffnest das Log, um den Key zu suchen, und da steht ITEM-000042:***. Also war es die redaction. Du prüfst security.redact_secrets, deine Vendor-Präfixe, die Bearer-Token-Regeln — alles sieht richtig aus. Erst beim zweiten Blick fällt es auf: Es wurde kein Secret getroffen. Das Muster begann mitten in einem gewöhnlichen Identifier, hielt die Ziffern an dessen Ende für ein Credential und maskierte mit ihnen den ganzen Key.

Drei Bugs, eine Schicht

Der gateway ist der Prozess hinter Desktop und hinter jeder Chat-Plattform-Integration. Die Plattform-Adapter — Telegram, WhatsApp, Discord, Slack, Raft — sind dünne Übersetzer zwischen diesem Prozess und einer konkreten Netzwerk-API. Sie lesen Konfiguration aus der Umgebung, sie schreiben Logzeilen, die durch den redaction-Filter laufen, und sie importieren Schwestermodule aus dem Repo. Drei alltägliche Aufgaben, drei Bugs.

Alle drei wurden im selben Pull Request der gateway-Schicht behoben (#151738, gemerged am 2026-11-09). Sie wirken unzusammenhängend, und in gewissem Sinn sind sie es auch. Aber sie teilen sich eine Schicht und ein Temperament: Jeder von ihnen versagt an einer anderen Stelle als dort, wo der Fehler sitzt — also taucht keiner je als ein Fehler auf, nach dem du suchen könntest.

Das ist der erste Grund, warum diese Fehlerklasse so schwer zu finden ist. Eine Adapter-Regression sieht nicht wie ein Adapterproblem aus: Sie sieht aus wie ein kaputter job key, ein Bot, der nicht mehr antwortet, oder eine Bibliothek, die die falsche Version meldet. Die erste Stunde verbringst du in der falschen Datei.

Fall eins: ein falsches Zeichen in der .env tötete die Antwort

Telegrams Pfad für „follow-up while busy“ muss wissen, wie lange gewartet werden soll, bevor entschieden wird, ob eine Nachricht ein echtes Follow-up ist oder noch zum laufenden Run gehört. Der Wert kommt aus HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS, und der Code konvertierte ihn mit einem nackten float-Aufruf.

Ein Wert wie abc — ein Tippfehler, ein vergessener Platzhalter oder ein 3s, das jemand schrieb, weil es sich besser liest — warf also ValueError: could not convert string to float: 'abc' in run_inbound.py:697. Diese Exception wurde an der Grenze nicht gefangen. Sie wickelte den gesamten inbound handler ab, was bedeutet: Die Nachricht des Nutzers bekam überhaupt keine Antwort. Kein verspätetes Follow-up. Ein toter Turn.

Der Fix leitet dieses Auslesen über gateway.run._float_env, denselben Helper, den die anderen Timeout-Regler in dem Modul schon nutzen. Schlechte Eingaben werfen nicht mehr: Der Wert fällt auf 3 Sekunden zurück, das Follow-up wird eingereiht, und der Agent arbeitet weiter.

# Falsch — alle drei sind Strings, keine Zahlen
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=abc
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=3s
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=
# Richtig — eine schlichte Zahl in Sekunden
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=3

Warum es verborgen blieb: Der Pfad läuft nur, wenn eine zweite Nachricht eintrifft, während ein Run läuft, also berührt ihn fast kein Test. Und wenn er zuschlägt, zeigt sich der Fehler als „der Bot ignoriert mich“, was die Leute zum Token schickt, dann zum Webhook, dann zum Netzwerk — nicht zu einem Konfigurationswert, den sie vor Wochen getippt haben. Env vars haben kein Typsystem, und nichts validiert sie, bis die Zeile läuft, die sie parst.

Fall zwei: redaction begann mitten im Wort zu treffen

redaction ist Pattern-Matching mit einem Versprechen: Finde die Secrets, lass alles andere in Ruhe. Die zweite Hälfte ist der Teil, der still kaputtgeht.

Ein regex weiß nicht, was ein Wort ist. Wenn du ihm nicht sagst, dass es nur an einer Grenze beginnen darf, fängt es fröhlich bei jedem Zeichen an, das das Muster erfüllt. Das alte Telegram-Muster _TELEGRAM_RE war bereit, mitten in einem ASCII-Identifier zu beginnen, bei der Ziffernfolge an dessen Ende. Eine gewöhnliche job key — geformt wie ITEM-000042:job-a12345678:q-, gefolgt von einem langen Lauf aus a — traf also ab der Mitte und wurde komplett durch *** ersetzt.

Nichts warf. Nichts warnte. Die Logzeile verlor ihren Key, und der Bereitschaftsingenieur verlor zwanzig Minuten.

Der Fix begrenzt, wo ein Treffer beginnen darf: an einer Identifier-Grenze oder nach einem der Escape-Trenner fester Breite, die der Adapter tatsächlich ausgibt (\n, \uXXXX, %XX und Verwandte). Das Ziffernfolge-Lookbehind, das den Scanner davon abhält, dieselben Ziffern erneut abzulaufen, ist weiterhin da — lässt man es weg, wird ein redaction-Durchlauf auf einem langen numerischen String quadratisch.

Eine Test-Assertion musste gelockert werden, und der Grund ist es wert, gekannt zu werden: Die Behandlung von JSON-Key-Namen auf main maskiert jetzt Credential-Werte, bevor Key-Namen verarbeitet werden, also beschreibt eine Assertion, die erwartet, dass ein Key-Name unverändert erscheint, nicht mehr, was der Code tut. Das ist ein Test, der zu einer bewussten Änderung aufschließt, kein Loch, das zugedeckt wird.

Die Lehre lässt sich verallgemeinern: Wenn deine redaction-Regeln eine Liste von regexes sind und keiner davon an einer Grenze ankert, hast du einen Bug, der auf den ersten Identifier wartet, der auf acht Ziffern endet.

Fall drei: ein Adapter-Import mischte den Importpfad neu

sys.path in einem Satz: die geordnete Liste von Verzeichnissen, die Python von vorne nach hinten durchläuft, wenn du import something schreibst, wobei das erste Verzeichnis mit einem Treffer gewinnt. Position null schlägt alles, auch ordentlich in die Umgebung installierte Pakete.

Das Installieren irgendeines Plattform-Adapters — telegram, whatsapp, discord, slack, raft, dazu gateway.platforms.base, cron.scheduler und tools.cronjob_tools — schob früher das Repo-Verzeichnis auf sys.path[0]. Ab diesem Moment löste sich jeder Modulname, der sowohl im Repo als auch in der installierten Umgebung existierte, auf die Repo-Kopie auf.

Die Reproduktion ist ungewöhnlich sauber. Importiere das echte evals-Paket, dann einen Adapter, dann noch einmal import evals: Es bindet jetzt an das evals-Verzeichnis des Repos statt an die installierte Distribution. Zehn von zehn rot vor dem Fix, zehn von zehn grün danach, und die Adapter fassen die Reihenfolge von sys.path überhaupt nicht mehr an.

Das ist der leiseste der drei. Keine Exception, keine Warnung, kein Deprecation-Hinweis. Der Import gelingt und liefert ein Objekt — nur ein anderes, als jeder andere Codepfad im Prozess erwartet. Alles, was auf der Identität der installierten Distribution beruht (Versionsmetadaten, Entry Points, Plugin-Discovery), beginnt Antworten zu liefern, die zu einem anderen Paket gehören, und das Symptom zeigt sich in dem Subsystem, das dieses Modul befragt hat — weit weg von dem Adapter, der den Pfad verschoben hat.

Vorher und nachher, in klaren Worten

Ohne den Test-Harness bleibt das hier übrig:

Probe Vorher Nachher
HERMES_TELEGRAM_FOLLOWUP_GRACE_SECONDS=abc, Nachricht trifft mitten im Run ein ValueError killt die Antwort Schlechter Wert fällt auf 3 Sekunden zurück; das Follow-up wird trotzdem eingereiht
Eine gewöhnliche job key wie ITEM-000042:job-a12345678:q- plus ein langer Lauf aus a Der ganze Key wird zu *** Der Key überlebt unverändert
Ein echtes Credential im selben Logstream Maskiert Weiterhin maskiert
import evals nach einem Adapter-Import, evals von PyPI installiert Bindet an die Repo-Kopie, 10 von 10 Bindet an das installierte Paket, 10 von 10

Lies die dritte Zeile, bevor du irgendeiner redaction-Änderung traust: Ein Muster zu verschärfen ist leicht; es zu verschärfen, ohne wegzulassen, was es geschützt hat, ist die Arbeit.

Die eigene Installation prüfen

Zwei kurze Checks, denn beide Bugs bleiben unsichtbar, bis sie zubeißen.

# Auf welches `evals` löst dieser Interpreter auf?
python3 -c "import evals; print(evals.__file__)"

# Bestätigen, dass die Follow-up-Grace ein schlichter Zahlenwert ist
grep -n FOLLOWUP_GRACE .env

Wenn der erste Befehl einen Pfad in deinem Checkout statt in site-packages ausgibt, siehst du genau den Fehler von oben. Beim zweiten degradiert ein nicht-numerischer Wert jetzt auf den Default von 3 Sekunden statt zu werfen — aber ein stiller Fallback ist immer noch eine falsche Konfiguration, also korrigiere den Wert, statt dich auf den Fallback zu verlassen.

Für die redaction-Hälfte: grep in deinen eigenen Logs nach *** und lies die Zeilen drumherum. Ein maskierter Authorization-Header ist das System bei der Arbeit. Eine maskierte job key, Request-ID oder Trace-ID ist das System bei zu viel Arbeit, und keine Konfigurationsprüfung wird das aufdecken.

Wer was behoben hat

Drei Fixes, drei Ursprünge, zusammen gemerged:

  • Der redaction-Grenzfix (#145664) wurde von @liuhao1024 cherry-picked, mit einem Patch von @yuzilongleif-collab.
  • Der Follow-up-Grace-Fix (#50120) wurde aus @Bartok9s #51324 cherry-picked.
  • Der sys.path-Fix (#117698) baut auf @beardthelions #117699 auf.

Die Kurzfassung

Ein Bug ist so schwer zu finden, wie sein Symptom von seiner Ursache entfernt sitzt. Ein vertippter float in einer env var sieht aus wie ein kaputter Bot. Ein regex, der mitten im Wort beginnt, sieht aus wie eine funktionierende Maske. Ein neu geordneter Importpfad sieht aus wie ein funktionierender Import.

Nimm die Prüfgewohnheiten mit, nicht die drei Patches. Gib __file__ für die Module aus, auf die du dich verlässt. Lass keinen Konfigurationswert ohne Fallback an einen Parser gelangen. Ankere jeden redaction-regex an einer Grenze und lies noch einmal, was er beim letzten Mal getroffen hat. Jede dieser Gewohnheiten hätte alle drei in Minuten gefangen.

Verwandte Lektüre: warum ein Cookie in einer Logzeile ein Login ist, was ein Telegram-409 früher gekostet hat, wie blockierende Aufrufe den gateway event loop einfrieren ließen, und die Konfigurationsreferenz.