fix(openai-responses): round-trip image-gen namespace (#588)

* fix(openai-responses): round-trip image-gen namespace

Lower Codex's private image_gen namespace to safe API-key aliases, restore function calls in JSON and SSE responses, and encode replayed history without changing ChatGPT forward mode.

* fix(openai-responses): preserve hosted image fallback

Remove hosted image_generation only when a usable client alias replaces it, while retaining the hosted tool for malformed namespaces and replay-only calls.

* fix(openai-responses): restore legacy image aliases

Build the reverse map from explicitly declared dotted image-gen functions so safe upstream aliases return to Codex with an explicit namespace without guessing unrelated double-underscore names.

* fix(responses): preserve eager relay invariant

Keep the win32 eager branch free of client rewrite wrappers and align the source invariant and transport documentation with the no-client-rewrite gate.

* test(responses): name SSE rewrite coverage accurately

Describe the integration test as the platform-neutral passthrough rewrite path while the separate source invariant continues to guard the win32 native relay branch.

* docs(codex): describe generic image aliases

Document the generic image_gen__<inner-name> contract and clarify that hosted image generation is removed only after a usable client alias replaces it.

* docs(i18n): sync image namespace behavior

Update the Japanese, Korean, Russian, and Simplified Chinese Codex integration guides with the API-key alias, response restoration, replay, and forward-mode compatibility contract.

* docs(code): clarify image alias helpers

Document the request-normalization and response-restoration helper contracts without changing the deferred SSE relay structure.

* fix(openai-responses): normalize image tool choices

* refactor(responses): share tool-group collection

Author: RailyW

docs-site/src/content/docs/guides/codex-integration.md

@@ -63,6 +63,15 @@ Standalone `/images/generations` calls never enter that bridge.
   tool offered at all, disable it in Codex with `codex features disable image_generation`
   (`[features] image_generation = false` in `config.toml`).
 
+The tool declaration still travels with the model's Responses request. For API-key Responses
+providers, opencodex lowers Codex's private `image_gen` namespace to an upstream-safe
+`image_gen__<inner-name>` alias (for example `image_gen__imagegen`). When that usable alias replaces
+the client declaration, opencodex removes a duplicate hosted `image_generation` declaration. It maps
+the function call to the explicit `image_gen` namespace before Codex sees it, and encodes the native
+call again when later history is replayed upstream. This keeps client-side image generation callable
+on public-compatible upstreams that reserve the namespace or reject dotted function names. ChatGPT
+forward mode remains untouched and keeps its native Responses Lite shape.
+
 For an OpenAI-compatible custom gateway, configure a dedicated provider and select it only for
 standalone Images requests:
 

docs-site/src/content/docs/ja/guides/codex-integration.md

@@ -57,6 +57,15 @@ ChatGPT bearer 認証で直接 POST します。注入された `base_url` が o
   `codex features disable image_generation`(`config.toml` の `[features] image_generation = false`)を
   使ってください。
 
+ツール宣言はモデルへの Responses リクエストにも引き続き含まれます。API キー方式の Responses
+プロバイダーでは、opencodex は Codex のプライベートな `image_gen` 名前空間を、上流で安全な
+`image_gen__<inner-name>` エイリアス(例: `image_gen__imagegen`)に変換します。その利用可能な
+エイリアスがクライアント宣言を置き換える場合にのみ、重複する hosted `image_generation` 宣言を
+削除します。関数呼び出しは Codex に届く前に明示的な `image_gen` 名前空間へ戻され、後続の履歴を
+上流へ再送するときは再びエンコードされます。これにより、名前空間を予約している、またはドットを
+含む関数名を拒否する OpenAI 互換の上流でも、クライアント側の画像生成を呼び出せます。ChatGPT
+forward モードは変更されず、ネイティブな Responses Lite 形式を維持します。
+
 `hostname` がループバックアドレスでない場合、Codex が自動生成した API 認証ヘッダーを送る必要があります。このとき専用
 プロバイダーを注入します。
 

docs-site/src/content/docs/ko/guides/codex-integration.md

@@ -56,6 +56,15 @@ ChatGPT bearer 인증으로 직접 POST합니다. 주입된 `base_url`이 openco
   `codex features disable image_generation`(`config.toml`의 `[features] image_generation = false`)을
   사용하세요.
 
+도구 선언은 모델의 Responses 요청에도 계속 포함됩니다. API key 방식 Responses 프로바이더에서는
+opencodex가 Codex의 비공개 `image_gen` namespace를 업스트림에서 안전한
+`image_gen__<inner-name>` alias(예: `image_gen__imagegen`)로 변환합니다. 이 사용 가능한 alias가
+클라이언트 선언을 대체할 때만 중복된 hosted `image_generation` 선언을 제거합니다. 함수 호출은
+Codex에 도달하기 전에 명시적인 `image_gen` namespace로 복원되고, 이후 기록을 업스트림으로
+replay할 때 다시 인코딩됩니다. 따라서 namespace를 예약하거나 점이 포함된 함수 이름을 거부하는
+OpenAI 호환 업스트림에서도 클라이언트 측 이미지 생성을 호출할 수 있습니다. ChatGPT forward
+모드는 변경되지 않으며 네이티브 Responses Lite 형식을 유지합니다.
+
 `hostname`이 loopback 주소가 아니면 Codex가 자동 생성된 API 인증 헤더를 보내야 합니다. 이때는 전용
 프로바이더를 주입합니다.
 

docs-site/src/content/docs/ru/guides/codex-integration.md

@@ -64,6 +64,17 @@ fast_mode = true
   командой `codex features disable image_generation`
   (`[features] image_generation = false` в `config.toml`).
 
+Объявление инструмента по-прежнему передаётся в Responses-запросе к модели. Для Responses-
+провайдеров с API-ключом opencodex преобразует приватное пространство имён Codex `image_gen`
+в безопасный для вышестоящей стороны псевдоним `image_gen__<inner-name>` (например,
+`image_gen__imagegen`). Дублирующее объявление hosted-инструмента `image_generation` удаляется
+только тогда, когда такой рабочий псевдоним заменяет клиентское объявление. Перед передачей в
+Codex вызов функции восстанавливается с явным пространством имён `image_gen`, а при последующем
+воспроизведении истории во вышестоящий сервис снова кодируется. Это сохраняет клиентскую
+генерацию изображений у OpenAI-совместимых провайдеров, которые резервируют это пространство
+имён или отклоняют имена функций с точками. Режим ChatGPT forward не изменяется и сохраняет
+свой нативный формат Responses Lite.
+
 Если `hostname` не является loopback-адресом, Codex должен отправлять сгенерированный заголовок
 API-аутентификации. Поэтому инжектор в этом случае использует выделенного провайдера:
 

docs-site/src/content/docs/zh-cn/guides/codex-integration.md

@@ -54,6 +54,14 @@ OpenAI 上游：
   `codex features disable image_generation`（即 `config.toml` 的
   `[features] image_generation = false`）。
 
+工具声明仍会随模型的 Responses 请求一同发送。对于 API key 方式的 Responses 提供商，
+opencodex 会把 Codex 私有的 `image_gen` namespace 转换为上游安全的
+`image_gen__<inner-name>` alias（例如 `image_gen__imagegen`）。只有当这个可用 alias 替代了
+客户端声明时，才会移除重复的 hosted `image_generation` 声明。函数调用会在到达 Codex 前恢复为
+显式的 `image_gen` namespace，后续将历史记录重放到上游时再重新编码。因此，即使 OpenAI 兼容
+上游保留了该 namespace，或拒绝包含点号的函数名，客户端图像生成仍可正常调用。ChatGPT forward
+模式保持不变，并继续使用其原生 Responses Lite 格式。
+
 如果 `hostname` 不是 loopback 地址，Codex 必须发送自动生成的 API 认证请求头。此时注入器会改用
 专用提供商：