Skip to content

Commit 82311ba

Browse files
committed
docs(test): reflect comment-line keep-alive and responses backend
Keep-alives are now SSE comment lines (': opencodex heartbeat') instead of response.heartbeat events, so the bridge-lifecycle RC3 test and the transport architecture docs no longer describe a parser-ignored response.heartbeat event. The grok-build guides' api_backend examples were still chat_completions; they now match the Responses backend the proxy emits.
1 parent 5a75e57 commit 82311ba

18 files changed

Lines changed: 70 additions & 85 deletions

File tree

‎docs-site/src/content/docs/fr/guides/grok-build.md‎

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ en `~/.grok/config.toml` :
1818
[model.ocx-gpt-5-6-sol]
1919
model = "gpt-5.6-sol"
2020
base_url = "http://127.0.0.1:10100/v1"
21-
api_backend = "chat_completions"
21+
api_backend = "responses"
2222
api_key = "opencodex-loopback"
2323
name = "OCX gpt-5.6-sol"
2424
# ... one [model.ocx-*] table per visible model ...
@@ -104,7 +104,7 @@ tables par modèle avec **champs directs**, en dehors des marqueurs `# >>> openc
104104
[model.ocx-opus]
105105
model = "anthropic/claude-opus-4-8"
106106
base_url = "http://127.0.0.1:10100/v1"
107-
api_backend = "chat_completions"
107+
api_backend = "responses"
108108
api_key = "opencodex-loopback"
109109
```
110110

@@ -115,7 +115,7 @@ composez et utilisez votre jeton d'entrée :
115115
[model.ocx-opus]
116116
model = "anthropic/claude-opus-4-8"
117117
base_url = "http://192.168.1.10:10100/v1" # the reachable host, not 127.0.0.1
118-
api_backend = "chat_completions"
118+
api_backend = "responses"
119119
api_key = "your-OPENCODEX_API_AUTH_TOKEN"
120120
```
121121

@@ -129,11 +129,6 @@ l'identifiant `grok-4.5`. Les alias générés évitent entièrement les points
129129

130130
## Limitations connues
131131

132-
- **Réponses backend et keep-alives:** opencodex émet un `response.heartbeat` keep-alive
133-
dans les flux `/v1/responses` pendant les périodes de silence en amont. Le décodeur Responses de Grok Build
134-
rejette les types d'événements inconnus, donc un modèle `api_backend = "responses"` configuré manuellement
135-
peut échouer à mi-tour sur des amonts lents. Le code PIN des entrées enregistrées automatiquement
136-
`api_backend = "chat_completions"`, qui ne fait jamais apparaître les images de battements de cœur bruts.
137132
- **Installé par le service `ocx restart` :** le proxy en cours d'exécution possède l'autorisation de redémarrage et la vidange
138133
coordination, tandis que le gestionnaire de service installé lance le remplacement après l'ancien processus
139134
sorties. La supervision du service reste installée. Lors de l'enregistrement automatique en boucle, le bloc géré

‎docs-site/src/content/docs/fr/reference/architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ Trois anciens points d’entrée volumineux préservent désormais la compatibil
7373
| `done` | `response.completed` (avec l’utilisation) |
7474
| `error` | `response.failed` (avec `last_error`) |
7575

76-
Le pont émet également un **signal de maintien en vie** (RC3) : lorsque le service en amont reste silencieux, il envoie toutes les 2 secondes un événement SSE `response.heartbeat`, ignoré par l’analyseur, afin de réarmer la minuterie d’inactivité de Codex. Le **délai maximal de blocage** est de 300 secondes par défaut (`stallTimeoutSec`). Une fois ce délai atteint, le service en amont est interrompu et `response.incomplete` est émis avec le motif `upstream_stall_timeout`, ce qui empêche une connexion bloquée d’immobiliser Codex indéfiniment.
76+
Le pont émet également un **signal de maintien en vie** (RC3) : lorsque le service en amont reste silencieux, il envoie toutes les 2 secondes une ligne de commentaire SSE (`: opencodex heartbeat`), ignorée par l’analyseur, afin de réarmer la minuterie d’inactivité de Codex. Une ligne de commentaire est ignorée par tous les analyseurs eventsource sans produire d’événement, donc les décodeurs Responses stricts ne voient jamais de variante inconnue. Le **délai maximal de blocage** est de 300 secondes par défaut (`stallTimeoutSec`). Une fois ce délai atteint, le service en amont est interrompu et `response.incomplete` est émis avec le motif `upstream_stall_timeout`, ce qui empêche une connexion bloquée d’immobiliser Codex indéfiniment.
7777

7878
Les appels d’outils sont répartis entre trois types d’éléments Responses à l’aide de la table des espaces de noms, de l’ensemble des outils libres et de l’ensemble des outils de recherche capturés par l’analyseur. Les espaces de noms MCP, les outils libres tels que `apply_patch` et les appels `tool_search` exécutés par le client peuvent ainsi effectuer un aller-retour complet. Une variante `buildResponseJSON()` produit à partir des mêmes événements un objet de réponse unique hors flux.
7979

‎docs-site/src/content/docs/guides/grok-build.md‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ per-model tables with **direct fields**, outside the `# >>> opencodex managed bl
104104
[model.ocx-opus]
105105
model = "anthropic/claude-opus-4-8"
106106
base_url = "http://127.0.0.1:10100/v1"
107-
api_backend = "chat_completions"
107+
api_backend = "responses"
108108
api_key = "opencodex-loopback"
109109
```
110110

@@ -115,7 +115,7 @@ dial and use your admission token:
115115
[model.ocx-opus]
116116
model = "anthropic/claude-opus-4-8"
117117
base_url = "http://192.168.1.10:10100/v1" # the reachable host, not 127.0.0.1
118-
api_backend = "chat_completions"
118+
api_backend = "responses"
119119
api_key = "your-OPENCODEX_API_AUTH_TOKEN"
120120
```
121121

@@ -129,11 +129,6 @@ the id `grok-4.5`. Generated aliases avoid dots entirely for this reason.
129129

130130
## Known limitations
131131

132-
- **Responses backend and keep-alives:** opencodex emits a `response.heartbeat` keep-alive
133-
on `/v1/responses` streams during upstream silence. Grok Build's Responses decoder
134-
rejects unknown event types, so a manually configured `api_backend = "responses"` model
135-
can fail mid-turn on slow upstreams. The auto-registered entries pin
136-
`api_backend = "chat_completions"`, which never surfaces raw heartbeat frames.
137132
- **Service-installed `ocx restart`:** the running proxy owns restart authorization and drain
138133
coordination, while the installed service manager launches the replacement after the old process
139134
exits. Service supervision remains installed. On loopback auto-registration, the managed block

‎docs-site/src/content/docs/ja/guides/grok-build.md‎

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ opencodex はローカル ポート上で OpenAI 互換の `POST /v1/chat/comple
1414
[model.ocx-gpt-5-6-sol]
1515
model = "gpt-5.6-sol"
1616
base_url = "http://127.0.0.1:10100/v1"
17-
api_backend = "chat_completions"
17+
api_backend = "responses"
1818
api_key = "opencodex-loopback"
1919
name = "OCX gpt-5.6-sol"
2020
# ... one [model.ocx-*] table per visible model ...
@@ -56,7 +56,7 @@ Grok Build では、ループバックでもカスタム モデルに対して
5656
[model.ocx-opus]
5757
model = "anthropic/claude-opus-4-8"
5858
base_url = "http://127.0.0.1:10100/v1"
59-
api_backend = "chat_completions"
59+
api_backend = "responses"
6060
api_key = "opencodex-loopback"
6161
```
6262

@@ -66,7 +66,7 @@ api_key = "opencodex-loopback"
6666
[model.ocx-opus]
6767
model = "anthropic/claude-opus-4-8"
6868
base_url = "http://192.168.1.10:10100/v1" # the reachable host, not 127.0.0.1
69-
api_backend = "chat_completions"
69+
api_backend = "responses"
7070
api_key = "your-OPENCODEX_API_AUTH_TOKEN"
7171
```
7272

@@ -76,8 +76,6 @@ api_key = "your-OPENCODEX_API_AUTH_TOKEN"
7676

7777
## 既知の制限事項
7878

79-
- **バックエンドとキープアライブの応答:** opencodex は `response.heartbeat` キープアライブを発行します
80-
アップストリーム沈黙中の `/v1/responses` ストリーム。 Grok Build の Responses デコーダは未知のイベント タイプを拒否するため、手動で構成された `api_backend = "responses"` モデルは低速なアップストリームではターン中に失敗する可能性があります。自動登録されたエントリは `api_backend = "chat_completions"` をピン留めしますが、生のハートビート フレームが表示されることはありません。
8179
- **サービスでインストールされた `ocx restart`:** 実行中のプロキシが再起動の認可とドレインの調整を担当し、古いプロセスの終了後はインストール済みのサービス マネージャーが置換プロセスを起動します。サービス監視は維持されます。ループバックの自動登録を使用している場合に限り、マネージド ブロックもハンドオフ中に維持されます。非ループバック構成では Grok 設定を手動管理します。同じポートで、別の ID 検証済みプロセスが正常になったことを確認した場合にのみ成功します。
8280
- **構成読み取りタイミング:** 最初に opencodex を起動し、その後 `grok` を起動します。
8381
予測可能な結果。 Grok Build は `~/.grok/config.toml` を監視し、`[model]` テーブルが実際に変更されると (内容で比較すると約 1 秒のデバウンス) 再ロードするため、更新されたブロックは再起動せずに開いているセッションに到達します。 Grok が解析した内容を確認するには、`grok inspect` を実行します。ロードされた設定ソースがリストされ、拒否されたフィールドについて警告が表示されます。解決されたモデルのリストは出力されません。単一の TOML エラーがユーザー設定レイヤー「全体」を無効にすることに注意してください。これが、opencodex がファイルをアトミックに書き込む理由です。Grok は書きかけの設定を決して認識しません。

‎docs-site/src/content/docs/ja/reference/architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ HTTP の境界は `server/index.ts` が担い、Responses データプレーン
8989
| `done` | `response.completed`(usage 付き) |
9090
| `error` | `response.failed`(`last_error` 付き) |
9191

92-
ブリッジは **ハートビートキープアライブ**(RC3)も実行します。上流からデータが来ないとき 2 秒ごとにパーサーが無視する `response.heartbeat` SSE イベントを送り、Codex のアイドルタイマーを再開します。デフォルトの **stall deadline** は 300 秒(`stallTimeoutSec`)です。この時間を超えると上流を中断し、理由が `upstream_stall_timeout` の `response.incomplete` を送り、接続が延々とぶら下がらないようにします。
92+
ブリッジは **ハートビートキープアライブ**(RC3)も実行します。上流からデータが来ないとき 2 秒ごとにパーサーが無視する `: opencodex heartbeat` SSE コメント行を送り、Codex のアイドルタイマーを再開します。コメント行はイベントを生成せずに任意の eventsource パーサーに破棄されるため、厳格な Responses デコーダは未知のバリアントを決して見ません。デフォルトの **stall deadline** は 300 秒(`stallTimeoutSec`)です。この時間を超えると上流を中断し、理由が `upstream_stall_timeout` の `response.incomplete` を送り、接続が延々とぶら下がらないようにします。
9393

9494
ツール呼び出しはパーサーが取得した名前空間マップ、freeform 集合、tool-search 集合を使って 3 種類の Responses 項目タイプに振り分けます — そのため MCP 名前空間、`apply_patch` スタイルの freeform ツール、クライアントが実行する `tool_search` がすべてラウンドトリップします。`buildResponseJSON()` 変種は同じイベントから単一の非ストリーミングレスポンスオブジェクトを生成します。
9595

‎docs-site/src/content/docs/ko/guides/grok-build.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ opencodex는 로컬 포트에서 OpenAI 호환 `POST /v1/chat/completions`(및 `
1414
[model.ocx-gpt-5-6-sol]
1515
model = "gpt-5.6-sol"
1616
base_url = "http://127.0.0.1:10100/v1"
17-
api_backend = "chat_completions"
17+
api_backend = "responses"
1818
api_key = "opencodex-loopback"
1919
name = "OCX gpt-5.6-sol"
2020
# ... one [model.ocx-*] table per visible model ...
@@ -52,7 +52,7 @@ Grok Build는 루프백에서도 사용자 정의 모델에 비어 있지 않은
5252
[model.ocx-opus]
5353
model = "anthropic/claude-opus-4-8"
5454
base_url = "http://127.0.0.1:10100/v1"
55-
api_backend = "chat_completions"
55+
api_backend = "responses"
5656
api_key = "opencodex-loopback"
5757
```
5858

@@ -62,7 +62,7 @@ api_key = "opencodex-loopback"
6262
[model.ocx-opus]
6363
model = "anthropic/claude-opus-4-8"
6464
base_url = "http://192.168.1.10:10100/v1" # the reachable host, not 127.0.0.1
65-
api_backend = "chat_completions"
65+
api_backend = "responses"
6666
api_key = "your-OPENCODEX_API_AUTH_TOKEN"
6767
```
6868

@@ -72,7 +72,6 @@ api_key = "your-OPENCODEX_API_AUTH_TOKEN"
7272

7373
## 알려진 제한
7474

75-
- **Responses 백엔드와 keep-alive:** 상위 업스트림이 조용한 동안 opencodex는 `/v1/responses` 스트림에 `response.heartbeat` keep-alive를 보냅니다. Grok Build의 Responses 디코더는 알 수 없는 이벤트 타입을 거부하므로, 수동으로 설정한 `api_backend = "responses"` 모델은 느린 업스트림에서 턴 도중 실패할 수 있습니다. 자동 등록된 항목은 `api_backend = "chat_completions"`로 고정되며, 원시 heartbeat 프레임을 노출하지 않습니다.
7675
- **서비스 설치된 `ocx restart`:** 실행 중인 프록시는 재시작 권한 확인과 드레인 조정을 담당하고, 기존 프로세스가 종료된 뒤 설치된 서비스 관리자가 교체 프로세스를 시작합니다. 서비스 감독은 그대로 유지됩니다. 루프백 자동 등록을 사용하는 경우에만 관리 블록도 핸드오프 동안 유지되며, 비루프백 배포에서는 Grok 설정을 수동으로 관리합니다. 같은 포트에서 신원이 확인된 다른 프로세스가 정상 상태가 된 뒤에만 명령이 성공합니다.
7776
- **설정 읽기 시점:** 가장 예측 가능한 결과를 얻으려면 opencodex를 먼저 시작하고 그다음 `grok`를 실행합니다. Grok Build는 `~/.grok/config.toml`을 감시하다가 `[model]` 테이블이 실제로 바뀔 때 다시 불러옵니다(내용을 기준으로 비교하는 약 1초 디바운스). 그래서 새로 고친 블록은 재시작 없이 열린 세션에도 들어갑니다. Grok가 무엇을 파싱했는지 확인하려면 `grok inspect`를 실행합니다. 이 명령은 로드한 설정 원본을 나열하고 거부한 필드가 있으면 경고합니다. 해석된 모델 목록은 출력하지 않습니다. TOML 오류 하나만으로도 사용자 설정 레이어 전체가 무효가 되므로, opencodex가 파일을 원자적으로 쓰는 이유도 여기에 있습니다. Grok는 절반만 써진 설정을 보지 않습니다.
7877
- **카탈로그 업데이트:** 펜스 블록은 주입 시점의 카탈로그를 반영합니다. 공급자나 모델을 추가한 뒤에는 `ocx ensure`를 실행하거나 프록시를 재시작해 갱신합니다.

‎docs-site/src/content/docs/ko/reference/architecture.md‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -101,9 +101,11 @@ HTTP 경계는 `server/index.ts`가 맡고, Responses 데이터 플레인은 `se
101101
| `error` | `response.failed` (with `last_error`) |
102102

103103
브리지는 **하트비트 킵얼라이브**(RC3)도 실행합니다. 업스트림에서 데이터가 오지 않을 때 2초마다
104-
파서가 무시하는 `response.heartbeat` SSE 이벤트를 보내 Codex의 유휴 타이머를 다시 시작합니다.
105-
기본 **stall deadline**은 300초(`stallTimeoutSec`)입니다. 이 시간을 넘기면 업스트림을 중단하고
106-
이유가 `upstream_stall_timeout`인 `response.incomplete`를 내보내 연결이 끝없이 매달리지 않게 합니다.
104+
파서가 무시하는 `: opencodex heartbeat` SSE 주석 줄을 보내 Codex의 유휴 타이머를 다시 시작합니다.
105+
주석 줄은 이벤트를 생성하지 않고 모든 eventsource 파서에 의해 버려지므로, 엄격한 Responses 디코더는
106+
알 수 없는 variant를 절대 보지 못합니다. 기본 **stall deadline**은 300초(`stallTimeoutSec`)입니다.
107+
이 시간을 넘기면 업스트림을 중단하고 이유가 `upstream_stall_timeout`인 `response.incomplete`를
108+
내보내 연결이 끝없이 매달리지 않게 합니다.
107109

108110
툴 호출은 파서가 캡처한 네임스페이스 맵, freeform 집합, tool-search 집합을 사용하여 세 가지
109111
Responses 항목 타입으로 구분됩니다 — 따라서 MCP 네임스페이스, `apply_patch` 스타일의 freeform

‎docs-site/src/content/docs/reference/architecture.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -103,11 +103,12 @@ understands:
103103
| `done` | `response.completed` (with usage) |
104104
| `error` | `response.failed` (with `last_error`) |
105105

106-
The bridge also runs a **heartbeat keep-alive** (RC3): during upstream silence, it emits a
107-
parser-ignored `response.heartbeat` SSE event every 2 seconds to re-arm Codex's idle timer. The
108-
default **stall deadline** is 300 seconds (`stallTimeoutSec`); reaching it aborts the upstream and emits
109-
`response.incomplete` with reason `upstream_stall_timeout`, preventing a hung connection from blocking
110-
Codex indefinitely.
106+
The bridge also runs a **heartbeat keep-alive** (RC3): during upstream silence, it emits an SSE
107+
comment line (`: opencodex heartbeat`) every 2 seconds to re-arm Codex's idle timer. Comment lines
108+
are discarded by every eventsource parser without producing an event, so strict Responses decoders
109+
never see an unknown variant. The default **stall deadline** is 300 seconds (`stallTimeoutSec`);
110+
reaching it aborts the upstream and emits `response.incomplete` with reason
111+
`upstream_stall_timeout`, preventing a hung connection from blocking Codex indefinitely.
111112

112113
Tool calls are disambiguated into three Responses item types using the namespace map, the freeform
113114
set, and the tool-search set captured by the parser — so MCP namespaces, `apply_patch`-style freeform

‎docs-site/src/content/docs/ru/guides/grok-build.md‎

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ Grok Build — вручную редактировать конфигураци
1818
[model.ocx-gpt-5-6-sol]
1919
model = "gpt-5.6-sol"
2020
base_url = "http://127.0.0.1:10100/v1"
21-
api_backend = "chat_completions"
21+
api_backend = "responses"
2222
api_key = "opencodex-loopback"
2323
name = "OCX gpt-5.6-sol"
2424
# ... one [model.ocx-*] table per visible model ...
@@ -83,7 +83,7 @@ admission token, а управляемый блок не может безопа
8383
[model.ocx-opus]
8484
model = "anthropic/claude-opus-4-8"
8585
base_url = "http://127.0.0.1:10100/v1"
86-
api_backend = "chat_completions"
86+
api_backend = "responses"
8787
api_key = "opencodex-loopback"
8888
```
8989

@@ -94,7 +94,7 @@ api_key = "opencodex-loopback"
9494
[model.ocx-opus]
9595
model = "anthropic/claude-opus-4-8"
9696
base_url = "http://192.168.1.10:10100/v1" # the reachable host, not 127.0.0.1
97-
api_backend = "chat_completions"
97+
api_backend = "responses"
9898
api_key = "your-OPENCODEX_API_AUTH_TOKEN"
9999
```
100100

@@ -107,12 +107,6 @@ api_key = "your-OPENCODEX_API_AUTH_TOKEN"
107107

108108
## Известные ограничения
109109

110-
- **Responses backend и keep-alive:** во время тишины upstream opencodex посылает keep-alive
111-
`response.heartbeat` в потоках `/v1/responses`. Декодер Responses в Grok Build отвергает
112-
неизвестные типы событий, поэтому вручную настроенная модель с
113-
`api_backend = "responses"` может оборваться посреди хода на медленных upstream. Автоматически
114-
зарегистрированные записи жёстко используют `api_backend = "chat_completions"`, где сырые
115-
heartbeat-кадры никогда не видны.
116110
- **`ocx restart` при установленной службе:** работающий прокси сам управляет drain и заменой,
117111
поэтому supervision службы и managed block сохраняются. Команда завершается успешно только после
118112
того, как на том же порту станет здоровым другой процесс с проверенной идентичностью.

0 commit comments

Comments
 (0)