Codex-Turns: Steuern, Freigaben, Ziele und Wiederherstellung

Ein Thread, ein Run: Start, Besitzer und Steuern #

Ein Codex-Run in HB Code ist eine Leser-Task, die einem Turn oder einer Kette von Turns auf einem Codex-Thread folgt. Alles in diesem Kapitel hängt an diesem Leser: Freigaben erreichen ihn über die Turn-Route, Stop spricht mit ihm über einen Steuerkanal, ein Ziel gibt ihm den nächsten Turn, und die Wiederherstellung gibt ihm eine neue Route. Der Prozess, der Actor und die Turn-Route stehen im Kapitel zum App-Server. Die Outbox, die entscheidet, wann eine Nachricht gesendet wird, steht im Kapitel zur Nachrichtenzustellung.

Der Besitzer-Eintrag ist eine Map im Speicher des Desktops mit der Codex-Thread-ID als Schlüssel. Er verhindert, dass zwei App-Sessions, die denselben Thread verknüpfen, ihn gleichzeitig ausführen. Derselbe Run kann ohne Fehler erneut beanspruchen. Ein veralteter Besitzer wird entfernt, wenn sein eingetragener Codex-Kindprozess tot ist. Hat der Eintrag keine pid, wird er nach 45 Sekunden entfernt, und nur, wenn der Run nicht mehr aktiv ist. Die Sperre wird nach thread/unload freigegeben und bevor die Abschlüsse die Outbox wecken, daher findet die nächste wartende Nachricht den Thread frei.

Steuern fügt dem Turn, der gerade läuft, eine Nachricht hinzu. Der Desktop sendet turn/steer auf dem Laufzeitpaar, dem der aktive Turn gehört. Er öffnet keinen Thread, startet keinen Turn und beansprucht keinen Besitzer, denn der Leser, der schon läuft, behält alle drei.

Stop and send now braucht einen weiteren Aufruf. Eine Steuerung, die Codex angenommen hat, kann im Turn noch als wartende Eingabe liegen. Der Desktop sendet turn/detachPendingInputForReplay mit derselben threadId, expectedTurnId und clientUserMessageId. Die Antworten detachedForReplay und alreadyDetachedForReplay erlauben die Wiederholung in einem neuen Turn. Die Antwort applied bedeutet, dass das Modell die Nachricht schon hat, also startet keine Wiederholung. Die Antworten recording und staleTarget sowie jeder Fehler blockieren die Wiederholung ebenfalls.

Wer eine Freigabe beantwortet #

Codex bittet mit einer JSON-RPC-Anfrage um eine Freigabe und wartet auf die Antwort. Der Actor dieses Codex-Kindprozesses hält jede offene Anfrage in einer Map und muss jemanden finden, der sie anzeigen kann. Eine Anfrage, die niemand anzeigen kann, wird abgelehnt, denn ein Turn, der auf eine Antwort wartet, die nicht kommen kann, würde nie enden.

• Die Zustellung hat zwei Wege. Eine Anfrage für einen Turn mit einer aktiven Route geht an den Leser dieses Turns, der die Karte in der Session zeigt. Eine Anfrage ohne Route wird an Beobachter verteilt. Anfragen aus Subagent-Threads nehmen diesen Weg, weil kein Leser ihre Turns besitzt.
• Ein Beobachter muss eine verteilte Anfrage innerhalb von 30 Sekunden beanspruchen. Der Beobachter des Runs weist zuerst nach, dass der Thread zu seinem Root-Thread gehört, mit einer Grenze von 10 Sekunden für diese Prüfung. Eine nicht beanspruchte Anfrage wird abgelehnt, wenn die 30 Sekunden enden.
• Eine Anfrage ohne unterstützte Entscheidung und eine Anfrage ohne Route und ohne Beobachter werden sofort abgelehnt.
• Codex kann dieselbe Anfrage nach einer Wiederverbindung erneut senden. Eine identische Anfrage behält ihren Platz. Bei einer anderen Anfrage mit derselben ID lehnt der Desktop diese ID ab und schließt die Karte.
• Wenn turn/completed eintrifft, lehnt der Actor jede offene Anfrage dieses Turns ab, bevor der Leser den Abschluss sieht. Das Aufgeben eines Turns und das Herunterfahren des Actors tun dasselbe.
• serverRequest/resolved von Codex schließt die Karte als anderswo erledigt. Während des initialize-Handshakes kann es keine Karte geben, daher wird eine Freigabeanfrage abgelehnt.

Eine Antwort aus dem Desktop-Fenster oder von einem Telefon nimmt einen einzigen Weg. Ein Telefon ruft run.chatResolveApproval auf, und der Desktop bietet die Antwort jedem laufenden Codex-Kindprozess an, den zuletzt verwendeten zuerst. Jeder Actor vergleicht Anfrage-ID, Thread-ID, Turn-ID und Item-ID mit seiner Map, also nimmt genau ein Kindprozess sie an. Eine Entscheidung, die die Anfrage nicht angeboten hat, wird abgewiesen.

Die Zugriffsstufe Unrestricted sendet approvalPolicy never. Trifft trotzdem eine Anfrage ein, beantwortet der Leser sie ohne Karte. Er wählt die erste Entscheidung, die die Anfrage anbietet, aus acceptForSession, accept und „breit annehmen“. Die anderen Zugriffsstufen senden approvalPolicy on-request.

Ziele: viele Turns in einem Run #

Ein Ziel ist Zustand, den Codex an einem Thread hält: eine Zielvorgabe, ein Status, ein Token-Budget und Zähler. Solange der Status active ist, startet Codex den nächsten Turn von selbst, wenn ein Turn endet. Der Desktop startet diese Turns nicht. Er findet jeden und hängt einen Leser an, und die ganze Kette bleibt ein Chat-Run mit einer Operations-ID.

Ein Ziel hat die Felder objective, status, tokenBudget, tokensUsed, timeUsedSeconds, createdAt und updatedAt. Der Status ist einer von active, paused, blocked, usageLimited, budgetLimited und complete. Der Leser folgt der Kette nur, solange der Status active ist.

• Ein Ziel-Run startet mit thread/goal/set und dem Status active. Er sendet kein turn/start. Codex startet den ersten Turn.
• Nach jedem Turn sendet der Leser thread/goal/get. Solange das Ziel active ist, sendet er thread/resume mit excludeTurns: false und nimmt den neuesten Turn. Ein Turn zählt, wenn seine ID neu ist oder wenn er noch läuft. Der Leser versucht es 3-mal im Abstand von 250 ms und liest dann das Ziel erneut.
• Ein laufender Turn bekommt eine Turn-Route und wird wie jeder andere Turn gelesen. Ein Turn, der schon abgeschlossen ist, wird aus dem Snapshot in der resume-Antwort abgeschlossen.
• Jeder Codex-Chat-Run endet mit derselben Prüfung. Eine Nachricht an einen Thread mit einem aktiven Ziel bleibt daher ein Run, bis das Ziel den Status active verlässt. Ein Run, der kein aktives Ziel findet, sucht trotzdem einmal mit thread/resume nach einem neueren Turn und endet dann.
• Eine Steuerung, die zwischen zwei Turns eintrifft, wartet. Jeder neue Turn weckt die Steuerungs-Bahn der Outbox erneut.
• Ein Ziel-Run entlädt seinen Thread am Ende mit thread/unload. Ein fehlgeschlagenes Entladen wird dort nur protokolliert.

Stop ist eine Leiter mit vier Stufen #

Stop markiert den Run als abgebrochen und arbeitet dann eine Leiter ab. Die Reihenfolge ist für Ziele wichtig: Einem Turn, der unterbrochen wird, während sein Ziel noch active ist, würde sofort ein neuer Turn folgen.

Codex beantwortet turn/interrupt, wenn der Turn angehalten hat, und sendet turn/completed mit dem Status interrupted. Der Leser nimmt diesen Abschluss als Ende des Turns, und der Run endet als abgebrochen. Einen Run, der zwischen turn/start und der Registrierung des Turns abgebrochen wurde, behandelt der Run selbst: Er pausiert das Ziel und gibt den neuen Turn auf, und er wiederholt beides bei Transportfehlern alle 250 ms.

Die Fünf-Sekunden-Regel nach einem Fehler #

Codex meldet ein Problem in einem Turn mit einer error-Benachrichtigung, und das Feld willRetry sagt, ob Codex weitermacht. Der Fehler allein beendet den Turn nie. Der Turn endet mit turn/completed, und der Leser wartet darauf, aber nur 5 Sekunden.

Der Leser wacht alle 100 ms auf, wenn keine Benachrichtigung eintrifft. Er nutzt diesen Takt für Stop-Anfragen und für die Frist, und ein stiller Turn scheitert nie allein wegen der Stille. Den Drain von 75 ms gibt es, weil Codex die letzten Item-Benachrichtigungen kurz nach turn/completed senden kann. Dieselben 5 Sekunden gelten für einen Subagent-Thread: Nach einem Fehler ohne erneuten Versuch zählt sein Thread nach 5 Sekunden nicht mehr als aktiv für den Kindprozess.

turn/completed und ein Fehler ohne erneuten Versuch werden auf einer vollen Turn-Route nie verworfen. Sie warten in einer eigenen Bahn in der Reihenfolge ihres Eintreffens, und gewöhnliche Events für diesen Turn werden verworfen, solange einer wartet.

Geht die Turn-Route verloren, fragt der Desktop nach genau diesem Turn #

Der Leser hat ein Signal für eine verlorene Verbindung: Seine Turn-Route schließt, während kein Fehler gespeichert ist. Der Actor schließt jede Route, wenn er stoppt, zum Beispiel wenn das stdout des Kindprozesses schließt. Der Desktop fragt Codex dann, was aus dem Turn geworden ist, und er fragt nach genau diesem Turn. Ein Turn kann nicht in einen anderen Prozess wechseln. Ein neuer Codex-Kindprozess lädt den Thread aus dem gespeicherten Verlauf und meldet einen Turn, der noch lief, als interrupted. Die Antwort ist nur dann inProgress, wenn der antwortende Kindprozess den Turn noch ausführt.

• Nur eine verlorene Verbindung startet einen Wiedereinstieg. Bei jedem anderen Fehler, der kein Endstatus ist, gibt der Desktop den Turn mit turn/interrupt auf.
• Der Leser wartet bis zu 1 Sekunde darauf, dass der alte Client schließt. Dann least er einen Client für dasselbe Laufzeitpaar, und die Registry startet einen neuen Kindprozess, wenn der alte weg ist.
• Die Zugriffseinstellungen, die der alte Client für den Turn festgehalten hat, gehen auf den neuen Client über, und der Besitzer-Eintrag bekommt die neue pid.
• Hat der Client gewechselt, werden die Beobachter für Subagent-Freigaben und für Agent-Nachrichten gestoppt und am neuen Client neu gestartet.
• Der Wiedereinstieg ist thread/resume mit excludeTurns: false. Der Desktop nimmt den Turn mit der erwarteten ID aus der Antwort. Hat die Antwort keinen solchen Turn, scheitert der Run, und der Desktop gibt den Turn auf.

Bei jeder Antwort gleicht der Desktop zuerst die Zeilen auf dem Bildschirm mit dem Snapshot des Turns ab. So bleibt die Arbeit, die Codex vor dem Verlust gespeichert hat, in der Timeline. In einen Turn wird einmal wieder eingestiegen. Scheitert auch die neue Route, endet der Run mit diesem Fehler. Zwischen zwei Turns eines Ziels hat der Leser keine Route, die er verlieren kann. Dort stellt er die Verbindung stattdessen bei Transportfehlern von thread/goal/get und thread/resume wieder her, höchstens 2-mal in Folge.

Kind-Threads, beobachtete Threads, Rollback #

Ein Codex-Agent kann Subagents starten, und jeder Subagent ist ein eigener Thread unter dem Root-Thread. Kein Run des Desktops besitzt ihre Turns. Der Desktop listet sie auf, speichert, wo ihre Dateien liegen, und folgt einem nur live, solange ein Fenster ihn zeigt.

Ohne Beobachter folgt nichts einem Subagent-Thread. Seine Benachrichtigungen bleiben ohne Route, und der Desktop liest den Thread aus dem Verlauf, wenn Sie ihn öffnen. Eine Freigabe von einem Subagent braucht keine Beobachtung: Der Beobachter des Root-Runs beansprucht sie, wie der Abschnitt zu Freigaben beschreibt.