lukas/nixos-config
Archived
1
0
Fork 1
Code Issues Pull requests Releases Wiki Activity
This repository has been archived on 2026-09-17. You can view files and clone it, but you cannot make any changes to its state, such as pushing and creating new issues, pull requests or comments.
nixos-config/docs/intent/board-usage-endpoint-codex.md
pijukka 41e05ed43f board: automatic escalation ladder for limit_reached Builder retries 
The Operator's ===OPERATOR-DECISION=== schema gains an optional
"escalation" field (<=2 steps of model/reasoning_effort/iteration_limit,
validated against a new per-runtime orchestration.MODEL_POOL allowlist):
per-parent for direct_builder, per-child for split. On limit_reached,
completion_watcher.py now walks this ladder (via the shared
fanout.escalation_ladder_for()) instead of a single flat identical-params
retry, escalating model/iteration_limit before falling back to today's
manual repair/Aufteilen-angefordert checkpoints. A card that never went
through the Operator keeps its existing flat single-retry behavior
unchanged. orchestration.child_failed(), fanout.child_terminal(), and
trigger.py's Aufteilen-angefordert guard all switch from the old hardcoded
">= 1" threshold to the card's actual ladder length. board.html surfaces
the current attempt count on affected cards.

Also includes the board-session-usage-indicator research writeup (Codex
app-server JSON-RPC + Claude /api/oauth/usage as the two non-interactive
usage sources) and its Operator-produced child intents, plus the
operator_klaerung_noetig phase-visibility fix already staged in this
checkout (distinct phase for a needs_human/crashed Operator run that never
produced children, instead of reusing "durch_kinder_blockiert").

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SyeDivnWm6hgiNd3YKjK7Z
2026-09-10 13:58:52 +02:00

3.6 KiB
Raw Permalink Blame History

Intent: Codex-Nutzungsquelle im Board-Usage-Endpunkt

Ziel

Die in der Vorkarte board-usage-endpoint-claude bereits vorgesehene, aber leere Codex-Seite von GET /api/board/usage mit echten Werten befüllen: verbrauchte Prozent im 5-Stunden- und im Wochenfenster der geteilten interaktiven drone-Codex-Identität.

Umfang

  • In hosts/blunix/localServices/board-agent/trigger.py:
    • codex app-server als kurzlebigen Kindprozess starten und über dessen Stdio-JSON-RPC-Protokoll zuerst initialize, danach account/rateLimits/read senden.
    • Aus der Antwort rateLimits.primary.usedPercent (5-Stunden-Fenster) und rateLimits.secondary.usedPercent (Wochenfenster) sowie die jeweiligen resetsAt-Zeitstempel auslesen und in die bestehenden codex-Felder der Antwort schreiben. Der Antwortvertrag der Vorkarte bleibt unverändert.
    • Kurzes Timeout (wenige Sekunden) und garantiertes Aufräumen des Kindprozesses (auch bei Timeout) sicherstellen.
    • Vollständige Fehlerisolierung: jeder Fehler führt nur zu null auf der Codex-Seite; die Claude-Seite bleibt unabhängig nutzbar.
  • In hosts/blunix/localServices/board-agent.nix:
    • Ein eigenes, dauerhaftes und beschreibbares Probe-CODEX_HOME unterhalb des bestehenden stateDir (/var/lib/board-agent) definieren und dem Trigger-Service über eine Umgebungsvariable bekannt machen. Es ist bewusst getrennt vom bestehenden codexHome der isolierten Builder-Identität.
    • ProtectHome = "read-only" bleibt unverändert; es wird kein Sandbox-Downgrade vorgenommen.
  • auth.json wird vor jeder Abfrage frisch aus /home/drone/.codex/auth.json in das Probe-CODEX_HOME kopiert (nicht nur einmalig beim Servicestart wie beim bestehenden prepareCodexHome-Muster), damit ein rotiertes Token ohne Neustart des dauerhaft laufenden Dienstes wirksam wird.
  • Tests in test_board_agent.py mit gefälschtem Subprozess: Erfolgsfall, fehlendes Binary, Timeout, kaputte/unerwartete RPC-Antwort, frisches Kopieren von auth.json.
  • Kurze Ergänzung in README.md zum Probe-CODEX_HOME und zur Codex-Quelle.

Explizit ausgeschlossen

  • Keine Änderung am Antwortvertrag oder an der Claude-Seite des Endpunkts.
  • Keine UI-Änderung in board.html (eigene Folgekarte).
  • Kein dauerhaft laufender codex app-server-Dienst; pro Abfrage ein kurzlebiger Kindprozess.
  • Kein Abschwächen von ProtectHome oder anderer Sandbox-Optionen.
  • Kein Verlauf/Graph, keine Alarmierung, keine Aufschlüsselung pro Rolle.

Annahmen

  • codex app-server beantwortet account/rateLimits/read nach einem initialize-Handshake nicht-interaktiv und in deutlich unter einer Sekunde; eine laufende Instanz ist nicht nötig.
  • codex app-server schreibt beim Start breit in sein CODEX_HOME (SQLite-Dateien, Caches), weshalb ein eigenes beschreibbares Probe-Verzeichnis nötig ist.
  • Die Kopierkosten von auth.json (wenige KB) sind bei einem Poll-Intervall von rund 60 Sekunden vernachlässigbar.

Offene Risiken

  • codex app-server ist als "[experimental]" markiert; Methodenname und Antwortstruktur können sich ändern. Die Fehlerisolierung ist deshalb verpflichtend.
  • Der Kindprozess darf bei Fehlern nicht als Zombie zurückbleiben oder den Request blockieren.

Erfolgskriterien

  • GET /api/board/usage liefert echte Codex-Prozentwerte, bei Fehlern eine Leerdarstellung, und die Claude-Seite bleibt davon unberührt.
  • Nix-Auswertung der geänderten board-agent.nix und der Testlauf von test_board_agent.py sind fehlerfrei.
  • Keine Secrets oder Rohdaten verlassen den Endpunkt.