fix: preserve caller constraints on the request path (#5211, #5210, #5212, #5213)

devlog/_plan/260920_meaning_preservation_batch/010_lane_a.md

@@ -0,0 +1,100 @@
+# Lane A — meaning preservation on the request path
+
+Status: OPEN. Branch `codex/260920-lane-a-meaning-preservation`, cut from `origin/dev`
+`0613aaec17`. One branch, five ordered commits, one pull request against `dev`.
+
+## What each commit restores
+
+### #5211 — tool choice policy on the Chat Completions path
+
+Two constraints reached the parser and were dropped on the way out, both under a normal 200.
+
+A `tool_choice` of type `allowed_tools` is a record, is not `type: "function"`, and carries no
+`function` member, so it fell past every branch of `toolChoiceToResponses` and `body.tool_choice`
+was never assigned. Chat nests the subset under `allowed_tools` and names each entry under a
+member keyed by its own type; the Responses shape `mapToolChoice` reads carries `mode` and
+`tools` on the choice itself with a flat `name`. Both levels are now flattened. An entry that
+cannot be named is refused rather than skipped, because skipping one widens the subset.
+
+`parallel_tool_calls` had three provider states and two branches, in two places. The unset state
+is the default for every provider that never configured the knob, and it dropped the caller's own
+explicit `false` — on the translated path and, from a second copy of the same branch, on the
+native Chat passthrough. The decision now lives in `src/adapters/openai-chat/parallel-tool-calls.ts`,
+which both builders read. An explicit `true` still omits the key, matching the configured opt-out.
+
+The passthrough half was found by adversarial review, not by the original report.
+
+### #5210 — tool declaration fields on the outbound adapters
+
+`strict` was kept deliberately by the Messages inbound and forwarded by the OpenAI Chat adapter,
+and dropped by Anthropic — the target that defines it. It is now emitted when it is explicitly
+`true`. An unstated `strict` stays absent, because the inbound records it as `false` and a
+`false` on the wire cannot be told apart from silence.
+
+`allowed_callers` had no carrier at all. It now rides `OcxTool.allowedCallers` from the Messages
+inbound, through the Responses tool schema — where an undeclared key is stripped, which is why it
+never reached `buildTools` — to the Anthropic wire. The OpenAI Chat and Gemini builders have no
+counterpart and refuse with a 400 rather than rebuild the declaration without the fence. The
+unrestricted `["direct"]` default is not a restriction.
+
+Gemini's `functionCallingConfig.mode: "VALIDATED"` was plumbed to the wire compiler but only
+reachable by matching a model name. A caller-declared strict tool now selects it in place of the
+absent-choice default; `NONE`, `ANY` and a forced-name choice are never overwritten.
+
+### #5213 — developer message position, then role
+
+Delivered as two commits because they are two acceptance conditions.
+
+Position carries #5237 by Yum-wu with a `Co-authored-by` trailer. The upstream branch had the
+right idea and a broken patch (a stray `];` and an assertion that put the deferred reminder
+before the tool result), so the change was reimplemented and the attribution kept. One
+destination already had chronological placement, keyed to a model id and a registry entry; that
+is a property of prompt-prefix caching rather than of that destination, so it is now universal
+and the model/registry test is gone.
+
+Role is separate. `developer` is part of the Chat Completions role set and is now forwarded as
+sent. A destination that genuinely rejects it sets `foldDeveloperRoleToSystem`, which converts
+the role in place and never moves the message, so the placement contract holds on both paths.
+
+### #5212 — inline document bytes
+
+Both inbound parsers reduced an attachment to its name before any adapter ran.
+`OcxContentPart` gains a document member carrying the media type and the base64 payload;
+Anthropic emits the document block, OpenAI Chat the file part, Gemini `inline_data`.
+
+Widening that union is the hazard, so the part also carries the marker every text-only consumer
+already falls back to, which keeps a wire with no document representation byte-identical to
+before. Six consumers needed more than the fallback: `ollama-native` and the Cursor tool-result
+decoder would have read a nonexistent `imageUrl`, and the Kiro, Devin, Cursor and coding-agent
+text serializers would have produced an empty turn. All were found by adversarial review.
+
+The untranslated-media refusal is narrowed only where a converter actually builds the part:
+user content on the Chat projection, user and developer messages on the Responses one. A file in
+a tool output, a system message or an assistant message is still refused. The scanner and the
+decoder share one predicate, so a request cannot be exempted in one and reduced to a marker in
+the other.
+
+## Known remaining gap
+
+Tool-result documents keep the #939 marker. The Responses tool-output vocabulary has no file
+block and every adapter's tool-result path flattens to text, so carrying bytes there is a
+separate change rather than a half-done one.
+
+## Union-defect check before push
+
+- File-size ratchet: `src/adapters/openai-chat.ts` was the only capped file in the touch set
+  (cap 822). The `parallel_tool_calls` decision moved to a sibling module and the file is 811
+  lines. No cap was raised.
+- `PROVIDER_CONFIG_FIELD_POLICY` in `src/server/auth-cors.ts` is
+  `satisfies Record<keyof OcxProviderConfig, ...>`, so `foldDeveloperRoleToSystem` is classified
+  there and in `providerConfigSchema`.
+- Every new test file is registered in both `scripts/test-layout/layout.json` and
+  `tests/fixtures/test-layout-expected.json`, which the layout guard asserts are equal.
+- No count is restated: the provider reference tables gained a row rather than a number.
+
+## Verification
+
+Static source review plus exact-head hosted CI. Local suites, individual tests, typecheck,
+build, install and live `ocx` execution were NOT RUN, per the lane constraints. Adversarial
+source review ran on every commit and produced the passthrough, Kiro/Devin/Cursor/coding-agent,
+role-aware-refusal and base64-predicate findings listed above.

docs-site/src/content/docs/fr/guides/claude-code.md

@@ -628,4 +628,4 @@ Utilisez `"haiku"` comme valeur de remplacement pour le modèle.
 
 Dans `config.json`, `claudeCode.stabilizePromptCache: true` déplace les notices Claude reconnues en fin des instructions système vers un dernier message utilisateur sur les routes traduites. La valeur par défaut est `false`. Activez cette option seulement si ce changement de rôle convient à vos clients. Les exemples dans des blocs de code et le texte non reconnu sont conservés ; le transfert Anthropic natif reste inchangé. Sans métadonnées, la clé de cache suit les instructions stabilisées. Cette option ne crée pas une identité de conversation et ne garantit aucun succès du cache amont.
 
-Sur la route Chat d’OpenCode Go pour `deepseek-v4.1-flash`, les rappels système traduits dans l’historique conservent automatiquement leur position et leur rôle system, après les résultats d’outils encore attendus. Ainsi, l’ajout de rappels ne réécrit pas le prompt système initial. Ce comportement s’applique avec ou sans `stabilizePromptCache` ; la conversion des autres modèles et destinations, ainsi que le transfert Anthropic natif, restent inchangés. La réutilisation du cache exige toujours une identité de session stable et un cache disponible en amont. Les changements des instructions ou outils antérieurs et la compaction de la conversation peuvent aussi affecter les succès du cache ; préserver l’ordre des rappels ne suffit pas à garantir sa réutilisation.
+Sur toutes les routes Chat traduites, les rappels de l’historique conservent leur position dans la conversation, après les résultats d’outils encore attendus, et sont transmis avec le rôle `developer`. L’ajout d’un rappel ne réécrit donc pas le prompt système initial, et une instruction placée au milieu de la conversation n’arrive plus avant les tours qu’elle était censée suivre. Si le service en amont refuse le rôle `developer`, activez `foldDeveloperRoleToSystem` sur ce fournisseur : le rappel est alors envoyé en `system`, à la même position. Ce comportement s’applique avec ou sans `stabilizePromptCache` ; le transfert Anthropic natif reste inchangé. La réutilisation du cache exige toujours une identité de session stable et un cache disponible en amont. Les changements des instructions ou outils antérieurs et la compaction de la conversation peuvent aussi affecter les succès du cache ; préserver l’ordre des rappels ne suffit pas à garantir sa réutilisation.

docs-site/src/content/docs/fr/reference/configuration/providers.md

@@ -132,6 +132,7 @@ sauvegarde dont le contenu diffère, puis réécrit en identifiants sans préfix
 | `noPenaltyModels?` | `string[]` | Modèles qui rejettent les pénalités presence/frequency. |
 | `noStructuredOutputModels?` | `string[]` | ID de modèle exact dont le point final `openai-chat` rejette `response_format`. Seule une correspondance exacte du modèle demandé omet le champ ; la traduction à sortie structurée reste activée pour tous les autres modèles `openai-chat`. |
 | `noJsonSchemaModels?` | `string[]` | ID de modèle exact dont le point final `openai-chat` rejette un `response_format` `json_schema` mais accepte encore `json_object`. Une telle requête est rétrogradée vers `json_object` au lieu d’être supprimée, donc un appelant qui demande du JSON en reçoit toujours. `noStructuredOutputModels` l’emporte quand un modèle figure dans les deux listes. Les préréglages `opencode go`, `opencode zen` et `opencode free` l’embarquent pour leurs routes DeepSeek. |
+| `foldDeveloperRoleToSystem?` | `boolean` | Envoyer un message `developer` en `system` pour un fournisseur `openai-chat` dont le service en amont refuse le rôle `developer`. Dans les deux cas le message conserve sa position dans la conversation ; seul le rôle change. La valeur par défaut est `false`, donc le rôle standard de Chat Completions est transmis tel quel. |
 | `parallelToolCalls?` | `boolean` | Contrôler les appels d’outils parallèles. Pour `openai-chat`, ils sont activés par défaut ; `false` envoie explicitement `parallel_tool_calls: false`. Les autres adaptateurs ne les annoncent que lorsque la valeur vaut explicitement `true`. |
 | `terminalContinuationGuard?` | `boolean` | Active, pour un fournisseur `openai-chat`, une relance interne bornée lorsqu’un tour exploitable annonce une action puis s’arrête proprement sans appel d’outil. La valeur par défaut est `false`, et une valeur explicite `false` équivaut à l’absence du champ. Les tentatives de combinaison et les tours de compactage routés sont exclus ; les autres adaptateurs ignorent cette option. |
 | `responsesItemIdRepair?` | `{ message?: string[]; reasoning?: string[]; repairMissingTerminalIds?: boolean; repairInvalidIds?: boolean }` | Réparation SSE en aval désactivée par défaut pour les identifiants d'espace réservé exacts, les identifiants de terminal manquants et (avec `repairInvalidIds`) les identifiants message/reasoning manquant du préfixe canonique `msg_`/`rs_`. Les identifiants d’appel de fonction ne sont jamais réécrits. Le DeepSeek intégré active les deux derniers par défaut. |

docs-site/src/content/docs/guides/claude-code.md

@@ -708,12 +708,14 @@ route. Pass `"haiku"` as the model placeholder.
 
 Set `claudeCode.stabilizePromptCache` to `true` in `config.json` to relocate supported trailing Claude harness notices from system instructions to a trailing user message on translated routes. The default is `false`. Enable it only when this role change is appropriate for your clients. It preserves fenced examples and unmatched text; native Anthropic passthrough is unchanged. The metadata-less prompt-cache key then follows stabilized instructions. This does not create conversation identity or guarantee upstream cache hits.
 
-On OpenCode Go's `deepseek-v4.1-flash` Chat route, translated timeline system
-reminders automatically retain their position and system role, after any pending
-tool results. This prevents newly appended reminders from rewriting the leading
-system prompt. It applies with or without `stabilizePromptCache`; other models
-and destinations keep their existing conversion; native Anthropic passthrough
-is unchanged. Cache reuse still requires stable session identity and upstream
-cache availability. Changes to earlier instructions or tools, and conversation
-compaction, can still affect cache hits; preserving reminder order alone does
-not guarantee reuse.
+On every translated Chat route, timeline reminders keep their position in the
+conversation, after any pending tool results, and are forwarded with the
+`developer` role. This prevents a newly appended reminder from rewriting the
+leading system prompt, and stops a mid-conversation instruction from arriving
+ahead of the turns it was written to follow. Set `foldDeveloperRoleToSystem` on
+a provider whose upstream rejects the `developer` role; the reminder is then
+sent as `system` in the same position. This applies with or without
+`stabilizePromptCache`, and native Anthropic passthrough is unchanged. Cache
+reuse still requires stable session identity and upstream cache availability.
+Changes to earlier instructions or tools, and conversation compaction, can still
+affect cache hits; preserving reminder order alone does not guarantee reuse.

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

@@ -146,14 +146,17 @@ An explicit reasoning effort of `none` survives Chat conversion. Output limits a
 controls are preserved for generic API-key Responses targets; the canonical ChatGPT target
 still applies its own restrictions. This does not make all providers' controls equivalent.
 
-**Audio and files need a native input wire that supports them.** OpenCodex does not yet have
-a lossless audio/file carrier for translated requests. When Chat requires projection, or a
-Responses request targets a translated adapter, recognized audio/file attachments return an
-explicit error rather than succeeding without the attachment. File-ID-only images have the
-same restriction because translated adapters cannot resolve those IDs. Convert the attachment
-to text first, or use a native wire and model that support it. Native Chat and raw Responses
-(including Azure) retain their existing behavior; this is not a promise of every model's
-upstream media support. Video conversion limits remain adapter-specific.
+**Audio and most file attachments need a native input wire that supports them.** A document
+that carries its own base64 bytes in a user message is the exception: it survives translation
+and reaches the Anthropic, OpenAI Chat and Google wires as a native document, file part and
+inline data part. Everything else still returns an explicit error rather than succeeding
+without the attachment — audio, a file-ID or remote reference the proxy cannot dereference, an
+attachment in a tool output or a system message, and a document routed to a wire with no byte
+carrier. File-ID-only images have the same restriction because translated adapters cannot
+resolve those IDs. Convert the attachment to text first, or use a native wire and model that
+support it. Native Chat and raw Responses (including Azure) retain their existing behavior;
+this is not a promise of every model's upstream media support. Video conversion limits remain
+adapter-specific.
 
 ## Schema status
 

docs-site/src/content/docs/ja/guides/claude-code.md

@@ -498,4 +498,4 @@ Anthropic バックエンドを明示すると意図的に失敗後停止しま
 
 `config.json` の `claudeCode.stabilizePromptCache` を `true` にすると、変換ルートのシステム指示末尾にある対応済み Claude 通知を最後のユーザーメッセージへ移します。既定値は `false` です。このロール変更が適切なクライアントでのみ有効にしてください。コードフェンス内の例と一致しない本文は保持され、Anthropic のネイティブ転送は変わりません。メタデータがない場合のキャッシュキーは安定化した指示から計算されます。会話 ID の生成やキャッシュヒットの保証は行いません。
 
-OpenCode Go の `deepseek-v4.1-flash` Chat ルートでは、変換されたタイムライン上のシステムリマインダーは、保留中のツール結果の後で位置と system ロールを自動的に維持します。これにより、新しいリマインダーを追加しても先頭のシステムプロンプトが書き換わりません。`stabilizePromptCache` の設定にかかわらず適用され、他のモデルや接続先の変換、および Anthropic のネイティブ転送は変わりません。キャッシュの再利用には、安定したセッション ID と上流キャッシュの利用可能性が引き続き必要です。過去の指示やツールの変更、会話の圧縮もキャッシュヒットに影響します。リマインダーの順序を保つだけで再利用が保証されるわけではありません。
+変換されたすべての Chat ルートで、タイムライン上のリマインダーは保留中のツール結果の後、会話内の元の位置を保ったまま `developer` ロールで転送されます。これにより、新しいリマインダーを追加しても先頭のシステムプロンプトが書き換わらず、会話の途中に置かれた指示がそれより前のターンの前に移動することもありません。上流が `developer` ロールを受け付けない場合は、そのプロバイダーに `foldDeveloperRoleToSystem` を設定してください。同じ位置のまま `system` として送信されます。`stabilizePromptCache` の設定にかかわらず適用され、Anthropic のネイティブ転送は変わりません。キャッシュの再利用には、安定したセッション ID と上流キャッシュの利用可能性が引き続き必要です。過去の指示やツールの変更、会話の圧縮もキャッシュヒットに影響します。リマインダーの順序を保つだけで再利用が保証されるわけではありません。