feat(web-search): live xai executor with opt-in x_search (#2188 L7)

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

@@ -5,13 +5,13 @@ description: Dotez les modèles routés d’une véritable recherche web et donn
 
 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
 ces capacités au moyen de deux services auxiliaires. Chacun peut s’appuyer sur un fournisseur connecté à ChatGPT (`forward`) ou sur un
-fournisseur Anthropic OAuth enregistré. Les erreurs des services auxiliaires sont converties en résultats d’outil limités ou en marqueurs d’image,
+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,
 au lieu de faire échouer l’intégralité du tour.
 
 :::note[Sélection automatique du moteur]
-Une valeur `backend` explicite est prioritaire. Lorsqu'elle est omise, opencodex utilise `anthropic` si un fournisseur OAuth Anthropic actif
-possède un compte actif qui n'est pas marqué `needsReauth` ; sinon, il utilise `openai`. Une sélection explicite de
-`anthropic` sans ces identifiants échoue de manière sûre. `openai` exige à la fois une connexion ChatGPT et un
+Une valeur `backend` explicite est prioritaire. Sans valeur, la recherche web utilise toujours `openai` ; Vision utilise
+`anthropic` si un compte OAuth Anthropic utilisable existe, sinon `openai`. Une sélection explicite de
+`anthropic` ou `xai` sans identifiants utilisables échoue sans repli. `openai` exige à la fois une connexion ChatGPT et un
 fournisseur `forward` actif.
 :::
 
@@ -24,7 +24,8 @@ Lorsque Codex demande un hébergement `web_search` pour un modèle routé sans p
 2. Exécute le modèle routé dans une petite **boucle d'agent**. Lorsqu'il appelle `web_search`, opencodex utilise le
    moteur du service auxiliaire sélectionné : OpenAI exécute l'outil hébergé `web_search` avec `gpt-5.6-luna` par défaut ;
    Anthropic exécute `web_search_20250305` avec `claude-sonnet-5` par défaut. La réponse en streaming et
-   les citations deviennent le résultat d’un outil.
+   les citations deviennent le résultat d’un outil. xAI exécute `web_search` avec `grok-4.6` par défaut et ajoute
+   `x_search` à la même requête lorsque `xSearch.enabled` vaut true.
 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`
    (par défaut 3), supprime ensuite l'outil de recherche et force une réponse finale. De vrais outils clients tels que
    `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

@@ -209,8 +209,10 @@ l'API Images d'OpenAI et la forme de réponse attendue par Codex.
 | Champ | Type | Par défaut | Signification |
 | --- | --- | --- | --- |
 | `enabled?` | `boolean` | activé lorsqu'il est utilisable | Interrupteur principal. |
-| `backend?` | `"openai" \| "anthropic" \| "xai" \| "gemini" \| "exa"` | `openai` | Une valeur explicite est prioritaire ; sans valeur, `openai` est toujours utilisé. `xai`, `gemini` et `exa` ne s'activent que s'ils sont configurés explicitement. |
-| `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. |
+| `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. |
+| `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. |
+| `exaApiKey?` | `string` | aucun | Clé opérateur pour le backend `exa`. Écriture seule : les lectures de gestion ne renvoient jamais la valeur stockée. |
+| `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`). |
 | `reasoning?` | `string` | `low` | Effort secondaire. `minimal` est rejeté lors de la recherche sur le Web. |
 | `maxSearchesPerTurn?` | `number` | `3` | Recherches réelles autorisées par tour de modèle principal. |
 | `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. |
@@ -220,7 +222,11 @@ Le moteur OpenAI nécessite une connexion à ChatGPT et un fournisseur ChatGPT `
 entrantes depuis Claude injectent l'authentification ChatGPT principale dans la requête interne. Le moteur Anthropic utilise les
 identifiants actifs stockés auprès d'un fournisseur Anthropic OAuth activé. Si le moteur Anthropic est sélectionné explicitement
 mais qu'aucun compte n'est utilisable, l'opération échoue de manière sûre au lieu de se rabattre sur un autre moteur. L'exécuteur Anthropic utilise son
-outil `web_search_20250305` natif.
+outil `web_search_20250305` natif. Le backend xAI nécessite un compte OAuth Grok stocké et utilisable, emploie
+`web_search` hébergé et ajoute `x_search` hébergé lorsque `xSearch.enabled` vaut true. Une entrée de gestion
+`xSearch` mal formée renvoie `400` ; un bloc persistant mal formé échoue de manière sûre pendant la planification.
+Les voies `gemini` et `exa` ne s'activent jamais par découverte d'identifiants ni par fallback ; l'opérateur doit
+les sélectionner explicitement. `exaApiKey` est accepté en écriture mais omis des réponses de gestion.
 
 Quatre horloges régissent la recherche : base `stallTimeoutSec`, `connectTimeoutMs`, inactivité du modèle routé et
 délai d'expiration de la recherche hébergée. Le chien de garde efficace du pont est le maximum plus 30 secondes. Le décrochage routé est

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

@@ -4,16 +4,18 @@ description: Give routed models real web search and text-only models image under
 ---
 
 Routed models do not all expose hosted **web search** or native **image input**. opencodex backfills
-those capabilities with two sidecars. Each can run through a ChatGPT-login (`forward`) provider or a
-stored Anthropic OAuth provider. Sidecar errors become bounded tool results or image markers instead
-of failing the whole turn.
+those capabilities with two sidecars. Both support a ChatGPT-login (`forward`) provider or stored
+Anthropic OAuth provider; web search can additionally use stored Grok OAuth through the explicit
+`xai` backend. Sidecar errors become bounded tool results or image markers instead of failing the
+whole turn.
 
 :::note[Automatic backend selection]
 Explicit `backend` config wins. The two sidecars default differently when `backend` is unset:
 **web search** always defaults to `openai` — `anthropic` runs only when explicitly configured.
 **Vision** defaults to `anthropic` if an enabled Anthropic OAuth provider has an active account not
 marked `needsReauth`, otherwise `openai`. Explicit `anthropic` without that credential fails
-closed. `openai` requires both ChatGPT login auth and an enabled `forward` provider.
+closed. Explicit `xai` requires a usable stored Grok OAuth account and does not fall back. `openai`
+requires both ChatGPT login auth and an enabled `forward` provider.
 :::
 
 ## Web-search sidecar
@@ -25,7 +27,8 @@ When Codex requests hosted `web_search` for a non-passthrough routed model, open
 2. Runs the routed model in a small **agentic loop**. When it calls `web_search`, opencodex uses the
    selected sidecar backend: OpenAI runs hosted `web_search` with `gpt-5.6-luna` by default;
    Anthropic runs `web_search_20250305` with `claude-sonnet-5` by default. The streamed answer and
-   citations become a tool result.
+   citations become a tool result. xAI runs Grok hosted `web_search` with `grok-4.6` by default and,
+   when enabled, adds hosted `x_search` to the same request.
 3. **Loops** until the model answers or the total real-query budget reaches `maxSearchesPerTurn`
    (default 3), then removes the search tool and forces a final answer. Real client tools such as
    `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.
 }
 ```
 
+The explicit xAI backend uses the stored credential created by `ocx login xai`. Its optional
+`xSearch` block enables X search and may restrict it to one handle list and an ISO date range:
+
+```json
+{
+  "webSearchSidecar": {
+    "backend": "xai",
+    "model": "grok-4.6",
+    "xSearch": {
+      "enabled": true,
+      "allowedXHandles": ["xai"],
+      "fromDate": "2026-08-01",
+      "toDate": "2026-08-21"
+    }
+  }
+}
+```
+
+`allowedXHandles` and `excludedXHandles` are mutually exclusive and each accepts at most 20
+strings. Dates use `YYYY-MM-DD`. Malformed management writes return `400`; persisted malformed
+blocks fail closed at planning time instead of silently broadening the search.
+
 `minimal` reasoning is not used because the hosted backend rejects tools at that effort. A failed
 search is returned to the routed model as a bounded error result, allowing it to answer from the
 context it already has.

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

@@ -5,13 +5,13 @@ description: ネイティブ ChatGPT サイドカー経由でルーティング
 
 ルーティングモデルごとにホスト型**ウェブ検索**やネイティブ**画像入力**のサポート範囲が異なります。opencodex は
 ChatGPT ログイン(`forward`)プロバイダーまたは保存された Anthropic OAuth プロバイダーを使う 2 つの
-サイドカーで不足機能を補います。サイドカーエラーはターン全体を失敗させず、長さ制限付きのツール
+サイドカーで不足機能を補い、ウェブ検索は明示的な `xai` バックエンドで保存済み Grok OAuth も利用できます。サイドカーエラーはターン全体を失敗させず、長さ制限付きのツール
 結果や画像案内文に差し替わります。
 
 :::note[バックエンド自動選択]
-`backend` を明示するとその値が優先します。省略するとアクティブアカウントが `needsReauth` 状態でない Anthropic
-OAuth プロバイダーがあるとき `anthropic`、ないとき `openai` を使います。使える認証情報なしに
-`anthropic` を明示すると失敗後停止します。`openai` は ChatGPT ログインと有効化された `forward`
+`backend` を明示するとその値が優先します。ウェブ検索は省略時に常に `openai`、Vision は利用可能な
+Anthropic OAuth アカウントがあれば `anthropic`、なければ `openai` を使います。利用可能な認証情報なしに
+`anthropic` または `xai` を明示するとフォールバックせず失敗します。`openai` は ChatGPT ログインと有効化された `forward`
 プロバイダーが両方必要です。
 :::
 
@@ -24,8 +24,9 @@ Codex がパススルーでないルーティングモデルにホスト型 `web
    公開します。元のホスト型ツールのオプションはサイドカー呼び出しにそのまま使います。
 2. ルーティングモデルを小さな**エージェントループ**で実行します。モデルが `web_search` を呼ぶと選んだ
    バックエンドを使います。OpenAI はデフォルト `gpt-5.6-luna` でホスト型 `web_search` を実行し、
-   Anthropic はデフォルト `claude-sonnet-5` で `web_search_20250305` を実行します。ストリーミング回答と
-   引用をパースした結果をツール結果として返します。
+   Anthropic はデフォルト `claude-sonnet-5` で `web_search_20250305` を実行します。xAI はデフォルト
+   `grok-4.6` で hosted `web_search` を実行し、`xSearch.enabled` が true の場合は同じリクエストに
+   `x_search` を追加します。ストリーミング回答と引用をパースした結果をツール結果として返します。
 3. モデルが答えるか実際の検索クエリの総数が `maxSearchesPerTurn`(デフォルト 3)に達するまで
    **反復**します。限度に達すると検索ツールを削除し最終回答を強制します。`apply_patch` や shell
    のような実際のクライアントツールが出たらターンを終了し該当呼び出しが Codex に渡るようにします。

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

@@ -133,14 +133,16 @@ Codex は、タイトルやコミット メッセージなどのタスクに小
 |フィールド |タイプ |デフォルト |意味 |
 | --- | --- | --- | --- |
 | `enabled?` | `boolean` |使用可能な場合はオン |マスタースイッチ。 |
-| `backend?` | `"openai" \| "anthropic" \| "xai" \| "gemini" \| "exa"` | `openai` |明示指定が優先され、未指定時は常に `openai` です。`xai`、`gemini`、`exa` は明示的に設定した場合のみ有効になります。 |
-| `model?` | `string` |バックエンド依存 | OpenAI の場合は `gpt-5.6-luna`、Anthropic の場合は `claude-sonnet-5`。従来の明示的な `gpt-5.4-mini` は開始時に移行されます。 |
+| `backend?` | `"openai" \| "anthropic" \| "xai" \| "gemini" \| "exa"` | `openai` | 明示設定が優先され、未設定なら常に `openai` です。`anthropic` と `xai` は明示設定時のみ実行され、`gemini` と `exa` は executor が提供されるまで予約値です。 |
+| `model?` | `string` |バックエンド依存 | OpenAI は `gpt-5.6-luna`、Anthropic は `claude-sonnet-5`、xAI は `grok-4.6`。従来の明示的な `gpt-5.4-mini` は開始時に移行されます。 |
+| `exaApiKey?` | `string` | なし | `exa` バックエンドのオペレーターキー。書き込み専用で、管理 API の読み取りでは保存値を返しません。 |
+| `xSearch?` | `object` | 省略 | xAI 専用の hosted `x_search` opt-in。`enabled`、相互排他的な `allowedXHandles` / `excludedXHandles` 配列（最大 20 件）、ISO の `fromDate` / `toDate`（`YYYY-MM-DD`）を指定します。 |
 | `reasoning?` | `string` | `low` |サイドカーの取り組み。 `minimal` は Web 検索で拒否されます。 |
 | `maxSearchesPerTurn?` | `number` | `3` |メインモデルのターンごとに許可される実際の検索。 |
 | `routedModelStallTimeoutMs?` | `number` | `200000` |設定ファイルのみのルーテッド モデルの raw ボディの非アクティブ期限。整数 1 ～ 2147483647。空でないすべてのチャンクがリセットされます。 |
 | `timeoutMs?` | `number` | `60000` | 1 つのホストされた検索の期限。 |
 
-OpenAI バックエンドには、ChatGPT ログインと有効な ChatGPT `forward` プロバイダーが必要です。クロードインバウンドのルーティングされたリプレイは、メインの ChatGPT 認証を内部リクエストに挿入します。 Anthropic バックエンドは、有効な Anthropic OAuth プロバイダーからのアクティブに保存された資格情報を使用します。使用可能なアカウントがない、明示的に選択された Anthropic バックエンドは、フォールバックせずに失敗して閉じられます。 Anthropic executor は、ネイティブの `web_search_20250305` ツールを使用します。
+OpenAI バックエンドには、ChatGPT ログインと有効な ChatGPT `forward` プロバイダーが必要です。クロードインバウンドのルーティングされたリプレイは、メインの ChatGPT 認証を内部リクエストに挿入します。 Anthropic バックエンドは、有効な Anthropic OAuth プロバイダーからのアクティブに保存された資格情報を使用します。使用可能なアカウントがない、明示的に選択された Anthropic バックエンドは、フォールバックせずに失敗して閉じられます。 Anthropic executor は、ネイティブの `web_search_20250305` ツールを使用します。xAI バックエンドには使用可能な保存済み Grok OAuth アカウントが必要で、hosted `web_search` を使用し、`xSearch.enabled` が true の場合は hosted `x_search` を追加します。不正な `xSearch` 管理入力は `400` を返し、不正な永続化ブロックは計画時に fail closed します。`gemini` と `exa` は資格情報の検出やフォールバックからは決して有効にならず、オペレーターが明示的に選択する必要があります。`exaApiKey` は書き込み時に受け付けますが、管理レスポンスからは省略されます。
 
 検索は 4 つのクロック (ベース `stallTimeoutSec`、`connectTimeoutMs`、ルーテッド モデルの非アクティビティ、ホスト型検索のタイムアウト) によって制御されます。有効なブリッジ ウォッチドッグは、最大プラス 30 秒です。ルート ストールは非アクティブ ガードであり、総生成期限ではありません。
 

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

@@ -5,13 +5,14 @@ description: 네이티브 ChatGPT 사이드카를 통해 라우팅 모델에 실
 
 라우팅 모델마다 호스팅 **웹 검색**이나 네이티브 **이미지 입력** 지원 범위가 다릅니다. opencodex는
 ChatGPT 로그인(`forward`) 프로바이더나 저장된 Anthropic OAuth 프로바이더를 사용하는 두
-사이드카로 부족한 기능을 보완합니다. 사이드카 오류는 턴 전체를 실패시키지 않고 길이가 제한된 도구
+사이드카로 부족한 기능을 보완하며, 웹 검색은 명시적인 `xai` 백엔드로 저장된 Grok OAuth도 사용할 수
+있습니다. 사이드카 오류는 턴 전체를 실패시키지 않고 길이가 제한된 도구
 결과나 이미지 안내문으로 바뀝니다.
 
 :::note[백엔드 자동 선택]
-`backend`를 명시하면 그 값이 우선합니다. 생략하면 활성 계정이 `needsReauth` 상태가 아닌 Anthropic
-OAuth 프로바이더가 있을 때 `anthropic`, 없을 때 `openai`를 사용합니다. 쓸 수 있는 자격 증명 없이
-`anthropic`을 명시하면 실패 후 중단합니다. `openai`는 ChatGPT 로그인과 활성화된 `forward`
+`backend`를 명시하면 그 값이 우선합니다. 웹 검색은 생략 시 항상 `openai`를 사용하고, 비전은 사용
+가능한 Anthropic OAuth 계정이 있으면 `anthropic`, 없으면 `openai`를 사용합니다. 쓸 수 있는 자격
+증명 없이 `anthropic` 또는 `xai`를 명시하면 폴백 없이 실패합니다. `openai`는 ChatGPT 로그인과 활성화된 `forward`
 프로바이더가 모두 필요합니다.
 :::
 
@@ -24,8 +25,9 @@ Codex가 패스스루가 아닌 라우팅 모델에 호스팅 `web_search`를 
    노출합니다. 원래 호스팅 도구의 옵션은 사이드카 호출에 그대로 사용합니다.
 2. 라우팅 모델을 작은 **에이전트 루프**에서 실행합니다. 모델이 `web_search`를 호출하면 선택한
    백엔드를 사용합니다. OpenAI는 기본 `gpt-5.6-luna`로 호스팅 `web_search`를 실행하고,
-   Anthropic은 기본 `claude-sonnet-5`로 `web_search_20250305`를 실행합니다. 스트리밍 답변과
-   인용을 파싱한 결과는 도구 결과로 돌려줍니다.
+   Anthropic은 기본 `claude-sonnet-5`로 `web_search_20250305`를 실행합니다. xAI는 기본
+   `grok-4.6`으로 호스팅 `web_search`를 실행하고, `xSearch.enabled`가 true이면 같은 요청에
+   `x_search`를 추가합니다. 스트리밍 답변과 인용을 파싱한 결과는 도구 결과로 돌려줍니다.
 3. 모델이 답하거나 실제 검색 쿼리의 총합이 `maxSearchesPerTurn`(기본값 3)에 도달할 때까지
    **반복**합니다. 한도에 닿으면 검색 도구를 제거하고 최종 답변을 강제합니다. `apply_patch`나 shell
    같은 실제 클라이언트 도구가 나오면 턴을 끝내 해당 호출이 Codex에 전달되게 합니다.