feat(vision): make sidecar reasoning model-aware

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

@@ -70,14 +70,20 @@ failures after response headers have started are delivered as `response.failed`
 ## Vision sidecar
 
 When the routed model is listed in its provider's `noVisionModels` and a request carries an image,
-opencodex describes each image **before** the main call and replaces it with text. The Dashboard and
-management API present `gpt-5.6-luna` as the current default, and startup migrates an explicitly
-persisted legacy `gpt-5.4-mini` value to Luna. If the `visionSidecar.model` field is entirely absent,
-the vision execution path still has a `gpt-5.4-mini` code fallback.
+opencodex describes each image **before** the main call and replaces it with text. When
+`visionSidecar.model` is absent or blank, the OpenAI execution path, Dashboard, and management API
+use the `gpt-5.4-mini` fallback. Startup still migrates an explicitly persisted legacy
+`gpt-5.4-mini` value to `gpt-5.6-luna`; that migration applies to a stored value, not to an absent
+model field.
 
 - Images can come from user, developer, and tool-result messages, including Codex's `view_image`.
-- Each image is sent to the configured native vision model with `reasoning.effort: "low"`; its
-  description replaces the image part inline.
+- On the OpenAI path (ChatGPT-login passthrough), each image is sent to the configured vision model
+  over the Responses endpoint with the selected `reasoning.effort` (`low` by default), and its
+  description replaces the image part inline. The Anthropic path uses the Messages endpoint with its
+  own thinking-budget mapping and ignores this OpenAI-specific setting.
+- For native models with known capability metadata, unsupported reasoning is normalized to the
+  highest supported rung at or below the requested level; if none exists, the lowest supported rung
+  is used. Unknown or custom models remain permissive when reliable capability metadata is absent.
 - Descriptions run with bounded concurrency (3 at a time, input order preserved). User context sent
   to the describer is capped at 800 characters, and each injected description is capped at 2,000
   characters. The request does not send `max_output_tokens`, which the ChatGPT backend rejects.
@@ -90,14 +96,17 @@ the vision execution path still has a `gpt-5.4-mini` code fallback.
   available, the raw image is stripped rather than forwarded to a text-only backend.
 - `maxDescriptionsPerTurn` (default 8) limits new descriptions per main-model turn. Cache hits and
   same-turn duplicates do not consume it. Successful `data:` image descriptions are cached by
-  backend, model, detail, image bytes, and message context; mutable `https:` images are not cached.
+  backend, model, detail, image bytes, and message context — plus the reasoning effort on OpenAI
+  keys (Anthropic keys omit it, since that field is ignored there); mutable `https:` images are not
+  cached.
 
 ```json
 {
   "visionSidecar": {
     "enabled": true,
-    "backend": "anthropic",
-    "model": "claude-sonnet-5",
+    "backend": "openai",
+    "model": "gpt-5.6-luna",
+    "reasoning": "medium",
     "maxDescriptionsPerTurn": 8,
     "timeoutMs": 45000
   }

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

@@ -69,14 +69,20 @@ stall は全体生成 timeout ではありません。SSE 開始前の失敗は
 ## ビジョンサイドカー
 
 ルーティングモデルが該当プロバイダーの `noVisionModels` にありリクエストに画像が来る場合、opencodex は
-メイン呼び出し**前に**各画像を説明したテキストに差し替えます。ダッシュボードと管理 API の現在のデフォルト選択は
-`gpt-5.6-luna` で、起動時に明示的に保存された既存 `gpt-5.4-mini` 値も Luna にマイグレーションします。
-ただし `visionSidecar.model` フィールド自体がない場合はビジョン実行経路はコードフォールバックの `gpt-5.4-mini` を使います。
+メイン呼び出し**前に**各画像を説明したテキストに差し替えます。`visionSidecar.model` が未設定または空の場合、
+OpenAI 実行経路、ダッシュボード、管理 API は `gpt-5.4-mini` をフォールバックとして使います。起動時には
+明示的に保存された旧 `gpt-5.4-mini` 値を引き続き `gpt-5.6-luna` にマイグレーションしますが、この
+マイグレーションは保存済みの値だけが対象で、モデルフィールドがない場合には適用されません。
 
 - 画像はユーザー、developer、ツール結果メッセージから来ます。Codex の `view_image` 結果も
   含まれます。
-- 各画像は設定されたネイティブビジョンモデルに `reasoning.effort: "low"` で渡され、説明が画像
-  部分をインラインに差し替えます。
+- OpenAI パス（ChatGPT ログインパススルー）では、各画像は選択した `reasoning.effort`（デフォルト
+  `low`）付きで Responses エンドポイント経由で設定済みのビジョンモデルに送信され、説明が画像部分
+  をインラインで置き換えます。Anthropic パスは Messages エンドポイントを使い、独自の思考予算
+  マッピングで動作し、この OpenAI 固有の設定を無視します。
+- 信頼できる能力メタデータがあるネイティブモデルでは、未対応の推論レベルは要求値以下で最も高い
+  対応レベルに正規化されます。該当するレベルがない場合は最も低い対応レベルを使います。能力情報を
+  信頼できない不明モデルやカスタムモデルは制限せず、そのまま扱います。
 - 説明は一度に 3 件並列処理し入力順序を維持します。説明モデルに渡すユーザー文脥は
   800 文字、注入する画像説明は 1 枚あたり 2,000 文字に制限します。ChatGPT バックエンドが拒否する
   `max_output_tokens` は送信しません。
@@ -89,14 +95,17 @@ stall は全体生成 timeout ではありません。SSE 開始前の失敗は
   テキスト専用バックエンドに元画像を送らず削除します。
 - `maxDescriptionsPerTurn`(デフォルト 8)はメインモデル 1 ターンで新規実行する説明数を制限します。キャッシュ
   ヒットと同じターンの重複要求は限度を消費しません。成功した `data:` 画像説明はバックエンド、モデル、
-  detail、画像バイト、メッセージ文脈を基準にキャッシュし、変わり得る `https:` 画像はキャッシュしません。
+  detail、画像バイト、メッセージ文脈を基準にキャッシュし、OpenAI のキーには推論負荷も含まれます
+  (Anthropic のキーには含まれません。そこではこのフィールドは無視されるため)。変わり得る
+  `https:` 画像はキャッシュしません。
 
 ```json
 {
   "visionSidecar": {
     "enabled": true,
-    "backend": "anthropic",
-    "model": "claude-sonnet-5",
+    "backend": "openai",
+    "model": "gpt-5.6-luna",
+    "reasoning": "medium",
     "maxDescriptionsPerTurn": 8,
     "timeoutMs": 45000
   }

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

@@ -144,9 +144,10 @@ OpenAI バックエンドには、ChatGPT ログインと有効な ChatGPT `forw
 | `enabled?` | `boolean` |使用可能な場合はオン |マスターイメージと説明のスイッチ。 |
 | `backend?` | `"openai" \| "anthropic"` |自動 | Web 検索と同じ、明示的優先、人間認証情報を意識した選択。 |
 | `model?` | `string` |バックエンド依存 | OpenAI の場合は `gpt-5.4-mini`、Anthropic の場合は `claude-sonnet-5`。 |
+| `reasoning?` | `"low" \| "medium" \| "high" \| "xhigh" \| "max"` | `"low"` | OpenAI Responses の推論負荷。Anthropic は無視します。 |
 | `maxDescriptionsPerTurn?` | `number` | `8` |新しい説明のキャッシュミスはメインターンごとに許可されます。 `0` は通話を無効にします。無効な値にはデフォルトが使用されます。 |
 | `timeoutMs?` | `number` | `45000` |サイドカーのフェッチタイムアウト。 |
 
-Vision は、プロバイダーの `noVisionModels` のモデルに送信された画像に対してのみアクティブになります。 OpenAI には、検索と同じログイン/転送要件があります。明示的に選択された Anthropic は、使用可能な認証情報がないと失敗します。成功した `data:` 記述では、バックエンド、モデル、詳細、画像バイト、および正規化されたメッセージ コンテキストをキーとした境界付きキャッシュが使用されます。ヒットと同じターンの重複は制限を消費しません。リモート `https:` イメージと失敗した説明、または空の説明はキャッシュされません。
+対応するレベルは、上流プロバイダーの能力と選択したモデルが公表する推論ラダーによって制限されます。 Vision は、プロバイダーの `noVisionModels` のモデルに送信された画像に対してのみアクティブになります。 OpenAI には、検索と同じログイン/転送要件があります。明示的に選択された Anthropic は、使用可能な認証情報がないと失敗します。成功した `data:` 記述では、バックエンド、モデル、詳細、画像バイト、および正規化されたメッセージ コンテキストをキーとした境界付きキャッシュが使用されます。OpenAI のキーには推論負荷も含まれます（Anthropic のキーには含まれません）。ヒットと同じターンの重複は制限を消費しません。リモート `https:` イメージと失敗した説明、または空の説明はキャッシュされません。
 
 Anthropic OAuth サイドカーは、opencodex の既存のクロード コード OAuth フィンガープリントを再利用します。対象のアカウントとワークロードをソークテストします。

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

@@ -70,14 +70,20 @@ stall은 전체 생성 timeout이 아닙니다. SSE가 시작되기 전 실패
 ## 비전 사이드카
 
 라우팅 모델이 해당 프로바이더의 `noVisionModels`에 있고 요청에 이미지가 들어오면, opencodex는
-메인 호출 **전에** 각 이미지를 설명한 텍스트로 바꿉니다. Dashboard와 관리 API의 현재 기본 선택값은
-`gpt-5.6-luna`이며, 시작할 때 명시적으로 저장된 기존 `gpt-5.4-mini` 값도 Luna로 마이그레이션합니다.
-다만 `visionSidecar.model` 필드 자체가 없으면 비전 실행 경로는 코드 폴백인 `gpt-5.4-mini`를 씁니다.
+메인 호출 **전에** 각 이미지를 설명한 텍스트로 바꿉니다. `visionSidecar.model`이 없거나 빈 값이면
+OpenAI 실행 경로, Dashboard, 관리 API는 `gpt-5.4-mini`를 폴백으로 사용합니다. 시작 시 명시적으로
+저장된 기존 `gpt-5.4-mini` 값은 계속 `gpt-5.6-luna`로 마이그레이션되지만, 이 마이그레이션은 저장된
+값에만 적용되고 모델 필드가 없는 경우에는 적용되지 않습니다.
 
 - 이미지는 사용자, developer, 도구 결과 메시지에서 올 수 있습니다. Codex의 `view_image` 결과도
   포함됩니다.
-- 각 이미지는 설정된 네이티브 비전 모델에 `reasoning.effort: "low"`로 전달되고, 설명이 이미지
-  부분을 인라인으로 대체합니다.
+- OpenAI 경로(ChatGPT 로그인 패스스루)에서는 각 이미지가 선택한 `reasoning.effort`(기본값
+  `low`)와 함께 Responses 엔드포인트로 설정된 비전 모델에 전송되고, 설명이 이미지 부분을 인라인으로
+  대체합니다. Anthropic 경로는 Messages 엔드포인트와 자체 thinking 예산 매핑을 사용하며 이
+  OpenAI 전용 설정을 무시합니다.
+- 신뢰할 수 있는 기능 메타데이터가 있는 네이티브 모델에서는 지원되지 않는 추론 수준을 요청값 이하에서
+  가장 높은 지원 단계로 정규화합니다. 해당 단계가 없으면 가장 낮은 지원 단계를 사용합니다. 신뢰할 수
+  있는 기능 메타데이터가 없는 알 수 없는 모델이나 커스텀 모델은 제한하지 않습니다.
 - 설명은 한 번에 3개씩 병렬 처리하며 입력 순서를 유지합니다. 설명 모델에 전달하는 사용자 문맥은
   800자, 주입하는 이미지 설명은 장당 2,000자로 제한합니다. ChatGPT 백엔드가 거부하는
   `max_output_tokens`는 보내지 않습니다.
@@ -90,15 +96,17 @@ stall은 전체 생성 timeout이 아닙니다. SSE가 시작되기 전 실패
   없으면 텍스트 전용 백엔드에 원본 이미지를 보내지 않고 제거합니다.
 - `maxDescriptionsPerTurn`(기본값 8)은 메인 모델 한 턴에서 새로 실행할 설명 수를 제한합니다. 캐시
   적중과 같은 턴의 중복 요청은 한도를 쓰지 않습니다. 성공한 `data:` 이미지 설명은 백엔드, 모델,
-  detail, 이미지 바이트, 메시지 문맥을 기준으로 캐시하며, 바뀔 수 있는 `https:` 이미지는 캐시하지
-  않습니다.
+  detail, 이미지 바이트, 메시지 문맥을 기준으로 캐시하며, OpenAI 키에는 추론 강도도 포함됩니다
+  (Anthropic 키에는 포함되지 않습니다. 해당 필드는 거기서 무시되기 때문입니다). 바뀔 수 있는
+  `https:` 이미지는 캐시하지 않습니다.
 
 ```json
 {
   "visionSidecar": {
     "enabled": true,
-    "backend": "anthropic",
-    "model": "claude-sonnet-5",
+    "backend": "openai",
+    "model": "gpt-5.6-luna",
+    "reasoning": "medium",
     "maxDescriptionsPerTurn": 8,
     "timeoutMs": 45000
   }

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

@@ -144,9 +144,10 @@ OpenAI 백엔드는 ChatGPT 로그인과 활성화된 ChatGPT `forward` provider
 | `enabled?` | `boolean` | on when usable | 주 이미지 설명 스위치입니다. |
 | `backend?` | `"openai" \| "anthropic"` | auto | web search와 같은, 명시값 우선 및 Anthropic 자격 증명 인식 선택 방식입니다. |
 | `model?` | `string` | backend-dependent | OpenAI는 `gpt-5.4-mini`, Anthropic은 `claude-sonnet-5`입니다. |
+| `reasoning?` | `"low" \| "medium" \| "high" \| "xhigh" \| "max"` | `"low"` | OpenAI Responses 추론 강도입니다. Anthropic은 무시합니다. |
 | `maxDescriptionsPerTurn?` | `number` | `8` | 메인 턴당 허용되는 새 설명 캐시 미스 수입니다. `0`이면 호출이 비활성화되며, 잘못된 값은 기본값을 사용합니다. |
 | `timeoutMs?` | `number` | `45000` | 사이드카 fetch 제한 시간입니다. |
 
-Vision은 provider의 `noVisionModels`에 속한 모델로 보낸 이미지에만 활성화됩니다. OpenAI는 검색과 같은 로그인/forward 요건을 갖고 있으며, 명시적으로 선택한 Anthropic은 사용할 수 있는 자격 증명이 없으면 닫힌 상태로 실패합니다. 성공한 `data:` 설명은 backend, model, detail, image bytes, 그리고 정규화된 메시지 컨텍스트를 키로 하는 bounded cache를 사용합니다. 히트와 같은 턴의 중복은 한도를 소모하지 않습니다. 원격 `https:` 이미지와 실패했거나 비어 있는 설명은 캐시하지 않습니다.
+지원되는 수준은 업스트림 제공자의 역량과 선택한 모델이 공개한 추론 사다리에 따라 제한됩니다. Vision은 provider의 `noVisionModels`에 속한 모델로 보낸 이미지에만 활성화됩니다. OpenAI는 검색과 같은 로그인/forward 요건을 갖고 있으며, 명시적으로 선택한 Anthropic은 사용할 수 있는 자격 증명이 없으면 닫힌 상태로 실패합니다. 성공한 `data:` 설명은 backend, model, detail, image bytes, 그리고 정규화된 메시지 컨텍스트를 키로 하는 bounded cache를 사용합니다. OpenAI 키에는 reasoning effort도 포함됩니다(Anthropic 키에는 없습니다). 히트와 같은 턴의 중복은 한도를 소모하지 않습니다. 원격 `https:` 이미지와 실패했거나 비어 있는 설명은 캐시하지 않습니다.
 
 Anthropic OAuth 사이드카는 opencodex의 기존 Claude Code OAuth fingerprint를 재사용합니다. 의도한 계정과 워크로드로 소크 테스트를 수행합니다.