Die Codex-app-server-Integration

Ein überwachter Kindprozess #

Codex läuft als Kindprozess mit dem Namen codex-app-server. Der Desktop sucht die Binärdatei im Ordner seiner eigenen ausführbaren Datei, dann unter macOS in ../Resources, dann in binaries, src-tauri/binaries und desktop/src-tauri/binaries unter dem aktuellen Verzeichnis. Er akzeptiert die Namen codex-app-server und codex-app-server-<target triple>. Die Binärdatei codex-code-mode-host muss im selben Ordner liegen. Der Desktop weicht nie auf ein Codex aus, das auf dem Rechner installiert ist. Fehlt der Sidecar, scheitert der Start mit einem Fehler, der pnpm -C desktop sync:codex-sidecars nennt.

-c features.local_thread_store_compression=false
-c features.background_paginated_rollout_migration=false
-c features.multi_agent_v2.tool_namespace="hbcode"
--listen stdio://
--session-source app-server
-c sqlite_home=<storage-profile-home>
--allowed-storage-root <storage-profile-home>
--auth-home <execution-profile-home>

Jedes Profil-Home hat eine stabile, undurchsichtige UUID. Der Desktop legt jeden Ordner dieses Pfads selbst an und lehnt einen Symlink in jeder Komponente ab. Der mitgelieferte Kindprozess öffnet keine Datenbank, solange --allowed-storage-root, CODEX_HOME und sqlite_home nicht kanonisch auf dasselbe Verzeichnis zeigen.

Vor jedem Start liest der Desktop die PID-Datei im Profilstamm. Die Datei heißt app-server.pid, wenn Speicherprofil und Ausführungsprofil gleich sind, und app-server-<execution profile>.pid bei einem gemischten Paar. Der Desktop beendet den eingetragenen Prozess nur, wenn er noch ein codex-app-server ist und dieser Desktop ihn nicht gestartet hat. Ein Prozess, den dieser Desktop betreibt, bekommt nie ein Signal. Danach trägt der Desktop die neue Prozess-ID ein und leert stderr in einem eigenen Task.

Der Handshake besteht aus initialize mit Client-Informationen und aktiviertem experimentalApi, danach initialized. Die Antwort auf initialize muss jede der 15 erforderlichen Protokollerweiterungen aufführen, darunter threadItem.createdAtMs, threadItem.commandOutputSource, threadItemsList.path, threadUnload und threadTurn.executionMetadata. Fehlt ein Eintrag, wird der Kindprozess als inkompatibel mit diesem Build beendet, und jeder andere Initialisierungsfehler beendet ihn ebenfalls. Diese Schranke macht eine beliebige Upstream-Binärdatei unbrauchbar.

Die JSON-RPC-Pipe #

{"id":42,"method":"initialize","params":{"capabilities":{"experimentalApi":true},"clientInfo":{"name":"hbcode","version":"<build-version>"}}}

Auch der Kindprozess kann Anfragen senden. Der Desktop beantwortet zwei Arten: einen Tool-Aufruf im Namespace hbcode und die drei Freigabeanfragen. Jede andere Anfrage bekommt den JSON-RPC-Fehler -32601 mit dem Text „HB Code desktop does not handle app-server request“, und ein Tool-Aufruf für einen anderen Namespace ist eine solche Anfrage. Eine Freigabeanfrage, die eintrifft, während initialize wartet, wird abgelehnt. Eine stdout-Zeile, die nicht mit { oder [ beginnt, wird protokolliert und ignoriert. Wenn stdout schließt, enthält der Fehler das Ende von stderr.

Jede Methode, die der Desktop sendet #

Der Codex-Client ist ein fester Satz von 27 Methoden. Der Desktop sendet keine andere Methode an den Kindprozess.

Der Tool-Namespace hbcode #

thread/start enthält dynamicTools, die einen Namespace namens hbcode neben die Shell- und Datei-Tools stellen, die Codex schon hat. Der Kindprozess wird mit features.multi_agent_v2.tool_namespace auf demselben Namen gestartet, deshalb teilen Codex’ eigene Multi-Agent-Tools ihn. Die Liste enthält 4 bis 8 Tools und folgt den Einstellungen in diesem Moment.

thread/start enthält außerdem developerInstructions. agents/session_rules.rs fügt dafür drei Texte in dieser Reihenfolge zusammen: den App-Tool-Text des Katalogs, die Regel für Anweisungen und den Text des Antwortstils. Der Stil Default fügt keinen Text hinzu. Ein normales Senden und ein Ziel-Run verwenden dieselben Anweisungen. Codex liest sie, wenn ein Thread startet. thread/resume sendet sie erneut, und Codex verwendet sie nur, wenn eine Komprimierung den Kontext des fortgesetzten Threads neu aufbaut. Eine Änderung des Antwortstils erreicht daher neue Sessions und eine ältere Session erst nach einer Komprimierung.

Die Freigabeklasse sagt, wer einen Aufruf freigibt, wenn ein Agent seinen Nutzer vor Tool-Aufrufen fragt. Codex führt diese Tools ohne Freigabeanfrage aus. Für Codex wirkt deshalb nur die Klasse desktop: Eine Session-Nachricht, die den Nutzer braucht, wartet in der Warteschlange des Empfängers.

Jede Spezifikation ist mit deferLoading markiert und enthält keine Session-, Run- oder Projektwerte. Der App-Tool-Text ist die Namespace-Beschreibung, die die Tool-Gruppen nennt, und danach „Find the hbcode tool for the task. Follow its instructions. For a video, give a brief. Its tool runs a worker.“ Die Namespace-Beschreibung und der App-Tool-Text bleiben zusammen unter 600 Zeichen. Für jeden item/tool/call schlägt der Desktop den Session-Link des aufrufenden Threads und den aktiven Run dieser Session nach. So erreicht ein fortgesetzter Thread oder ein abgezweigter Subagent den laufenden Run. Ein Aufruf mit einem Tool-Namen, den der Desktop nicht kennt, bekommt ein Ergebnis mit success: false und dem Text „Unsupported HB Code app tool.“ Die JSON-RPC-Antwort selbst ist ein normales Ergebnis.

create_explainer_video startet einen privaten Worker-Thread mit dem Namensraum explainer_video und den Tools save_scenes, render_stills und finish_explainer_video. Der Desktop leitet jeden Aufruf an den Job dieses Threads weiter. Aufrufe in anderen Namensräumen werden abgelehnt. Alle 250 Millisekunden prüft der Desktop, ob der übergeordnete Run noch aktiv ist. Andernfalls stoppt er den Worker, unterbricht den Turn und entlädt den Thread.

Clients pro Profilpaar #

Der Quellenlink speichert eine Thread-ID und den exakten Rollout-Pfad. thread/start liefert nur die ID, deshalb liest der Desktop den absoluten Pfad mit einem separaten thread/read, bevor er den Link veröffentlicht und bevor turn/start folgt. Der Pfad eines Subagent-Threads kommt mit dessen thread/started-Benachrichtigung. Ein Wechsel der Zugangsdaten ändert nie die Unterhaltungsquelle.

Jedes Paar hat seine eigene Startsperre, deshalb wartet ein Paar nie auf den Start eines anderen. Ein zweiter Start für ein Paar, das noch startet, scheitert mit „This Codex subscription is still starting.“ Ein Kindprozess, der außer Dienst geht, schließt seine Schranke für die Turn-Zulassung, und ein turn/start, das auf ihm vorbereitet wurde, scheitert vor der Zulassung.

Nach jedem Chat-Run entlädt der Desktop den Thread mit thread/unload. Ein fehlgeschlagenes Entladen oder ein Subagent-Pfad, der nicht gespeichert werden konnte, nimmt diesen Kindprozess außer Dienst, denn die Prozessgrenze ist der einzige Beweis, dass der JSONL-Writer fort ist. Auch ein Ziel-Run entlädt seinen Thread, dort wird ein fehlgeschlagenes Entladen aber nur protokolliert. Bevor sich der Quellenlink eines Threads ändert, wird außerdem jede untätige Kopie auf jedem laufenden Kindprozess entladen.

Profile und Anmeldung #

Ein Telefon liest die Codex-Profile mit system.codexAuthProfiles und wechselt mit system.activateCodexAuthProfile. Der Wechsel ist eine ändernde Methode und braucht deshalb einen Idempotenzschlüssel. Die Antwort ist die neue Profilliste.

Nutzungslimits #

Die Codex-Limits kommen von account/rateLimits/read auf dem Kindprozess des aktiven Profils. Der Desktop liest rateLimitsByLimitId.codex oder rateLimits, wenn dieser Eintrag fehlt. Er behält das primäre und das sekundäre Fenster (usedPercent, Fensterminuten, resetsAt), das Guthaben und den Tarif. Ein Telefon bekommt dieselben Werte mit system.codexUsageLimits.

Anfragen außerhalb eines Runs #

Session-Titel und Textverbesserung nutzen eine One-Shot-Textanfrage. Der Desktop startet einen flüchtigen Thread ohne Tools, mit permissions :read-only und der Freigaberichtlinie never. Er startet einen Turn, wartet höchstens 120 Sekunden auf den Text und entlädt den Thread. Nach einem Timeout oder einem Fehler gibt er zuerst den Turn auf. Eine leere Antwort ist ein Fehler.

Der Modellkatalog kommt von model/list mit includeHidden false. Der Desktop speichert ihn 300 Sekunden pro Speicherprofil zwischen und leert den Cache, wenn ein Profil gelöscht wird. Ein Senden liest den Katalog und prüft das gewählte Modell und den Aufwand dagegen, bevor der Turn zugelassen wird.

Die Liste bestehender Codex-Sessions kommt von thread/list auf dem Kindprozess des aktiven Profils. Der Desktop öffnet dafür nie die Codex-State-Datenbank und durchsucht nie Rollout-Dateien.

Der mitgelieferte Sidecar #

tauri:dev führt zuerst sync:codex-sidecars aus, der Kindprozess wird also aus dem eingebetteten Quellcode gebaut. Rechnen Sie mit einem Rust-Build und dem Netzwerkzugriff, den desktop/BUILD.md beschreibt.

Der Sync ist eine Aktualitätsschranke. Er scheitert, wenn desktop/vendor/codex/upstream-revision nicht dem main entspricht, den das letzte reconcile:codex-source in den lokalen Spiegel geholt hat. Die akzeptierte Revision ist damit so aktuell wie dieser Abruf. Die 309 Override-Dateien unter desktop/vendor/codex/source implementieren die Protokollerweiterungen und die Speichergrenze, auf die sich der Desktop verlässt. Deshalb scheitert eine fremde Upstream-Binärdatei an der initialize-Schranke. Behalten Sie den Protokolltransport als Verlaufsgrenze bei und fügen Sie keinen weiteren Transkript-Parser hinzu.

pnpm -C desktop sync:codex-sidecars:verify