Skip to content

Commit b2c2054

Browse files
committed
fix(web-search): close xai executor review blockers
Attach abort-driven body cancellation immediately after the xAI fetch, cancel oversized SSE readers upstream, and cover transport release. Stage and validate complete web-search management candidates before commit; reject malformed xSearch types without partial mutation or broadened searches. Document the live Grok OAuth/x_search backend across canonical docs, locales, type comments, and structure sources. Evidence: 47 focused tests pass; bun x tsc --noEmit; docs Astro build 393 pages.
1 parent 0f2d670 commit b2c2054

24 files changed

Lines changed: 232 additions & 95 deletions

File tree

‎docs-site/src/content/docs/fr/guides/sidecars.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@ description: Dotez les modèles routés d’une véritable recherche web et donn
55

66
Tous les modèles routés ne proposent pas une **recherche web** hébergée ni une **entrée d’image** native. opencodex complète
77
ces capacités au moyen de deux services auxiliaires. Chacun peut s’appuyer sur un fournisseur connecté à ChatGPT (`forward`) ou sur un
8-
fournisseur Anthropic OAuth enregistré. Les erreurs des services auxiliaires sont converties en résultats d’outil limités ou en marqueurs d’image,
8+
fournisseur Anthropic OAuth enregistré ; la recherche web peut aussi utiliser un OAuth Grok enregistré via le moteur `xai` explicite. Les erreurs des services auxiliaires sont converties en résultats d’outil limités ou en marqueurs d’image,
99
au lieu de faire échouer l’intégralité du tour.
1010

1111
:::note[Sélection automatique du moteur]
12-
Une valeur `backend` explicite est prioritaire. Lorsqu'elle est omise, opencodex utilise `anthropic` si un fournisseur OAuth Anthropic actif
13-
possède un compte actif qui n'est pas marqué `needsReauth` ; sinon, il utilise `openai`. Une sélection explicite de
14-
`anthropic` sans ces identifiants échoue de manière sûre. `openai` exige à la fois une connexion ChatGPT et un
12+
Une valeur `backend` explicite est prioritaire. Sans valeur, la recherche web utilise toujours `openai` ; Vision utilise
13+
`anthropic` si un compte OAuth Anthropic utilisable existe, sinon `openai`. Une sélection explicite de
14+
`anthropic` ou `xai` sans identifiants utilisables échoue sans repli. `openai` exige à la fois une connexion ChatGPT et un
1515
fournisseur `forward` actif.
1616
:::
1717

@@ -24,7 +24,8 @@ Lorsque Codex demande un hébergement `web_search` pour un modèle routé sans p
2424
2. Exécute le modèle routé dans une petite **boucle d'agent**. Lorsqu'il appelle `web_search`, opencodex utilise le
2525
moteur du service auxiliaire sélectionné : OpenAI exécute l'outil hébergé `web_search` avec `gpt-5.6-luna` par défaut ;
2626
Anthropic exécute `web_search_20250305` avec `claude-sonnet-5` par défaut. La réponse en streaming et
27-
les citations deviennent le résultat d’un outil.
27+
les citations deviennent le résultat d’un outil. xAI exécute `web_search` avec `grok-4.6` par défaut et ajoute
28+
`x_search` à la même requête lorsque `xSearch.enabled` vaut true.
2829
3. **Répète la boucle** jusqu'à ce que le modèle réponde ou que le nombre total de recherches réelles atteigne `maxSearchesPerTurn`
2930
(par défaut 3), supprime ensuite l'outil de recherche et force une réponse finale. De vrais outils clients tels que
3031
`apply_patch` ou le shell mettent fin au tour afin que ces appels parviennent à Codex.

‎docs-site/src/content/docs/fr/reference/configuration/server.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -209,8 +209,9 @@ l'API Images d'OpenAI et la forme de réponse attendue par Codex.
209209
| Champ | Type | Par défaut | Signification |
210210
| --- | --- | --- | --- |
211211
| `enabled?` | `boolean` | activé lorsqu'il est utilisable | Interrupteur principal. |
212-
| `backend?` | `"openai" \| "anthropic"` | automatique | Une valeur explicite est prioritaire ; sinon, la présence d'identifiants OAuth Anthropic stockés et utilisables sélectionne `anthropic`, puis `openai`. |
213-
| `model?` | `string` | dépendant du backend | `gpt-5.6-luna` pour OpenAI ou `claude-sonnet-5` pour Anthropic. L'héritage explicite `gpt-5.4-mini` migre au démarrage. |
212+
| `backend?` | `"openai" \| "anthropic" \| "xai" \| "gemini" \| "exa"` | `openai` | Une valeur explicite est prioritaire ; l'absence de valeur sélectionne toujours `openai`. `anthropic` et `xai` ne s'exécutent que s'ils sont configurés explicitement ; `gemini` et `exa` restent réservés jusqu'à la livraison de leur executor. |
213+
| `model?` | `string` | dépendant du backend | `gpt-5.6-luna` pour OpenAI, `claude-sonnet-5` pour Anthropic ou `grok-4.6` pour xAI. L'héritage explicite `gpt-5.4-mini` migre au démarrage. |
214+
| `xSearch?` | `object` | omis | Activation facultative de `x_search` hébergé, propre à xAI : `enabled`, tableaux mutuellement exclusifs `allowedXHandles` / `excludedXHandles` (20 au maximum), et dates ISO `fromDate` / `toDate` (`YYYY-MM-DD`). |
214215
| `reasoning?` | `string` | `low` | Effort secondaire. `minimal` est rejeté lors de la recherche sur le Web. |
215216
| `maxSearchesPerTurn?` | `number` | `3` | Recherches réelles autorisées par tour de modèle principal. |
216217
| `routedModelStallTimeoutMs?` | `number` | `200000` | Date limite d'inactivité du corps brut du modèle routé uniquement pour les fichiers de configuration. Entier 1–2147483647 ; chaque morceau non vide le réinitialise. |

‎docs-site/src/content/docs/guides/sidecars.md‎

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,18 @@ description: Give routed models real web search and text-only models image under
44
---
55

66
Routed models do not all expose hosted **web search** or native **image input**. opencodex backfills
7-
those capabilities with two sidecars. Each can run through a ChatGPT-login (`forward`) provider or a
8-
stored Anthropic OAuth provider. Sidecar errors become bounded tool results or image markers instead
9-
of failing the whole turn.
7+
those capabilities with two sidecars. Both support a ChatGPT-login (`forward`) provider or stored
8+
Anthropic OAuth provider; web search can additionally use stored Grok OAuth through the explicit
9+
`xai` backend. Sidecar errors become bounded tool results or image markers instead of failing the
10+
whole turn.
1011

1112
:::note[Automatic backend selection]
1213
Explicit `backend` config wins. The two sidecars default differently when `backend` is unset:
1314
**web search** always defaults to `openai` — `anthropic` runs only when explicitly configured.
1415
**Vision** defaults to `anthropic` if an enabled Anthropic OAuth provider has an active account not
1516
marked `needsReauth`, otherwise `openai`. Explicit `anthropic` without that credential fails
16-
closed. `openai` requires both ChatGPT login auth and an enabled `forward` provider.
17+
closed. Explicit `xai` requires a usable stored Grok OAuth account and does not fall back. `openai`
18+
requires both ChatGPT login auth and an enabled `forward` provider.
1719
:::
1820

1921
## Web-search sidecar
@@ -25,7 +27,8 @@ When Codex requests hosted `web_search` for a non-passthrough routed model, open
2527
2. Runs the routed model in a small **agentic loop**. When it calls `web_search`, opencodex uses the
2628
selected sidecar backend: OpenAI runs hosted `web_search` with `gpt-5.6-luna` by default;
2729
Anthropic runs `web_search_20250305` with `claude-sonnet-5` by default. The streamed answer and
28-
citations become a tool result.
30+
citations become a tool result. xAI runs Grok hosted `web_search` with `grok-4.6` by default and,
31+
when enabled, adds hosted `x_search` to the same request.
2932
3. **Loops** until the model answers or the total real-query budget reaches `maxSearchesPerTurn`
3033
(default 3), then removes the search tool and forces a final answer. Real client tools such as
3134
`apply_patch` or shell finalize the turn so those calls reach Codex.
@@ -70,6 +73,28 @@ relevant images in words and include their source URLs.
7073
}
7174
```
7275

76+
The explicit xAI backend uses the stored credential created by `ocx login xai`. Its optional
77+
`xSearch` block enables X search and may restrict it to one handle list and an ISO date range:
78+
79+
```json
80+
{
81+
"webSearchSidecar": {
82+
"backend": "xai",
83+
"model": "grok-4.6",
84+
"xSearch": {
85+
"enabled": true,
86+
"allowedXHandles": ["xai"],
87+
"fromDate": "2026-08-01",
88+
"toDate": "2026-08-21"
89+
}
90+
}
91+
}
92+
```
93+
94+
`allowedXHandles` and `excludedXHandles` are mutually exclusive and each accepts at most 20
95+
strings. Dates use `YYYY-MM-DD`. Malformed management writes return `400`; persisted malformed
96+
blocks fail closed at planning time instead of silently broadening the search.
97+
7398
`minimal` reasoning is not used because the hosted backend rejects tools at that effort. A failed
7499
search is returned to the routed model as a bounded error result, allowing it to answer from the
75100
context it already has.

‎docs-site/src/content/docs/ja/guides/sidecars.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@ description: ネイティブ ChatGPT サイドカー経由でルーティング
55

66
ルーティングモデルごとにホスト型**ウェブ検索**やネイティブ**画像入力**のサポート範囲が異なります。opencodex は
77
ChatGPT ログイン(`forward`)プロバイダーまたは保存された Anthropic OAuth プロバイダーを使う 2 つの
8-
サイドカーで不足機能を補います。サイドカーエラーはターン全体を失敗させず、長さ制限付きのツール
8+
サイドカーで不足機能を補い、ウェブ検索は明示的な `xai` バックエンドで保存済み Grok OAuth も利用できます。サイドカーエラーはターン全体を失敗させず、長さ制限付きのツール
99
結果や画像案内文に差し替わります。
1010

1111
:::note[バックエンド自動選択]
12-
`backend` を明示するとその値が優先します。省略するとアクティブアカウントが `needsReauth` 状態でない Anthropic
13-
OAuth プロバイダーがあるとき `anthropic`、ないとき `openai` を使います。使える認証情報なしに
14-
`anthropic` を明示すると失敗後停止します。`openai` は ChatGPT ログインと有効化された `forward`
12+
`backend` を明示するとその値が優先します。ウェブ検索は省略時に常に `openai`、Vision は利用可能な
13+
Anthropic OAuth アカウントがあれば `anthropic`、なければ `openai` を使います。利用可能な認証情報なしに
14+
`anthropic` または `xai` を明示するとフォールバックせず失敗します。`openai` は ChatGPT ログインと有効化された `forward`
1515
プロバイダーが両方必要です。
1616
:::
1717

@@ -24,8 +24,9 @@ Codex がパススルーでないルーティングモデルにホスト型 `web
2424
公開します。元のホスト型ツールのオプションはサイドカー呼び出しにそのまま使います。
2525
2. ルーティングモデルを小さな**エージェントループ**で実行します。モデルが `web_search` を呼ぶと選んだ
2626
バックエンドを使います。OpenAI はデフォルト `gpt-5.6-luna` でホスト型 `web_search` を実行し、
27-
Anthropic はデフォルト `claude-sonnet-5` で `web_search_20250305` を実行します。ストリーミング回答と
28-
引用をパースした結果をツール結果として返します。
27+
Anthropic はデフォルト `claude-sonnet-5` で `web_search_20250305` を実行します。xAI はデフォルト
28+
`grok-4.6` で hosted `web_search` を実行し、`xSearch.enabled` が true の場合は同じリクエストに
29+
`x_search` を追加します。ストリーミング回答と引用をパースした結果をツール結果として返します。
2930
3. モデルが答えるか実際の検索クエリの総数が `maxSearchesPerTurn`(デフォルト 3)に達するまで
3031
**反復**します。限度に達すると検索ツールを削除し最終回答を強制します。`apply_patch` や shell
3132
のような実際のクライアントツールが出たらターンを終了し該当呼び出しが Codex に渡るようにします。

‎docs-site/src/content/docs/ja/reference/configuration/server.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -133,8 +133,9 @@ Codex は、タイトルやコミット メッセージなどのタスクに小
133133
|フィールド |タイプ |デフォルト |意味 |
134134
| --- | --- | --- | --- |
135135
| `enabled?` | `boolean` |使用可能な場合はオン |マスタースイッチ。 |
136-
| `backend?` | `"openai" \| "anthropic"` |自動 |明示的な勝利。それ以外の場合は使用可能な保存された Anthropic OAuth は `anthropic` を選択し、次に `openai` を選択します。 |
137-
| `model?` | `string` |バックエンド依存 | OpenAI の場合は `gpt-5.6-luna`、Anthropic の場合は `claude-sonnet-5`。従来の明示的な `gpt-5.4-mini` は開始時に移行されます。 |
136+
| `backend?` | `"openai" \| "anthropic" \| "xai" \| "gemini" \| "exa"` | `openai` | 明示設定が優先され、未設定なら常に `openai` です。`anthropic` と `xai` は明示設定時のみ実行され、`gemini` と `exa` は executor が提供されるまで予約値です。 |
137+
| `model?` | `string` |バックエンド依存 | OpenAI は `gpt-5.6-luna`、Anthropic は `claude-sonnet-5`、xAI は `grok-4.6`。従来の明示的な `gpt-5.4-mini` は開始時に移行されます。 |
138+
| `xSearch?` | `object` | 省略 | xAI 専用の hosted `x_search` opt-in。`enabled`、相互排他的な `allowedXHandles` / `excludedXHandles` 配列(最大 20 件)、ISO の `fromDate` / `toDate`(`YYYY-MM-DD`)を指定します。 |
138139
| `reasoning?` | `string` | `low` |サイドカーの取り組み。 `minimal` は Web 検索で拒否されます。 |
139140
| `maxSearchesPerTurn?` | `number` | `3` |メインモデルのターンごとに許可される実際の検索。 |
140141
| `routedModelStallTimeoutMs?` | `number` | `200000` |設定ファイルのみのルーテッド モデルの raw ボディの非アクティブ期限。整数 1 ~ 2147483647。空でないすべてのチャンクがリセットされます。 |

‎docs-site/src/content/docs/ko/guides/sidecars.md‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,14 @@ description: 네이티브 ChatGPT 사이드카를 통해 라우팅 모델에 실
55

66
라우팅 모델마다 호스팅 **웹 검색**이나 네이티브 **이미지 입력** 지원 범위가 다릅니다. opencodex는
77
ChatGPT 로그인(`forward`) 프로바이더나 저장된 Anthropic OAuth 프로바이더를 사용하는 두
8-
사이드카로 부족한 기능을 보완합니다. 사이드카 오류는 턴 전체를 실패시키지 않고 길이가 제한된 도구
8+
사이드카로 부족한 기능을 보완하며, 웹 검색은 명시적인 `xai` 백엔드로 저장된 Grok OAuth도 사용할 수
9+
있습니다. 사이드카 오류는 턴 전체를 실패시키지 않고 길이가 제한된 도구
910
결과나 이미지 안내문으로 바뀝니다.
1011

1112
:::note[백엔드 자동 선택]
12-
`backend`를 명시하면 그 값이 우선합니다. 생략하면 활성 계정이 `needsReauth` 상태가 아닌 Anthropic
13-
OAuth 프로바이더가 있을 때 `anthropic`, 없을 때 `openai`를 사용합니다. 쓸 수 있는 자격 증명 없이
14-
`anthropic`을 명시하면 실패 후 중단합니다. `openai`는 ChatGPT 로그인과 활성화된 `forward`
13+
`backend`를 명시하면 그 값이 우선합니다. 웹 검색은 생략 시 항상 `openai`를 사용하고, 비전은 사용
14+
가능한 Anthropic OAuth 계정이 있으면 `anthropic`, 없으면 `openai`를 사용합니다. 쓸 수 있는 자격
15+
증명 없이 `anthropic` 또는 `xai`를 명시하면 폴백 없이 실패합니다. `openai`는 ChatGPT 로그인과 활성화된 `forward`
1516
프로바이더가 모두 필요합니다.
1617
:::
1718

@@ -24,8 +25,9 @@ Codex가 패스스루가 아닌 라우팅 모델에 호스팅 `web_search`를
2425
노출합니다. 원래 호스팅 도구의 옵션은 사이드카 호출에 그대로 사용합니다.
2526
2. 라우팅 모델을 작은 **에이전트 루프**에서 실행합니다. 모델이 `web_search`를 호출하면 선택한
2627
백엔드를 사용합니다. OpenAI는 기본 `gpt-5.6-luna`로 호스팅 `web_search`를 실행하고,
27-
Anthropic은 기본 `claude-sonnet-5`로 `web_search_20250305`를 실행합니다. 스트리밍 답변과
28-
인용을 파싱한 결과는 도구 결과로 돌려줍니다.
28+
Anthropic은 기본 `claude-sonnet-5`로 `web_search_20250305`를 실행합니다. xAI는 기본
29+
`grok-4.6`으로 호스팅 `web_search`를 실행하고, `xSearch.enabled`가 true이면 같은 요청에
30+
`x_search`를 추가합니다. 스트리밍 답변과 인용을 파싱한 결과는 도구 결과로 돌려줍니다.
2931
3. 모델이 답하거나 실제 검색 쿼리의 총합이 `maxSearchesPerTurn`(기본값 3)에 도달할 때까지
3032
**반복**합니다. 한도에 닿으면 검색 도구를 제거하고 최종 답변을 강제합니다. `apply_patch`나 shell
3133
같은 실제 클라이언트 도구가 나오면 턴을 끝내 해당 호출이 Codex에 전달되게 합니다.

‎docs-site/src/content/docs/ko/reference/configuration/server.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -133,8 +133,9 @@ Codex는 제목과 커밋 메시지 같은 작업에 작은 보조 모델을 사
133133
| 필드 | 형식 | 기본값 | 의미 |
134134
| --- | --- | --- | --- |
135135
| `enabled?` | `boolean` | on when usable | 주 스위치입니다. |
136-
| `backend?` | `"openai" \| "anthropic"` | auto | 명시값이 우선입니다. 그 외에는 사용 가능한 저장된 Anthropic OAuth가 있으면 `anthropic`을, 아니면 `openai`를 선택합니다. |
137-
| `model?` | `string` | backend-dependent | OpenAI는 `gpt-5.6-luna`, Anthropic은 `claude-sonnet-5`입니다. 레거시로 명시된 `gpt-5.4-mini`는 시작 시 마이그레이션됩니다. |
136+
| `backend?` | `"openai" \| "anthropic" \| "xai" \| "gemini" \| "exa"` | `openai` | 명시값이 우선입니다. 생략하면 항상 `openai`입니다. `anthropic`과 `xai`는 명시적으로 설정할 때만 실행되며, `gemini`와 `exa`는 executor가 제공될 때까지 예약 상태입니다. |
137+
| `model?` | `string` | backend-dependent | OpenAI는 `gpt-5.6-luna`, Anthropic은 `claude-sonnet-5`, xAI는 `grok-4.6`입니다. 레거시로 명시된 `gpt-5.4-mini`는 시작 시 마이그레이션됩니다. |
138+
| `xSearch?` | `object` | 생략 | xAI 전용 `x_search` opt-in입니다. `enabled`, 서로 배타적인 `allowedXHandles` / `excludedXHandles` 배열(최대 20개), ISO `fromDate` / `toDate`(`YYYY-MM-DD`)를 지원합니다. |
138139
| `reasoning?` | `string` | `low` | 사이드카 노력 수준입니다. `minimal`은 web search와 함께 거부됩니다. |
139140
| `maxSearchesPerTurn?` | `number` | `3` | 메인 모델 턴당 허용되는 실제 검색 수입니다. |
140141
| `routedModelStallTimeoutMs?` | `number` | `200000` | 설정 파일 전용 routed-model 원시 본문 비활성 기한입니다. 정수 1–2147483647이며, 비어 있지 않은 모든 청크가 이를 다시 시작합니다. |

‎docs-site/src/content/docs/reference/configuration/server.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -205,8 +205,9 @@ Images API paths and response shape expected by Codex.
205205
| Field | Type | Default | Meaning |
206206
| --- | --- | --- | --- |
207207
| `enabled?` | `boolean` | on when usable | Master switch. |
208-
| `backend?` | `"openai" \| "anthropic"` | `openai` | Explicit wins; unset always resolves to `openai`. `anthropic` runs only when explicitly configured. |
209-
| `model?` | `string` | backend-dependent | `gpt-5.6-luna` for OpenAI or `claude-sonnet-5` for Anthropic. Legacy explicit `gpt-5.4-mini` migrates on start. |
208+
| `backend?` | `"openai" \| "anthropic" \| "xai" \| "gemini" \| "exa"` | `openai` | Explicit wins; unset always resolves to `openai`. `anthropic` and `xai` run only when explicitly configured; `gemini` and `exa` remain reserved until their executors ship. |
209+
| `model?` | `string` | backend-dependent | `gpt-5.6-luna` for OpenAI, `claude-sonnet-5` for Anthropic, or `grok-4.6` for xAI. Legacy explicit `gpt-5.4-mini` migrates on start. |
210+
| `xSearch?` | `object` | omitted | xAI-only opt-in for hosted `x_search`: `enabled`, mutually exclusive `allowedXHandles` / `excludedXHandles` arrays (maximum 20), and ISO `fromDate` / `toDate` (`YYYY-MM-DD`). |
210211
| `reasoning?` | `string` | `low` | Sidecar effort. `minimal` is rejected with web search. |
211212
| `maxSearchesPerTurn?` | `number` | `3` | Real searches allowed per main-model turn. |
212213
| `routedModelStallTimeoutMs?` | `number` | `200000` | Config-file-only routed-model raw-body inactivity deadline. Integer 1–2147483647; every non-empty chunk resets it. |
@@ -216,7 +217,9 @@ The OpenAI backend requires a ChatGPT login and enabled ChatGPT `forward` provid
216217
routed replays inject main ChatGPT auth into the internal request. The Anthropic backend uses the
217218
active stored credential from an enabled Anthropic OAuth provider. An explicitly selected Anthropic
218219
backend with no usable account fails closed instead of falling back. The Anthropic executor uses its
219-
native `web_search_20250305` tool.
220+
native `web_search_20250305` tool. The xAI backend requires a usable stored Grok OAuth account, uses
221+
hosted `web_search`, and adds hosted `x_search` when `xSearch.enabled` is true. Malformed `xSearch`
222+
management input returns `400`; a malformed persisted block fails closed during planning.
220223

221224
Four clocks govern search: base `stallTimeoutSec`, `connectTimeoutMs`, routed-model inactivity, and
222225
hosted-search timeout. The effective bridge watchdog is the maximum plus 30 seconds. Routed stall is

0 commit comments

Comments
 (0)