- add shared `EnsureResponsesUsageDetails` helper to patch `usage` objects with:
- `output_tokens_details.reasoning_tokens = 0`
- `input_tokens_details.cached_tokens = 0`
- for both plain JSON and SSE `data:` frames, including multi-line frames
- apply the helper to OpenAI Response format outputs in non-stream and stream paths across executors/plugins so translated payloads consistently include required usage details
- update websocket/completion payload builders to emit default `usage` detail fields for prewarm/finish responses
Closes: #4985
- Introduced `InjectXSearch` in `XAIConfig` to enable automatic injection of the native `x_search` tool when not explicitly declared.
- Updated `XAIExecutor` to honor the `InjectXSearch` configuration, ensuring consistent tool availability.
- Enhanced configuration handling with support for dynamic diffing to track changes in `InjectXSearch`.
- Added comprehensive tests to validate `InjectXSearch` behavior, including preparation and tool choice synchronization.
- Updated example config and documentation to outline `InjectXSearch` usage.
Closes: #4339
- Added logic to `preserveXAIResponsesOutputControls` for retaining supported controls (`max_output_tokens`, `temperature`, `top_p`, `top_k`) during translation.
- Removed unsupported fields such as `stop` where necessary to align with xAI's Responses API.
- Updated tests to validate the preservation and removal of fields across various input scenarios.
- Improved payload configuration handling with additional unit tests for ensuring compatibility with model-specific overrides.
Closes: #4464
- Updated Kimi and Gemini executors to use `TranslateRequestWithCodexMultiAgentV2` for improved multi-agent v2 optimization.
- Enhanced configuration and API server to support `CodexOptimizeMultiAgentV2`.
- Added codex multi-agent V2 optimizations in `config`, `executor`, and `watcher` modules.
- Refactored token counting logic into a reusable `countXAIInputTokens` function for better readability and maintainability.
- Replaced direct encoder usage with structured input handling, including JSON parsing and segment collection.
- Switched tokenizer from `Cl100kBase` to `O200kBase` to support larger contexts.
Closes: #4492
- Added `promoteXAIAdditionalTools` to normalize and migrate `additional_tools` to the top-level `tools` array in XAI request bodies.
- Updated test cases to validate the promotion logic and ensure unsupported `additional_tools` items are excluded from input payloads.
Closes: #4434
- Introduced `normalizeXAIObjectRootUnionBranchTypes` for ensuring object-only branches in root-level unions.
- Updated XAI executor logic to handle additional schema adjustments, ensuring compatibility with stricter validations.
- Extended test coverage to validate schema normalization, including both functional and custom tool scenarios.
Closes: #4397
- Switched from `xaiChatBaseURL` to `xaiCompactBaseURL` for compact requests to avoid 404 errors from CLI chat-proxy.
- Updated headers to use standard API headers for compact endpoints.
- Added `xaiCompactBaseURL` helper function for dedicated compact request base URL resolution.
- Adjusted comments to clarify handling of compact and websocket transports.
Closes: #4376
- Refactored `xaiFunctionParametersNeedSimplification` to identify schemas xAI cannot process, including those with non-object types in unions.
- Limited parameter simplifications to problematic schemas instead of specific tools or namespaces.
- Clarified and updated debug messages to reflect schema rejection and hang prevention.
Closes: #4343
Normalize and drop tool_choice entries that reference tools removed by
normalizeXAITools before injecting native x_search, then allow x_search in
allowed_tools without duplicates so Grok can select the injected tool.
- Added `clientDeclaredTools` to `xaiInternalXSearchResponseFilter` for improved filtering precision.
- Implemented `collectXAIClientDeclaredToolKeys` to register client-declared tools with effective normalization to function calls.
- Prevented leakage of internal traces (e.g., `xs_call-*`) while preserving client-declared tools with overlapping names.
- Introduced multiple test cases to ensure filter correctness and preserve expected WebSocket response outputs.
- Enhanced completed output handling in response filtering.
Closes: #4282 / PR #4284.
xAI Responses does not accept namespace tool containers, so the executor flattens nested tools before forwarding them upstream. The original namespace support in 8b3670b8 moved children to the top level but discarded their namespace identity; ca67caf later retained namespace context only for targeted schema simplification.
Qualify flattened names to avoid collisions, normalize namespaced function-call history, and restore name plus namespace on HTTP and WebSocket responses. This keeps Codex MCP routing intact without changing the existing xAI tool_search filtering policy.
Preserve include=reasoning.encrypted_content, cache reasoning+assistant message
for store:false multi-turn, and accept Grok thinking signatures on Claude→Codex
for grok targets.
Harden replay cache: blob-level reasoning filter, never double-inject assistant
when history has a last message, isolate session keys by downstream API key,
clear cache on non-replayable completed turns, and normalize refusal parts.
- Introduced `logXAIResolvedBaseURL` for consistent logging of resolved upstream base URLs.
- Added helper `xaiBaseURLSource` to classify base URL origins (default, CLI chat proxy, custom).
- Enhanced test suite with `TestXAIBaseURLSource` to cover base URL source classification logic.
- Introduced `using_api` attribute in xAI auth for toggling between official API and CLI chat-proxy paths.
- Updated `xaiChatBaseURL` and `applyXAIChatHeaders` to conditionally apply the appropriate logic based on the `using_api` value.
- Added robust handling of attribute and metadata parsing for `using_api`.
- Extended test suite to cover `using_api` scenarios, including defaults, overrides, and header behaviors.
- Extracted `applyXAIDefaultHeaders` and `applyXAICustomHeaders` for cleaner separation of concerns in API header application.
- Updated `applyXAIChatHeaders` to ensure proper header overrides for CLI chat-proxy-specific configurations.
- Added test case to validate custom headers' ability to override CLI chat-proxy defaults.
- Introduced `xaiChatBaseURL` helper to normalize base URLs for non-media chat requests.
- Added `applyXAIChatHeaders` to handle CLI chat-proxy-specific headers.
- Updated logic to differentiate between default, chat-proxy, and custom gateway base URLs.
- Extended test coverage to validate behavior of headers and base URL handling across scenarios.
Closes: #4182
- Refined tool normalization logic to pass namespace context (`namespaceName`) to `normalizeXAITool`.
- Limited schema simplification to `codex_app.automation_update` to avoid unintended modifications to unrelated tools or namespaces.
- Updated `xaiFunctionParametersNeedSimplification` to match tools by exact namespace and name.
- Enhanced tests to validate correct schema simplification for `codex_app.automation_update` while preserving unrelated tool definitions.
Codex Desktop injects codex_app.automation_update with a large oneOf+$ref
schema. On xAI free/build Responses, that request accepts HTTP but never
emits SSE, so clients hang until cancel.
- Simplify automation_update (and similar large oneOf+$ref schemas) to a
permissive object schema before upstream xAI
- Map subscription free-usage-exhausted 429s to a 24h RetryAfter for
account rotation/cooldown
- Add unit tests for both behaviors
- Replaced hardcoded model allowlist with dynamic model registry metadata lookup.
- Enhanced `xaiSupportsReasoningEffort` to utilize metadata for reasoning capability validation.
- Updated `sanitizeXAIResponsesBody` to log reasoning effort stripping for unsupported models.
- Added unit tests to verify registry-based reasoning effort handling across models, including Grok 4.5.
Closes: #4147
Add Grok-native reasoning replay for Claude-sourced xAI Responses requests. Replay state is scoped by model and session, normalized to reasoning/function_call/custom_tool_call items, and injected with the same tool-call alignment semantics used by Codex.
Include the minimal Grok encrypted_content validator needed on upstream/dev so replay cache entries cannot accept Codex/GPT, Gemini, or Claude signature shapes. Cache completed output items from HTTP, streaming, and WebSocket xAI responses.
Cover two-turn Claude replay, tool_result continuity, valid Grok cache storage, and rejection of Codex-shaped encrypted_content.
* Drop foreign encrypted_content before xAI Grok upstream
xAI Grok accepts provider-native encrypted_content as opaque replay state, but GPT/Codex reasoning signatures, Gemini thoughtSignature blobs, and Claude thinking signatures can all travel through OpenAI Responses-style reasoning.encrypted_content while remaining incompatible with xAI. Forwarding those foreign blobs to Grok causes upstream validation failures, especially when the foreign value is high-entropy enough to look ciphertext-like.
Add a Grok encrypted_content transport validator that stays conservative and shape-oriented:
- require unpadded standard base64 with no foreign characters
- reject obvious GPT/Codex gAAAA reasoning signatures before decode
- reject strict Claude thinking signatures in both official E-form and Antigravity R-form
- reject known Gemini thoughtSignature envelopes by reusing the central Gemini validator, covering Gemini 2.5 field-1 and Gemini 3.x field-2 shapes
- require decoded payloads to be long enough and high-entropy enough to look like native Grok ciphertext
- avoid decrypting, protobuf-parsing, or otherwise interpreting native Grok payloads on the hot path
Wire the validator into the xAI Responses request preparation path for reasoning and compaction input items. Invalid encrypted_content fields are deleted before the request is sent upstream, while the surrounding item is preserved and debug logging records only redacted metadata.
Extend coverage with native Grok corpus preservation, Gemini field-1/field-2 rejection, Claude E-form and R-form rejection, invalid-blob sanitizer tests, and compact/websocket replay preservation. The foreign-provider checks are deliberately narrow so high-entropy Grok blobs are not rejected merely because they look random.
* fix(xai): harden encrypted content sanitizer
- Introduced `ClaudeCodeSessionID` resolution logic, preferring headers over payload metadata.
- Added `ClaudeCodePromptCache` to map sessions to stable prompt cache keys.
- Refactored existing logic to integrate `ClaudeCodePromptCache` for session-based handling.
- Included extensive unit tests to validate session ID extraction, cache reuse, and header prioritization.
- Introduced `xaiRequiresIsolatedConversation` to enforce session ID generation for `grok-composer` models.
- Updated request preparation logic to handle isolated conversations by setting `prompt_cache_key` and `x-grok-conv-id`.
- Added unit tests with coverage for session isolation, stateless models, and explicit `prompt_cache_key` scenarios.
Closes: #3750
- Introduced `xaiNormalizeReasoningSummaryData` and related functions to normalize `reasoning_text` events into `reasoning_summary` shapes for standardization.
- Updated WebSocket and streaming logic to process normalized reasoning summary events correctly.
- Enhanced tests to validate normalization, order of events, and output structure in both stream and non-stream scenarios.
- Introduced `executeCompact` to handle non-streaming compact responses via the `/responses/compact` endpoint.
- Added `executeCompactionTriggerStream` for streaming responses triggered by `compaction_trigger`.
- Enhanced request preparation with `prepareResponsesRequestTo` for dynamic response formats.
- Updated logic to bypass streaming for `/responses/compact` and added fallback behaviors.
- Added comprehensive tests for compact response handling and event streaming validations.
When Claude Code sends a stop-hook evaluator request (or any request
without tools), the payload includes "tools": [] (empty array). The
claude->codex translator unconditionally emits tools: [] + tool_choice:
"auto" + parallel_tool_calls: true into the Codex Responses shape.
When that payload is routed to xAI, the upstream rejects with HTTP 400:
"A tool_choice was set on the request but no tools were specified."
Fix entirely in the xAI executor (translator package is policy-locked):
add normalizeXAIToolChoiceForTools() after normalizeXAITools() to drop
tool_choice and parallel_tool_calls whenever tools end up absent or
empty (covering both the empty-from-source case and the
all-filtered-out case where every tool was an unsupported type such as
tool_search or image_generation).
Per code-review feedback: always remove parallel_tool_calls when tools
are missing (not gated on tool_choice presence) and existence-check
each key before sjson delete to avoid unnecessary JSON parse/copy.
Verification:
- go build -o test-output ./cmd/server
- go test ./internal/runtime/executor/... -count=1
- 5 new regression tests cover empty / missing / present / orphaned
parallel_tool_calls / no-op-when-both-absent.
