Files
CLIProxyAPI/internal/runtime/executor/xai_executor_request.go
hkfires b4410dd590 fix(executor): enforce payload rules as final barrier
Move Claude prompt-cache stripping before payload finalization so
user-injected values survive, and extract count-tokens betas only
after finalization without changing business semantics.

Capture Codex instructions and xAI transcript input before payload
rules for duplex, replay, and compaction inheritance, and reuse the
exact finalized xAI websocket frame on retries. This prevents rules
from being applied twice, overwritten, or accumulating across turns.
2026-11-16 22:06:14 +08:00

2998 lines
87 KiB
Go

package executor
import (
"bytes"
"context"
"fmt"
"net/http"
"strconv"
"strings"
"sync"
"github.com/MoeForge/moego/json"
"github.com/MoeForge/moego/ojson"
"github.com/google/uuid"
xaiauth "github.com/router-for-me/CLIProxyAPI/v8/internal/auth/xai"
"github.com/router-for-me/CLIProxyAPI/v8/internal/misc"
"github.com/router-for-me/CLIProxyAPI/v8/internal/runtime/executor/helps"
"github.com/router-for-me/CLIProxyAPI/v8/internal/signature"
"github.com/router-for-me/CLIProxyAPI/v8/internal/thinking"
"github.com/router-for-me/CLIProxyAPI/v8/internal/util"
cliproxyauth "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/auth"
cliproxyexecutor "github.com/router-for-me/CLIProxyAPI/v8/sdk/cliproxy/executor"
sdktranslator "github.com/router-for-me/CLIProxyAPI/v8/sdk/translator"
log "github.com/sirupsen/logrus"
)
type xaiPreparedRequest struct {
finalizePayload helps.PayloadFinalizer
applyPatch *helps.ApplyPatchResponsesState
baseModel string
from sdktranslator.Format
responseFormat sdktranslator.Format
to sdktranslator.Format
originalPayload []byte
body []byte
doc *ojson.Doc
namespaceTools map[string]xaiNamespaceToolRef
clientDeclaredTools map[xaiClientToolKey]struct{}
sessionID string
replayScope xaiReasoningReplayScope
filterInternalXSearch bool
webSearchAlias string
}
func (p *xaiPreparedRequest) ensureDoc() *ojson.Doc {
if p == nil {
return nil
}
if p.doc == nil {
p.doc = ojson.NewDoc(p.body)
}
return p.doc
}
// normalizeXAIWebsocketRequestDoc prepares business fields before payload rules.
func normalizeXAIWebsocketRequestDoc(doc *ojson.Doc) {
_ = doc.Delete("stream")
_ = doc.Delete("stream_options")
_ = doc.Delete("background")
_ = doc.Set("store", true)
if strings.TrimSpace(doc.Get("previous_response_id").String()) != "" {
_ = doc.Delete("instructions")
}
}
type xaiNamespaceToolRef struct {
namespace string
name string
isDispatcher bool
children map[string]struct{}
}
// xaiClientToolKey identifies a client-declared callable tool using the
// post-restore Responses shape (short name + optional namespace) and the
// effective upstream tool type after normalizeXAITool (client custom tools are
// sent as function). Response call types are matched against this effective
// kind so internal custom_tool_call traces are not exempted merely because a
// client declared an ordinary function/custom tool with the same short name,
// while legitimate function_call responses for normalized custom tools are kept.
type xaiClientToolKey struct {
namespace string
name string
toolType string
}
func resolveXAISignatureTargetModel(baseModel string, req cliproxyexecutor.Request, opts cliproxyexecutor.Options) string {
if resolved := resolveResponsesSignatureTargetModel(baseModel, req, opts); signature.SignatureProviderFromModelName(resolved) == signature.SignatureProviderGrok {
return resolved
}
return "grok"
}
func (e *XAIExecutor) prepareResponsesRequest(ctx context.Context, req cliproxyexecutor.Request, opts cliproxyexecutor.Options, stream bool) (*xaiPreparedRequest, error) {
return e.prepareResponsesRequestTo(ctx, req, opts, stream, sdktranslator.FormatCodex)
}
func (e *XAIExecutor) prepareResponsesRequestDoc(ctx context.Context, req cliproxyexecutor.Request, opts cliproxyexecutor.Options, stream bool) (*xaiPreparedRequest, error) {
return e.prepareResponsesRequestToDoc(ctx, req, opts, stream, sdktranslator.FormatCodex)
}
func (e *XAIExecutor) prepareResponsesRequestTo(ctx context.Context, req cliproxyexecutor.Request, opts cliproxyexecutor.Options, stream bool, to sdktranslator.Format) (*xaiPreparedRequest, error) {
prepared, err := e.prepareResponsesRequestToDoc(ctx, req, opts, stream, to)
if err != nil {
return nil, err
}
if prepared.doc != nil {
prepared.body = prepared.doc.Bytes()
}
return prepared, nil
}
func (e *XAIExecutor) prepareResponsesRequestToDoc(ctx context.Context, req cliproxyexecutor.Request, opts cliproxyexecutor.Options, stream bool, to sdktranslator.Format) (*xaiPreparedRequest, error) {
baseModel := thinking.ParseSuffix(req.Model).ModelName
from := opts.SourceFormat
responseFormat := cliproxyexecutor.ResponseFormatOrSource(opts)
originalPayloadSource := req.Payload
if len(opts.OriginalRequest) > 0 {
originalPayloadSource = opts.OriginalRequest
}
originalPayload := bytes.Clone(originalPayloadSource)
targetModel := resolveXAISignatureTargetModel(baseModel, req, opts)
originalTranslated := helps.TranslateRequestWithAPIKeyModelCompatibilityForExecutor(ctx, opts.Headers, e.cfg, e.Identifier(), from, to, targetModel, originalPayload, stream, helps.APIKeyModelIsCompat(req))
origDoc := ojson.NewDoc(originalTranslated)
helps.SetStringIfDifferentDoc(origDoc, "model", baseModel)
preserveXAIResponsesOutputControlsDoc(origDoc, originalPayload, from)
originalTranslated = origDoc.Bytes()
body, updatesChanged, err := helps.TranslateRequestWithAPIKeyModelCompatibilityAndUpdateIntentForExecutor(ctx, opts.Headers, e.cfg, e.Identifier(), from, to, targetModel, bytes.Clone(req.Payload), stream, helps.APIKeyModelIsCompat(req))
if err != nil {
return nil, err
}
doc := ojson.NewDoc(body)
helps.SetStringIfDifferentDoc(doc, "model", baseModel)
preserveXAIResponsesOutputControlsDoc(doc, req.Payload, from)
if err = helps.ApplyRequestThinkingDoc(doc, req, opts, from.String(), e.Identifier(), e.Identifier(), updatesChanged); err != nil {
return nil, err
}
finalizePayload := helps.NewPayloadFinalizer(e.cfg, e.Identifier(), baseModel, to.String(), "", originalTranslated, req, opts)
helps.SetStringIfDifferentDoc(doc, "model", baseModel)
helps.SetBoolIfDifferentDoc(doc, "stream", stream)
_ = doc.Delete("previous_response_id")
_ = doc.Delete("prompt_cache_retention")
_ = doc.Delete("safety_identifier")
_ = doc.Delete("stream_options")
helps.RewriteCodexMultiAgentV2InputDoc(doc, ctx, opts.Headers, e.cfg)
applyPatch := helps.NewApplyPatchResponsesState(from, originalPayload, originalTranslated)
if errNormalizePatch := helps.NormalizeApplyPatchResponsesRequestDoc(doc, originalPayload); errNormalizePatch != nil {
return nil, errNormalizePatch
}
willInjectXSearch := e.cfg != nil && e.cfg.XAI.InjectXSearch
shouldFold := xaiShouldFoldNamespaceToolsDoc(doc, willInjectXSearch)
namespaceTools := collectXAINamespaceToolRefsWithFoldDoc(doc, shouldFold)
for name, ref := range namespaceTools {
if ref.isDispatcher {
applyPatch.AddDispatcher(name, ref.namespace)
}
}
// Collect before normalizeXAITools flattens namespace wrappers so keys match
// the post-restore (namespace, short-name) shape used by the response filter.
clientDeclaredTools := collectXAIClientDeclaredToolKeysDoc(doc)
normalizeXAIToolsWithFoldDoc(doc, shouldFold)
promoteXAIAdditionalToolsDoc(doc)
var webSearchAlias string
if xaiHasClientWebSearchFunctionDoc(doc, namespaceTools) {
webSearchAlias = xaiResolveClientWebSearchAliasDoc(doc)
aliasXAIClientWebSearchFunctionDoc(doc, webSearchAlias, namespaceTools)
}
// Drop choices that point at tools removed by normalizeXAITools before any
// configured x_search injection, so no surviving choice references a deleted tool.
normalizeXAINamespaceToolChoiceWithFoldDoc(doc, shouldFold)
// Prune before rewriting hosted tool choices so older models that still
// strip the tool do not keep a leftover "required" selection.
pruneXAIOrphanedToolChoiceDoc(doc)
normalizeXAIForcedWebSearchToolChoiceDoc(doc)
normalizeXAIForcedImageGenerationToolChoiceDoc(doc)
normalizeXAIToolChoiceForToolsDoc(doc)
// Skip x_search injection when the request was forced to a hosted tool and
// the remaining tools list is only that hosted tool. "required" plus extra
// tools would let Grok call x_search instead of the forced hosted tool.
if e.cfg != nil && e.cfg.XAI.InjectXSearch && !xaiToolChoiceRequiresHostedToolOnlyAnyDoc(doc) {
ensureXAINativeXSearchToolDoc(doc)
}
clampXAIToolsLimitDoc(doc, xaiMaxTools, namespaceTools)
var replayScope xaiReasoningReplayScope
replayScope, _, err = applyXAIReasoningReplayCacheRequiredDoc(ctx, from, req, opts, doc)
if err != nil {
return nil, err
}
normalizeXAIInputCustomToolCallsDoc(doc)
normalizeXAIInputNamespaceToolCallsWithFoldDoc(doc, shouldFold)
if webSearchAlias != "" {
aliasXAIClientWebSearchInputDoc(doc, webSearchAlias, namespaceTools)
}
normalizeXAIInputReasoningItemsDoc(doc)
sanitizeXAIInputEncryptedContentWithOptionsDoc(doc, true)
normalizeCodexInstructionsDoc(doc)
// stop is supported by Chat Completions but not by xAI's Responses API.
// Thinking was handled before payload overrides and must not be revalidated here.
_ = doc.Delete("stop")
if xaiBytesMayContainImageRef(body) {
normalizeXAIImageRefsDoc(doc)
}
sessionID, errSession := xaiResolveComposerSessionID(ctx, req, opts, baseModel)
if errSession != nil {
return nil, errSession
}
if sessionID != "" {
helps.SetStringIfDifferentDoc(doc, "prompt_cache_key", sessionID)
}
return &xaiPreparedRequest{
finalizePayload: finalizePayload,
applyPatch: applyPatch,
baseModel: baseModel,
from: from,
responseFormat: responseFormat,
to: to,
originalPayload: originalPayload,
doc: doc,
namespaceTools: namespaceTools,
clientDeclaredTools: clientDeclaredTools,
sessionID: sessionID,
replayScope: replayScope,
filterInternalXSearch: xaiRequestHasNativeXSearchDoc(doc),
webSearchAlias: webSearchAlias,
}, nil
}
func (e *XAIExecutor) recordXAIRequest(ctx context.Context, auth *cliproxyauth.Auth, url string, headers http.Header, body []byte) {
var authID, authLabel, authType, authValue string
if auth != nil {
authID = auth.ID
authLabel = auth.Label
authType, authValue = auth.AccountInfo()
}
helps.RecordAPIRequest(ctx, e.cfg, helps.UpstreamRequestLog{
URL: url,
Method: http.MethodPost,
Headers: headers,
Body: body,
Provider: e.Identifier(),
AuthID: authID,
AuthLabel: authLabel,
AuthType: authType,
AuthValue: authValue,
})
}
func xaiCreds(auth *cliproxyauth.Auth) (token, baseURL string) {
if auth == nil {
return "", ""
}
if auth.Attributes != nil {
token = strings.TrimSpace(auth.Attributes["api_key"])
baseURL = strings.TrimSpace(auth.Attributes["base_url"])
}
if auth.Metadata != nil {
if token == "" {
token = xaiMetadataString(auth.Metadata, "access_token")
}
if baseURL == "" {
baseURL = xaiMetadataString(auth.Metadata, "base_url")
}
}
return token, baseURL
}
// xaiUsingAPI reports whether this xAI auth should use the official API path
// for HTTP chat and media. OAuth defaults to false to use Grok Build.
func xaiUsingAPI(auth *cliproxyauth.Auth) bool {
if auth == nil {
return true
}
if len(auth.Attributes) > 0 {
if raw := strings.TrimSpace(auth.Attributes[xaiUsingAPIAttr]); raw != "" {
parsed, errParse := strconv.ParseBool(raw)
if errParse == nil {
return parsed
}
}
}
if len(auth.Metadata) > 0 {
raw, ok := auth.Metadata[xaiUsingAPIAttr]
if ok && raw != nil {
switch v := raw.(type) {
case bool:
return v
case string:
parsed, errParse := strconv.ParseBool(strings.TrimSpace(v))
if errParse == nil {
return parsed
}
default:
}
}
}
if raw := strings.TrimSpace(auth.Attributes["auth_kind"]); raw != "" {
return !strings.EqualFold(raw, "oauth")
}
return !strings.EqualFold(xaiMetadataString(auth.Metadata, "auth_kind"), "oauth")
}
// xaiChatBaseURL returns the base URL for xAI HTTP chat and media (image/video) requests.
// When auth using_api is true, the official API base URL logic is used. When it
// is false (including its OAuth default), empty or official default base_url is
// rewritten to the CLI chat-proxy endpoint; an explicit non-default base_url is
// still honored.
// Websocket, compact, and speech intentionally do not use this helper:
// cli-chat-proxy does not implement /responses/compact (404), websocket
// upgrades (405), or /tts. Speech uses xaiSpeechRequestURL.
func xaiChatBaseURL(auth *cliproxyauth.Auth) string {
_, baseURL := xaiCreds(auth)
if xaiUsingAPI(auth) {
if baseURL == "" {
return xaiauth.DefaultAPIBaseURL
}
return baseURL
}
if baseURL != "" && !xaiIsDefaultAPIBaseURL(baseURL) {
return baseURL
}
return xaiauth.CLIChatProxyBaseURL
}
// xaiCompactBaseURL returns the base URL for xAI /responses/compact requests.
// Compact must stay on the official API (or an explicit non-CLI-proxy base_url).
// Reusing xaiChatBaseURL would pin OAuth traffic to cli-chat-proxy, which returns
// 404 for /responses/compact and then cools down the auth pool as not_found.
func xaiCompactBaseURL(auth *cliproxyauth.Auth) string {
_, baseURL := xaiCreds(auth)
if baseURL == "" || xaiIsCLIChatProxyBaseURL(baseURL) {
return xaiauth.DefaultAPIBaseURL
}
return baseURL
}
func xaiNormalizeBaseURL(baseURL string) string {
return strings.TrimRight(strings.TrimSpace(baseURL), "/")
}
func xaiIsDefaultAPIBaseURL(baseURL string) bool {
return xaiNormalizeBaseURL(baseURL) == xaiNormalizeBaseURL(xaiauth.DefaultAPIBaseURL)
}
func xaiIsCLIChatProxyBaseURL(baseURL string) bool {
return xaiNormalizeBaseURL(baseURL) == xaiNormalizeBaseURL(xaiauth.CLIChatProxyBaseURL)
}
// xaiBaseURLSource classifies a resolved xAI base URL for logging.
func xaiBaseURLSource(baseURL string) string {
switch {
case xaiIsDefaultAPIBaseURL(baseURL):
return "DefaultAPIBaseURL"
case xaiIsCLIChatProxyBaseURL(baseURL):
return "CLIChatProxyBaseURL"
default:
return "custom"
}
}
// logXAIResolvedBaseURL emits a console log for the resolved upstream base URL.
func logXAIResolvedBaseURL(ctx context.Context, baseURL string) {
helps.LogWithRequestID(ctx).Infof("xai: using base_url=%s source=%s", baseURL, xaiBaseURLSource(baseURL))
}
func xaiDefaultUserAgent() string {
return "xai-grok-workspace/" + xaiClientVersion()
}
func ensureXAIUserAgent(r *http.Request, clientHeaders ...http.Header) {
if r == nil {
return
}
misc.EnsureHeader(r.Header, util.ResolveClientHeaders(r, clientHeaders...), "User-Agent", xaiDefaultUserAgent())
}
func applyXAIHeaders(r *http.Request, auth *cliproxyauth.Auth, token string, stream bool, sessionID string, clientHeaders ...http.Header) {
applyXAIDefaultHeaders(r, token, stream, sessionID)
ensureXAIUserAgent(r, clientHeaders...)
applyXAICustomHeaders(r, auth, clientHeaders...)
}
func applyXAIDefaultHeaders(r *http.Request, token string, stream bool, sessionID string) {
r.Header.Set("Content-Type", "application/json")
if strings.TrimSpace(token) != "" {
r.Header.Set("Authorization", "Bearer "+token)
} else {
r.Header.Del("Authorization")
}
if stream {
r.Header.Set("Accept", "text/event-stream")
} else {
r.Header.Set("Accept", "application/json")
}
r.Header.Set("Connection", "Keep-Alive")
if sessionID != "" {
r.Header.Set("x-grok-conv-id", sessionID)
}
}
func applyXAICustomHeaders(r *http.Request, auth *cliproxyauth.Auth, clientHeaders ...http.Header) {
var attrs map[string]string
if auth != nil {
attrs = auth.Attributes
}
util.ApplyCustomHeadersFromAttrs(r, attrs, clientHeaders...)
}
// applyXAIChatHeaders applies standard xAI headers for non-image/video chat
// requests. When using_api is true or a custom non-CLI-proxy base URL is used,
// this matches the standard applyXAIHeaders behavior (forwarding the downstream
// User-Agent or falling back to the Grok workspace User-Agent). CLI chat-proxy
// identity headers are only attached when using_api is false and the resolved
// chat base URL is the official CLI chat-proxy endpoint.
func applyXAIChatHeaders(r *http.Request, auth *cliproxyauth.Auth, token string, stream bool, sessionID string, clientHeaders ...http.Header) {
if xaiUsingAPI(auth) || !xaiIsCLIChatProxyBaseURL(xaiChatBaseURL(auth)) {
applyXAIHeaders(r, auth, token, stream, sessionID, clientHeaders...)
return
}
applyXAIDefaultHeaders(r, token, stream, sessionID)
clientVer := xaiClientVersion()
r.Header.Set(xaiTokenAuthHeader, xaiTokenAuthValue)
r.Header.Set(xaiClientVersionHeader, clientVer)
r.Header.Set("User-Agent", "xai-grok-workspace/"+clientVer)
r.Header.Set(xaiClientIdentifierHeader, xaiClientIdentifierValue)
r.Header.Set(xaiAuthenticateResponseHeader, xaiAuthenticateResponseValue)
applyXAICustomHeaders(r, auth, clientHeaders...)
}
func xaiResolveComposerSessionID(ctx context.Context, req cliproxyexecutor.Request, opts cliproxyexecutor.Options, baseModel string) (string, error) {
if sessionID := xaiExecutionSessionID(req, opts); sessionID != "" {
return sessionID, nil
}
if !xaiRequiresIsolatedConversation(baseModel) {
return "", nil
}
cached, ok, errCache := helps.ClaudeCodePromptCache(ctx, baseModel, req.Payload, opts.Headers)
if errCache != nil {
return "", errCache
}
if ok {
return cached.ID, nil
}
return uuid.NewString(), nil
}
func xaiExecutionSessionID(req cliproxyexecutor.Request, opts cliproxyexecutor.Options) string {
if value := xaiMetadataString(opts.Metadata, cliproxyexecutor.ExecutionSessionMetadataKey); value != "" {
return value
}
if value := xaiMetadataString(req.Metadata, cliproxyexecutor.ExecutionSessionMetadataKey); value != "" {
return value
}
if promptCacheKey := ojson.GetBytesNoCopy(req.Payload, "prompt_cache_key"); promptCacheKey.Exists() {
if value := strings.TrimSpace(promptCacheKey.String()); value != "" {
return value
}
}
return helps.DerivedSessionUUID("xai", opts.Metadata, req.Metadata)
}
func xaiRequiresIsolatedConversation(model string) bool {
return strings.HasPrefix(strings.ToLower(strings.TrimSpace(model)), xaiComposerModelPrefix)
}
func xaiImageEndpointPath(opts cliproxyexecutor.Options) string {
if opts.SourceFormat.String() != xaiImageHandlerType {
return ""
}
path := xaiMetadataString(opts.Metadata, cliproxyexecutor.RequestPathMetadataKey)
if strings.HasSuffix(path, "/images/edits") {
return xaiImagesEditsPath
}
if strings.HasSuffix(path, "/images/generations") {
return xaiImagesGenerationsPath
}
return xaiDefaultImageEndpointPath
}
// normalizeXAIImageRefs rewrites OpenAI-style image object fields to the xAI
// image API shape before the payload is sent upstream:
//
// {"image":{"image_url":"https://..."}} → {"image":{"url":"https://..."}}
//
// Applies to image / images / reference_images anywhere in the JSON tree,
// including nested objects and array items. Does not rewrite chat content
// parts shaped as {"type":"image_url","image_url":{...}}.
func xaiBytesMayContainImageRef(b []byte) bool {
return bytes.Contains(b, []byte(`"image"`)) ||
bytes.Contains(b, []byte(`"images"`)) ||
bytes.Contains(b, []byte(`"reference_images"`)) ||
bytes.Contains(b, []byte(`\u`))
}
func xaiStringMayContainImageRef(s string) bool {
return strings.Contains(s, `"image"`) ||
strings.Contains(s, `"images"`) ||
strings.Contains(s, `"reference_images"`) ||
strings.Contains(s, `\u`)
}
const (
xaiKeyOther uint8 = iota
xaiKeyImage
xaiKeyImages
xaiKeyURL
xaiKeyImageURL
)
const (
xaiValIgnore uint8 = iota
xaiValRefURL
xaiValRefImageURL
xaiValRefNestedURL
)
const (
xaiResolveNone uint8 = iota
xaiResolveURL
xaiResolveImageURL
xaiResolveNestedImageURL
)
type xaiImageRefEdit struct {
path string
url string
resolveMode uint8
setURL bool
hasImageURL bool
valid bool
}
type xaiScanFrame struct {
isObj bool
inKey bool
isImagesArr bool
isImageURLObj bool
keyKind uint8
elemIdx int
keyStart int
keyEnd int
}
type xaiRefCandidate struct {
depth int
hasURL bool
urlNeedsTrim bool
urlMayNeedTrim bool
urlOverflow bool
urlLen int
urlBuf [256]byte
hasImageURL bool
hasImageURLVal bool
imageURLOverflow bool
imageURLNested bool
imageURLLen int
imageURLBuf [256]byte
}
type xaiImageRefScanner struct {
frames []xaiScanFrame
framesBuf [32]xaiScanFrame
refStack []xaiRefCandidate
refStackBuf [2]xaiRefCandidate
inStr bool
strEsc bool
strIsKey bool
curKeyStart int
curKeyHasEsc bool
keyArena []byte
keyArenaBuf [256]byte
valTarget uint8
valHasEsc bool
valHasNonSpace bool
valOverflow bool
valFirstByte byte
valLastByte byte
valLen int
valBuf [256]byte
edits []xaiImageRefEdit
editsBuf [4]xaiImageRefEdit
}
var xaiImageRefScannerPool = sync.Pool{
New: func() any {
return &xaiImageRefScanner{}
},
}
func (s *xaiImageRefScanner) init() {
s.framesBuf[0] = xaiScanFrame{}
s.frames = s.framesBuf[:1]
s.refStack = s.refStackBuf[:0]
s.keyArena = s.keyArenaBuf[:0]
s.inStr = false
s.strEsc = false
s.strIsKey = false
s.curKeyStart = 0
s.curKeyHasEsc = false
s.valTarget = xaiValIgnore
s.edits = s.editsBuf[:0]
}
func (s *xaiImageRefScanner) reset() {
clear(s.edits[:cap(s.edits)])
clear(s.editsBuf[:])
s.edits = nil
clear(s.frames[:cap(s.frames)])
clear(s.framesBuf[:])
s.frames = nil
clear(s.refStack[:cap(s.refStack)])
clear(s.refStackBuf[:])
s.refStack = nil
s.keyArena = nil
}
func (s *xaiImageRefScanner) buildPathUpTo(depth int) string {
var b strings.Builder
for d := 1; d < depth; d++ {
if d > 1 {
b.WriteByte('.')
}
f := &s.frames[d]
if f.isObj {
key := s.keyArena[f.keyStart:f.keyEnd]
for i := 0; i < len(key); i++ {
ch := key[i]
if ch == '.' || ch == '\\' || ch == '|' || ch == '#' || ch == '*' || ch == '?' || ch == '@' ||
(i == 0 && (ch == ':' || ch == '[' || ch == '{' || ch == '!')) {
b.WriteByte('\\')
}
b.WriteByte(ch)
}
} else {
var idxBuf [20]byte
b.Write(strconv.AppendInt(idxBuf[:0], int64(f.elemIdx), 10))
}
}
return b.String()
}
func (s *xaiImageRefScanner) decodeValBuf() string {
raw := s.valBuf[:s.valLen]
if !s.valHasEsc {
return string(raw)
}
var stackQuoted [514]byte
stackQuoted[0] = '"'
copy(stackQuoted[1:], raw)
stackQuoted[1+len(raw)] = '"'
return util.ParseGJSONBytesNoCopy(stackQuoted[:2+len(raw)]).String()
}
func (s *xaiImageRefScanner) finishValString() {
target := s.valTarget
s.valTarget = xaiValIgnore
if len(s.refStack) == 0 {
return
}
ref := &s.refStack[len(s.refStack)-1]
switch target {
case xaiValRefURL:
if !s.valHasEsc && !s.valHasNonSpace {
ref.hasURL = false
ref.urlNeedsTrim = false
ref.urlMayNeedTrim = false
ref.urlOverflow = false
ref.urlLen = 0
return
}
if s.valOverflow {
ref.urlOverflow = true
if !s.valHasEsc && s.valFirstByte > ' ' && s.valFirstByte < 0x80 && s.valLastByte > ' ' && s.valLastByte < 0x80 {
ref.hasURL = true
ref.urlNeedsTrim = false
} else {
ref.urlMayNeedTrim = true
}
return
}
str := s.decodeValBuf()
trimmed := strings.TrimSpace(str)
if trimmed != "" {
ref.hasURL = true
ref.urlNeedsTrim = len(trimmed) != len(str)
ref.urlLen = copy(ref.urlBuf[:], trimmed)
} else {
ref.hasURL = false
ref.urlNeedsTrim = false
ref.urlLen = 0
}
case xaiValRefImageURL, xaiValRefNestedURL:
if target == xaiValRefNestedURL && ref.hasImageURLVal {
return
}
if !s.valHasEsc && !s.valHasNonSpace {
return
}
if s.valOverflow {
ref.hasImageURLVal = true
ref.imageURLOverflow = true
ref.imageURLNested = target == xaiValRefNestedURL
return
}
str := s.decodeValBuf()
trimmed := strings.TrimSpace(str)
if trimmed != "" {
ref.hasImageURLVal = true
ref.imageURLOverflow = false
ref.imageURLNested = target == xaiValRefNestedURL
ref.imageURLLen = copy(ref.imageURLBuf[:], trimmed)
}
}
}
func (s *xaiImageRefScanner) finishRefObject(closingDepth int) {
ref := &s.refStack[len(s.refStack)-1]
s.refStack = s.refStack[:len(s.refStack)-1]
if ref.urlMayNeedTrim {
path := s.buildPathUpTo(closingDepth)
if path != "" {
s.edits = append(s.edits, xaiImageRefEdit{
path: path,
resolveMode: xaiResolveURL,
setURL: true,
hasImageURL: ref.hasImageURL,
})
}
return
}
if ref.hasURL {
if !ref.urlNeedsTrim && !ref.hasImageURL {
return
}
path := s.buildPathUpTo(closingDepth)
if path == "" {
return
}
if ref.urlOverflow {
s.edits = append(s.edits, xaiImageRefEdit{
path: path,
resolveMode: xaiResolveURL,
setURL: ref.urlNeedsTrim,
hasImageURL: ref.hasImageURL,
})
return
}
s.edits = append(s.edits, xaiImageRefEdit{
path: path,
url: strings.Clone(string(ref.urlBuf[:ref.urlLen])),
setURL: true,
hasImageURL: ref.hasImageURL,
})
return
}
if ref.hasImageURLVal {
path := s.buildPathUpTo(closingDepth)
if path == "" {
return
}
if ref.imageURLOverflow {
mode := xaiResolveImageURL
if ref.imageURLNested {
mode = xaiResolveNestedImageURL
}
s.edits = append(s.edits, xaiImageRefEdit{
path: path,
resolveMode: mode,
setURL: true,
hasImageURL: ref.hasImageURL,
})
return
}
s.edits = append(s.edits, xaiImageRefEdit{
path: path,
url: strings.Clone(string(ref.imageURLBuf[:ref.imageURLLen])),
setURL: true,
hasImageURL: ref.hasImageURL,
})
}
}
func (s *xaiImageRefScanner) finishKey() {
d := len(s.frames) - 1
if d <= 0 {
return
}
if s.curKeyHasEsc {
rawKey := s.keyArena[s.curKeyStart:]
var stackQuoted [260]byte
var quoted []byte
if 2+len(rawKey) <= len(stackQuoted) {
stackQuoted[0] = '"'
copy(stackQuoted[1:], rawKey)
stackQuoted[1+len(rawKey)] = '"'
quoted = stackQuoted[:2+len(rawKey)]
} else {
quoted = make([]byte, 2+len(rawKey))
quoted[0] = '"'
copy(quoted[1:], rawKey)
quoted[1+len(rawKey)] = '"'
}
unescaped := util.ParseGJSONBytesNoCopy(quoted).String()
s.keyArena = append(s.keyArena[:s.curKeyStart], unescaped...)
}
f := &s.frames[d]
f.keyStart = s.curKeyStart
f.keyEnd = len(s.keyArena)
keyBytes := s.keyArena[f.keyStart:f.keyEnd]
switch string(keyBytes) {
case "image":
f.keyKind = xaiKeyImage
case "images", "reference_images":
f.keyKind = xaiKeyImages
case "url":
f.keyKind = xaiKeyURL
case "image_url":
f.keyKind = xaiKeyImageURL
default:
f.keyKind = xaiKeyOther
}
}
func (s *xaiImageRefScanner) Write(p []byte) (int, error) {
i := 0
for i < len(p) {
if s.inStr {
if !s.strEsc && !s.strIsKey && s.valTarget == xaiValIgnore {
for i < len(p) && p[i] != '"' && p[i] != '\\' {
i++
}
if i >= len(p) {
break
}
}
c := p[i]
if s.strEsc {
if s.strIsKey {
s.keyArena = append(s.keyArena, c)
} else if s.valTarget != xaiValIgnore {
if !s.valOverflow {
if s.valLen < len(s.valBuf) {
s.valBuf[s.valLen] = c
s.valLen++
} else {
s.valOverflow = true
}
}
s.valLastByte = 0
}
s.strEsc = false
i++
continue
}
if c == '\\' {
if s.strIsKey {
s.curKeyHasEsc = true
s.keyArena = append(s.keyArena, c)
} else if s.valTarget != xaiValIgnore {
s.valHasEsc = true
if !s.valOverflow {
if s.valLen < len(s.valBuf) {
s.valBuf[s.valLen] = c
s.valLen++
} else {
s.valOverflow = true
}
}
s.valLastByte = 0
}
s.strEsc = true
i++
continue
}
if c == '"' {
s.inStr = false
if s.strIsKey {
s.strIsKey = false
s.finishKey()
} else if s.valTarget != xaiValIgnore {
s.finishValString()
}
i++
continue
}
if s.strIsKey {
s.keyArena = append(s.keyArena, c)
} else if s.valTarget != xaiValIgnore {
if s.valLen == 0 && !s.valOverflow {
s.valFirstByte = c
}
if c != ' ' && c != '\t' && c != '\r' && c != '\n' {
s.valHasNonSpace = true
}
s.valLastByte = c
if !s.valOverflow {
if s.valLen < len(s.valBuf) {
s.valBuf[s.valLen] = c
s.valLen++
} else {
s.valOverflow = true
}
}
}
i++
continue
}
for i < len(p) && (p[i] == ' ' || p[i] == '\t' || p[i] == '\r' || p[i] == '\n') {
i++
}
if i >= len(p) {
break
}
c := p[i]
d := len(s.frames) - 1
switch c {
case ':':
if d > 0 {
s.frames[d].inKey = false
}
i++
case ',':
if d > 0 {
if s.frames[d].isObj {
s.frames[d].inKey = true
} else {
s.frames[d].elemIdx++
}
}
i++
case '}', ']':
if d > 0 {
if len(s.refStack) > 0 && s.refStack[len(s.refStack)-1].depth == d {
s.finishRefObject(d)
}
s.keyArena = s.keyArena[:s.frames[d-1].keyEnd]
s.frames = s.frames[:d]
}
i++
case '"':
s.inStr = true
s.strEsc = false
if d > 0 && s.frames[d].isObj && s.frames[d].inKey {
s.strIsKey = true
s.valTarget = xaiValIgnore
s.curKeyStart = s.frames[d-1].keyEnd
s.curKeyHasEsc = false
s.keyArena = s.keyArena[:s.curKeyStart]
} else {
s.strIsKey = false
s.valTarget = xaiValIgnore
if len(s.refStack) > 0 {
ref := &s.refStack[len(s.refStack)-1]
if d == ref.depth && s.frames[d].isObj {
switch s.frames[d].keyKind {
case xaiKeyURL:
s.valTarget = xaiValRefURL
case xaiKeyImageURL:
ref.hasImageURL = true
s.valTarget = xaiValRefImageURL
}
} else if d == ref.depth+1 && s.frames[d].isImageURLObj && s.frames[d].keyKind == xaiKeyURL {
s.valTarget = xaiValRefNestedURL
}
if s.valTarget != xaiValIgnore {
s.valHasEsc = false
s.valHasNonSpace = false
s.valOverflow = false
s.valFirstByte = 0
s.valLastByte = 0
s.valLen = 0
}
}
}
i++
case '{', '[':
isImagesArr := false
isImageURLObj := false
isRefObj := false
if d > 0 {
parent := &s.frames[d]
if len(s.refStack) > 0 {
ref := &s.refStack[len(s.refStack)-1]
if d == ref.depth && parent.isObj && parent.keyKind == xaiKeyImageURL {
ref.hasImageURL = true
if c == '{' {
isImageURLObj = true
}
}
}
if c == '{' {
if (parent.isObj && parent.keyKind == xaiKeyImage) || (!parent.isObj && parent.isImagesArr) {
isRefObj = true
}
} else if c == '[' && parent.isObj && parent.keyKind == xaiKeyImages {
isImagesArr = true
}
}
prevKeyEnd := 0
if d > 0 {
prevKeyEnd = s.frames[d].keyEnd
}
newDepth := len(s.frames)
s.frames = append(s.frames, xaiScanFrame{
isObj: c == '{',
inKey: c == '{',
isImagesArr: isImagesArr,
isImageURLObj: isImageURLObj,
keyStart: prevKeyEnd,
keyEnd: prevKeyEnd,
})
if isRefObj {
s.refStack = append(s.refStack, xaiRefCandidate{depth: newDepth})
}
i++
default:
if d > 0 && len(s.refStack) > 0 {
ref := &s.refStack[len(s.refStack)-1]
if d == ref.depth && s.frames[d].isObj && s.frames[d].keyKind == xaiKeyImageURL {
ref.hasImageURL = true
}
}
i++
}
}
return len(p), nil
}
func isSkippedUnderDeletedXAIImageURL(path string, edits []xaiImageRefEdit) bool {
for i := range edits {
outer := &edits[i]
if !outer.valid || !outer.hasImageURL || outer.path == "" || len(path) <= len(outer.path)+11 {
continue
}
if strings.HasPrefix(path, outer.path) && strings.HasPrefix(path[len(outer.path):], ".image_url.") {
return true
}
}
return false
}
func normalizeXAIImageRefsDoc(doc *ojson.Doc) bool {
if doc == nil || doc.Len() == 0 {
return false
}
scanner := xaiImageRefScannerPool.Get().(*xaiImageRefScanner)
scanner.init()
defer func() {
scanner.reset()
xaiImageRefScannerPool.Put(scanner)
}()
_, _ = doc.WriteTo(scanner)
if len(scanner.edits) == 0 {
return false
}
for i := range scanner.edits {
edit := &scanner.edits[i]
switch edit.resolveMode {
case xaiResolveNone:
edit.valid = true
case xaiResolveURL:
urlRes := doc.Get(edit.path + ".url")
var orig string
if urlRes.Type == ojson.String {
orig = urlRes.String()
}
trimmed := strings.TrimSpace(orig)
if trimmed == "" {
imgRes := doc.Get(edit.path + ".image_url")
if imgRes.Type == ojson.String {
trimmed = strings.TrimSpace(imgRes.String())
} else if imgRes.IsObject() {
if nested := imgRes.Get("url"); nested.Type == ojson.String {
trimmed = strings.TrimSpace(nested.String())
}
}
if trimmed == "" {
continue
}
edit.setURL = true
} else if !edit.hasImageURL && trimmed == orig {
continue
} else {
edit.setURL = trimmed != orig
}
edit.url = trimmed
edit.valid = true
case xaiResolveImageURL:
edit.url = strings.TrimSpace(doc.Get(edit.path + ".image_url").String())
if edit.url != "" {
edit.valid = true
}
case xaiResolveNestedImageURL:
edit.url = strings.TrimSpace(doc.Get(edit.path + ".image_url.url").String())
if edit.url != "" {
edit.valid = true
}
}
}
changed := false
for i := range scanner.edits {
edit := &scanner.edits[i]
if !edit.valid || isSkippedUnderDeletedXAIImageURL(edit.path, scanner.edits) {
continue
}
if edit.setURL {
if errSet := doc.Set(edit.path+".url", edit.url); errSet == nil {
changed = true
}
}
if edit.hasImageURL {
if errDel := doc.Delete(edit.path + ".image_url"); errDel == nil {
changed = true
}
}
}
return changed
}
func normalizeXAIImageRefs(body []byte) []byte {
if !xaiBytesMayContainImageRef(body) || !ojson.ValidBytes(body) {
return body
}
doc := ojson.NewDoc(body)
if !normalizeXAIImageRefsDoc(doc) {
return body
}
return doc.Bytes()
}
func xaiIsVideoRequest(opts cliproxyexecutor.Options) bool {
return opts.SourceFormat.String() == xaiVideoHandlerType
}
func xaiIsSpeechRequest(opts cliproxyexecutor.Options) bool {
return opts.SourceFormat.String() == xaiSpeechHandlerType
}
// xaiSpeechRequestURL stays on the official API. cli-chat-proxy does not implement /tts,
// and a 404 there would cool the OAuth auth down as not_found.
func xaiSpeechRequestURL(auth *cliproxyauth.Auth) string {
return strings.TrimSuffix(xaiCompactBaseURL(auth), "/") + xaiTTSPath
}
func xaiVideoEndpointPath(opts cliproxyexecutor.Options) string {
if !xaiIsVideoRequest(opts) {
return ""
}
path := xaiMetadataString(opts.Metadata, cliproxyexecutor.RequestPathMetadataKey)
if strings.HasSuffix(path, "/videos/edits") {
return xaiVideosEditsPath
}
if strings.HasSuffix(path, "/videos/extensions") {
return xaiVideosExtensionsPath
}
if strings.HasSuffix(path, "/videos/generations") {
return xaiVideosGenerationsPath
}
return ""
}
func xaiMetadataString(meta map[string]any, key string) string {
if len(meta) == 0 || key == "" {
return ""
}
value, ok := meta[key]
if !ok || value == nil {
return ""
}
switch typed := value.(type) {
case string:
return strings.TrimSpace(typed)
case fmt.Stringer:
return strings.TrimSpace(typed.String())
default:
return strings.TrimSpace(fmt.Sprint(typed))
}
}
func preserveXAIResponsesOutputControls(body, source []byte, from sdktranslator.Format) []byte {
doc := ojson.NewDoc(body)
if !preserveXAIResponsesOutputControlsDoc(doc, source, from) {
return body
}
return doc.Bytes()
}
func preserveXAIResponsesOutputControlsDoc(doc *ojson.Doc, source []byte, from sdktranslator.Format) bool {
if doc == nil {
return false
}
var maxOutputTokens ojson.Result
switch from {
case sdktranslator.FormatOpenAI:
maxOutputTokens = ojson.GetBytesNoCopy(source, "max_completion_tokens")
if !maxOutputTokens.Exists() || maxOutputTokens.Type == ojson.Null {
maxOutputTokens = ojson.GetBytesNoCopy(source, "max_tokens")
}
case sdktranslator.FormatOpenAIResponse:
maxOutputTokens = ojson.GetBytesNoCopy(source, "max_output_tokens")
default:
return false
}
changed := false
if maxOutputTokens.Exists() && maxOutputTokens.Type != ojson.Null {
if doc.SetRawBytes("max_output_tokens", []byte(maxOutputTokens.Raw)) == nil {
changed = true
}
}
for _, field := range []string{"temperature", "top_p", "top_k"} {
value := ojson.GetBytesNoCopy(source, field)
if value.Exists() && value.Type != ojson.Null {
if doc.SetRawBytes(field, []byte(value.Raw)) == nil {
changed = true
}
}
}
return changed
}
// xaiGrokImageGenerationMinVersion is the first Grok line that accepts xAI's
// native Responses image_generation tool. Older conversation models still
// reject that hosted type, so the executor keeps stripping it there.
var xaiGrokImageGenerationMinVersion = xaiGrokVersion{major: 4, minor: 6}
type xaiGrokVersion struct {
major int
minor int
}
// xaiSupportsNativeImageGeneration reports whether the Grok model accepts
// xAI's native Responses image_generation tool. grok-4.20-* is an older
// product line whose dotted minor is not comparable to grok-4.6.
func xaiSupportsNativeImageGeneration(model string) bool {
name := strings.ToLower(strings.TrimSpace(thinking.ParseSuffix(model).ModelName))
if idx := strings.LastIndex(name, "/"); idx >= 0 {
name = name[idx+1:]
}
if name == "" || !strings.HasPrefix(name, "grok-") {
return false
}
rest := strings.TrimPrefix(name, "grok-")
if rest == "4.20" || strings.HasPrefix(rest, "4.20-") {
return false
}
ver, ok := xaiParseGrokVersionPrefix(rest)
if !ok {
return false
}
return xaiCompareGrokVersion(ver, xaiGrokImageGenerationMinVersion) >= 0
}
func xaiParseGrokVersionPrefix(rest string) (xaiGrokVersion, bool) {
i := 0
for i < len(rest) && rest[i] >= '0' && rest[i] <= '9' {
i++
}
if i == 0 {
return xaiGrokVersion{}, false
}
major, err := strconv.Atoi(rest[:i])
if err != nil {
return xaiGrokVersion{}, false
}
if i == len(rest) || rest[i] != '.' {
return xaiGrokVersion{major: major, minor: -1}, true
}
j := i + 1
for j < len(rest) && rest[j] >= '0' && rest[j] <= '9' {
j++
}
if j == i+1 {
return xaiGrokVersion{major: major, minor: -1}, true
}
minor, err := strconv.Atoi(rest[i+1 : j])
if err != nil {
return xaiGrokVersion{}, false
}
return xaiGrokVersion{major: major, minor: minor}, true
}
func xaiCompareGrokVersion(a, b xaiGrokVersion) int {
if a.major != b.major {
if a.major < b.major {
return -1
}
return 1
}
aMinor := a.minor
if aMinor < 0 {
aMinor = 0
}
bMinor := b.minor
if bMinor < 0 {
bMinor = 0
}
if aMinor < bMinor {
return -1
}
if aMinor > bMinor {
return 1
}
return 0
}
// ensureXAINativeXSearchTool appends {"type":"x_search"} when the final tools
// list does not already include native X Search. When tool_choice restricts the
// model to allowed_tools, x_search is also added there (without duplicates) so
// Grok can select the injected tool. When injection is enabled, HTTP and websocket
// executors both prepare payloads through prepareResponsesRequestTo, so this runs
// once before the body is submitted upstream.
func ensureXAINativeXSearchTool(body []byte) []byte {
if !ojson.ValidBytes(body) {
return body
}
doc := ojson.NewDoc(body)
if !ensureXAINativeXSearchToolDoc(doc) {
return body
}
return doc.Bytes()
}
func ensureXAINativeXSearchToolDoc(doc *ojson.Doc) bool {
if doc == nil {
return false
}
changed := false
if !xaiRequestHasNativeXSearchDoc(doc) {
tools := doc.Get("tools")
if !tools.Exists() || !tools.IsArray() {
if doc.SetRawBytes("tools", []byte(`[{"type":"x_search"}]`)) == nil {
changed = true
}
} else {
if doc.SetRawBytes("tools.-1", xaiXSearchToolJSON) == nil {
changed = true
}
}
}
if ensureXAINativeXSearchAllowedToolsDoc(doc) {
changed = true
}
return changed
}
// ensureXAINativeXSearchAllowedTools appends x_search to tool_choice.tools when
// the choice mode is allowed_tools and x_search is not already listed.
func ensureXAINativeXSearchAllowedTools(body []byte) []byte {
doc := ojson.NewDoc(body)
if !ensureXAINativeXSearchAllowedToolsDoc(doc) {
return body
}
return doc.Bytes()
}
func ensureXAINativeXSearchAllowedToolsDoc(doc *ojson.Doc) bool {
if doc == nil {
return false
}
choice := doc.Get("tool_choice")
if !choice.IsObject() || choice.Get("type").String() != "allowed_tools" {
return false
}
allowed := choice.Get("tools")
if !allowed.Exists() || !allowed.IsArray() {
return doc.SetRawBytes("tool_choice.tools", []byte(`[{"type":"x_search"}]`)) == nil
}
for _, tool := range allowed.Array() {
if strings.TrimSpace(tool.Get("type").String()) == xaiXSearchToolType {
return false
}
}
return doc.SetRawBytes("tool_choice.tools.-1", xaiXSearchToolJSON) == nil
}
// xaiHasClientWebSearchFunction reports whether body declares a client function
// or custom tool named "web_search" (without namespace), excluding folded namespace dispatchers.
func xaiHasClientWebSearchFunction(body []byte, namespaceTools map[string]xaiNamespaceToolRef) bool {
if !ojson.ValidBytes(body) {
return false
}
return xaiHasClientWebSearchFunctionResult(ojson.GetBytesNoCopy(body, "tools"), namespaceTools)
}
func xaiHasClientWebSearchFunctionDoc(doc *ojson.Doc, namespaceTools map[string]xaiNamespaceToolRef) bool {
if doc == nil {
return false
}
return xaiHasClientWebSearchFunctionResult(doc.Get("tools"), namespaceTools)
}
func xaiHasClientWebSearchFunctionResult(tools ojson.Result, namespaceTools map[string]xaiNamespaceToolRef) bool {
if !tools.IsArray() {
return false
}
for _, tool := range tools.Array() {
toolType := strings.TrimSpace(tool.Get("type").String())
name := strings.TrimSpace(tool.Get("name").String())
if (toolType == xaiFunctionToolType || toolType == xaiCustomToolType) && name == xaiWebSearchToolType {
if _, isNamespace := namespaceTools[name]; isNamespace {
continue
}
return true
}
}
return false
}
// xaiBodyHasToolNamed reports whether any tool in tools or input has the given name.
func xaiBodyHasToolNamed(body []byte, name string) bool {
return xaiToolsOrInputHaveToolNamed(ojson.GetBytesNoCopy(body, "tools"), ojson.GetBytesNoCopy(body, "input"), name)
}
func xaiBodyHasToolNamedDoc(doc *ojson.Doc, name string) bool {
if doc == nil {
return false
}
return xaiToolsOrInputHaveToolNamed(doc.Get("tools"), doc.Get("input"), name)
}
func xaiToolsOrInputHaveToolNamed(tools, input ojson.Result, name string) bool {
if tools.IsArray() {
for _, tool := range tools.Array() {
if strings.TrimSpace(tool.Get("name").String()) == name {
return true
}
if nested := tool.Get("tools"); nested.IsArray() {
for _, child := range nested.Array() {
if strings.TrimSpace(child.Get("name").String()) == name {
return true
}
}
}
}
}
if input.IsArray() {
for _, item := range input.Array() {
if strings.TrimSpace(item.Get("name").String()) == name {
return true
}
}
}
return false
}
// xaiResolveClientWebSearchAlias picks a candidate alias that does not collide
// with any client tool already present in the request.
func xaiResolveClientWebSearchAlias(body []byte) string {
candidate := xaiClientWebSearchAlias
if !xaiBodyHasToolNamed(body, candidate) {
return candidate
}
for i := 1; ; i++ {
next := fmt.Sprintf("%s_%d", xaiClientWebSearchAlias, i)
if !xaiBodyHasToolNamed(body, next) {
return next
}
}
}
func xaiResolveClientWebSearchAliasDoc(doc *ojson.Doc) string {
candidate := xaiClientWebSearchAlias
if !xaiBodyHasToolNamedDoc(doc, candidate) {
return candidate
}
for i := 1; ; i++ {
next := fmt.Sprintf("%s_%d", xaiClientWebSearchAlias, i)
if !xaiBodyHasToolNamedDoc(doc, next) {
return next
}
}
}
// aliasXAIClientWebSearchInput renames client-declared function calls named
// "web_search" to alias in replayed input history.
func aliasXAIClientWebSearchInput(body []byte, alias string, namespaceTools map[string]xaiNamespaceToolRef) []byte {
if !ojson.ValidBytes(body) || alias == "" {
return body
}
doc := ojson.NewDoc(body)
if !aliasXAIClientWebSearchInputDoc(doc, alias, namespaceTools) {
return body
}
return doc.Bytes()
}
func aliasXAIClientWebSearchInputDoc(doc *ojson.Doc, alias string, namespaceTools map[string]xaiNamespaceToolRef) bool {
if doc == nil || alias == "" {
return false
}
if _, isNamespace := namespaceTools[xaiWebSearchToolType]; isNamespace {
return false
}
input := doc.Get("input")
if !input.IsArray() {
return false
}
changed := false
for idx, item := range input.Array() {
itemType := strings.TrimSpace(item.Get("type").String())
itemName := strings.TrimSpace(item.Get("name").String())
itemNamespace := strings.TrimSpace(item.Get("namespace").String())
if (itemType == "function_call" || itemType == "custom_tool_call" || itemType == "function_call_output") &&
itemName == xaiWebSearchToolType && itemNamespace == "" {
if doc.Set(fmt.Sprintf("input.%d.name", idx), alias) == nil {
changed = true
}
}
}
return changed
}
// aliasXAIClientWebSearchFunction renames client-declared function tools named
// "web_search" to a non-colliding alias in tools declarations, tool_choice,
// and replayed input history to prevent xAI from hijacking them into hosted
// server-side search. Namespace dispatcher tools named "web_search" are untouched.
func aliasXAIClientWebSearchFunction(body []byte, alias string, namespaceTools map[string]xaiNamespaceToolRef) []byte {
if !ojson.ValidBytes(body) || alias == "" {
return body
}
doc := ojson.NewDoc(body)
if !aliasXAIClientWebSearchFunctionDoc(doc, alias, namespaceTools) {
return body
}
return doc.Bytes()
}
func aliasXAIClientWebSearchFunctionDoc(doc *ojson.Doc, alias string, namespaceTools map[string]xaiNamespaceToolRef) bool {
if doc == nil || alias == "" {
return false
}
changed := false
// 1. Alias in tools (excluding namespace dispatchers)
tools := doc.Get("tools")
if tools.IsArray() {
for idx, tool := range tools.Array() {
toolType := strings.TrimSpace(tool.Get("type").String())
name := strings.TrimSpace(tool.Get("name").String())
if (toolType == xaiFunctionToolType || toolType == xaiCustomToolType) && name == xaiWebSearchToolType {
if _, isNamespace := namespaceTools[name]; isNamespace {
continue
}
if doc.Set(fmt.Sprintf("tools.%d.name", idx), alias) == nil {
changed = true
}
}
}
}
// 2. Alias in tool_choice (only when unnamespaced and not a namespace dispatcher)
choice := doc.Get("tool_choice")
if choice.IsObject() {
if fnName := choice.Get("function.name"); fnName.Exists() && strings.TrimSpace(fnName.String()) == xaiWebSearchToolType {
if strings.TrimSpace(choice.Get("function.namespace").String()) == "" {
if _, isNamespace := namespaceTools[xaiWebSearchToolType]; !isNamespace {
if doc.Set("tool_choice.function.name", alias) == nil {
changed = true
}
}
}
}
if name := choice.Get("name"); name.Exists() && strings.TrimSpace(name.String()) == xaiWebSearchToolType {
if strings.TrimSpace(choice.Get("namespace").String()) == "" {
choiceType := strings.TrimSpace(choice.Get("type").String())
if choiceType == xaiFunctionToolType || choiceType == "tool" {
if _, isNamespace := namespaceTools[xaiWebSearchToolType]; !isNamespace {
if doc.Set("tool_choice.name", alias) == nil {
changed = true
}
}
}
}
}
if allowed := choice.Get("tools"); allowed.IsArray() {
for idx, allowedTool := range allowed.Array() {
if strings.TrimSpace(allowedTool.Get("namespace").String()) != "" {
continue
}
if _, isNamespace := namespaceTools[xaiWebSearchToolType]; isNamespace {
continue
}
allowedType := strings.TrimSpace(allowedTool.Get("type").String())
allowedName := strings.TrimSpace(allowedTool.Get("name").String())
if (allowedType == xaiFunctionToolType || allowedType == "tool") && allowedName == xaiWebSearchToolType {
if doc.Set(fmt.Sprintf("tool_choice.tools.%d.name", idx), alias) == nil {
changed = true
}
} else if allowedName == xaiWebSearchToolType && allowedType != xaiWebSearchToolType {
if doc.Set(fmt.Sprintf("tool_choice.tools.%d.name", idx), alias) == nil {
changed = true
}
}
}
}
}
// 3. Alias in input (conversation history, only when unnamespaced)
if aliasXAIClientWebSearchInputDoc(doc, alias, namespaceTools) {
changed = true
}
return changed
}
// normalizeXAIForcedWebSearchToolChoice rewrites web_search choices into a
// ModelToolChoice variant accepted by xAI chat-proxy.
func normalizeXAIForcedWebSearchToolChoice(body []byte) []byte {
return normalizeXAIForcedHostedToolChoice(body, xaiWebSearchToolType)
}
func normalizeXAIForcedWebSearchToolChoiceDoc(doc *ojson.Doc) bool {
return normalizeXAIForcedHostedToolChoiceDoc(doc, xaiWebSearchToolType)
}
// normalizeXAIForcedImageGenerationToolChoice rewrites image_generation choices
// into a ModelToolChoice variant accepted by xAI chat-proxy.
func normalizeXAIForcedImageGenerationToolChoice(body []byte) []byte {
return normalizeXAIForcedHostedToolChoice(body, xaiImageGenerationToolType)
}
func normalizeXAIForcedImageGenerationToolChoiceDoc(doc *ojson.Doc) bool {
return normalizeXAIForcedHostedToolChoiceDoc(doc, xaiImageGenerationToolType)
}
// normalizeXAIForcedHostedToolChoice rewrites choices for a hosted tool (web_search
// or image_generation) into a ModelToolChoice variant accepted by xAI chat-proxy.
// `{type: <toolType>}` becomes the string "required" and the tools list is reduced
// to that hosted tool so later x_search injection cannot broaden the restriction.
// An allowed_tools list that only names that hosted tool becomes the original mode
// ("auto" or "required") and is likewise reduced to that hosted tool. Mixed lists
// drop the hosted tool entry so the remaining hosted/function choices can still
// deserialize.
func normalizeXAIForcedHostedToolChoice(body []byte, toolType string) []byte {
doc := ojson.NewDoc(body)
if !normalizeXAIForcedHostedToolChoiceDoc(doc, toolType) {
return body
}
return doc.Bytes()
}
func normalizeXAIForcedHostedToolChoiceDoc(doc *ojson.Doc, toolType string) bool {
if doc == nil {
return false
}
choice := doc.Get("tool_choice")
if !choice.IsObject() {
return false
}
choiceType := strings.TrimSpace(choice.Get("type").String())
if choiceType == toolType {
changed := xaiKeepOnlyHostedToolsDoc(doc, toolType)
if doc.Set("tool_choice", "required") == nil {
changed = true
}
return changed
}
if choiceType != "allowed_tools" {
return false
}
allowed := choice.Get("tools")
if !allowed.IsArray() {
return false
}
filtered := make([][]byte, 0, len(allowed.Array()))
stripped := false
for _, tool := range allowed.Array() {
if strings.TrimSpace(tool.Get("type").String()) == toolType {
stripped = true
continue
}
filtered = append(filtered, []byte(tool.Raw))
}
if !stripped {
return false
}
if len(filtered) == 0 {
mode := strings.TrimSpace(choice.Get("mode").String())
if mode != "auto" {
mode = "required"
}
changed := xaiKeepOnlyHostedToolsDoc(doc, toolType)
if doc.Set("tool_choice", mode) == nil {
changed = true
}
return changed
}
return doc.SetRawBytes("tool_choice.tools", helps.JoinRawJSONArray(filtered)) == nil
}
func xaiKeepOnlyHostedTools(body []byte, toolType string) []byte {
doc := ojson.NewDoc(body)
if !xaiKeepOnlyHostedToolsDoc(doc, toolType) {
return body
}
return doc.Bytes()
}
func xaiKeepOnlyHostedToolsDoc(doc *ojson.Doc, toolType string) bool {
if doc == nil {
return false
}
tools := doc.Get("tools")
if !tools.IsArray() {
return false
}
kept := make([][]byte, 0, 1)
for _, tool := range tools.Array() {
if strings.TrimSpace(tool.Get("type").String()) == toolType {
kept = append(kept, []byte(tool.Raw))
}
}
if len(kept) == 0 || len(kept) == len(tools.Array()) {
return false
}
return doc.SetRawBytes("tools", helps.JoinRawJSONArray(kept)) == nil
}
func xaiToolChoiceRequiresHostedToolOnly(body []byte, toolType string) bool {
return xaiToolChoiceRequiresHostedToolOnlyResults(ojson.GetBytesNoCopy(body, "tool_choice"), ojson.GetBytesNoCopy(body, "tools"), toolType)
}
func xaiToolChoiceRequiresHostedToolOnlyDoc(doc *ojson.Doc, toolType string) bool {
if doc == nil {
return false
}
return xaiToolChoiceRequiresHostedToolOnlyResults(doc.Get("tool_choice"), doc.Get("tools"), toolType)
}
func xaiToolChoiceRequiresHostedToolOnlyResults(choice, tools ojson.Result, toolType string) bool {
if choice.Type != ojson.String {
return false
}
switch choice.String() {
case "required", "auto":
default:
return false
}
if !tools.IsArray() || len(tools.Array()) == 0 {
return false
}
for _, tool := range tools.Array() {
if strings.TrimSpace(tool.Get("type").String()) != toolType {
return false
}
}
return true
}
func xaiToolChoiceRequiresImageGenerationOnly(body []byte) bool {
return xaiToolChoiceRequiresHostedToolOnly(body, xaiImageGenerationToolType)
}
func xaiToolChoiceRequiresWebSearchOnly(body []byte) bool {
return xaiToolChoiceRequiresHostedToolOnly(body, xaiWebSearchToolType)
}
func xaiToolChoiceRequiresHostedToolOnlyAny(body []byte) bool {
return xaiToolChoiceRequiresImageGenerationOnly(body) || xaiToolChoiceRequiresWebSearchOnly(body)
}
func xaiToolChoiceRequiresHostedToolOnlyAnyDoc(doc *ojson.Doc) bool {
return xaiToolChoiceRequiresHostedToolOnlyDoc(doc, xaiImageGenerationToolType) ||
xaiToolChoiceRequiresHostedToolOnlyDoc(doc, xaiWebSearchToolType)
}
func xaiSetToolChoiceString(body []byte, value string) []byte {
updated, errSet := ojson.SetBytes(body, "tool_choice", value)
if errSet != nil {
return body
}
return updated
}
// pruneXAIOrphanedToolChoice removes tool_choice entries that no longer match
// any remaining tool after normalizeXAITools filtering. Forced choices that
// reference a deleted tool are dropped entirely; allowed_tools lists keep only
// choices that still resolve against the post-normalization tools set.
func pruneXAIOrphanedToolChoice(body []byte) []byte {
if !ojson.ValidBytes(body) {
return body
}
doc := ojson.NewDoc(body)
if !pruneXAIOrphanedToolChoiceDoc(doc) {
return body
}
return doc.Bytes()
}
func pruneXAIOrphanedToolChoiceDoc(doc *ojson.Doc) bool {
if doc == nil {
return false
}
choice := doc.Get("tool_choice")
if !choice.Exists() {
return false
}
available := collectXAIAvailableToolChoiceKeysDoc(doc)
if choice.Type == ojson.String {
// auto / none / required are not tool references.
return false
}
if !choice.IsObject() {
return false
}
choiceType := strings.TrimSpace(choice.Get("type").String())
switch choiceType {
case "allowed_tools":
return pruneXAIAllowedToolsChoiceDoc(doc, available)
default:
if choiceType == "" {
return false
}
if xaiToolChoiceMatchesAvailable(choice, available) {
return false
}
return doc.Delete("tool_choice") == nil
}
}
func pruneXAIAllowedToolsChoice(body []byte, available map[xaiToolChoiceKey]struct{}) []byte {
doc := ojson.NewDoc(body)
if !pruneXAIAllowedToolsChoiceDoc(doc, available) {
return body
}
return doc.Bytes()
}
func pruneXAIAllowedToolsChoiceDoc(doc *ojson.Doc, available map[xaiToolChoiceKey]struct{}) bool {
if doc == nil {
return false
}
allowed := doc.Get("tool_choice.tools")
if !allowed.Exists() || !allowed.IsArray() {
return doc.Delete("tool_choice") == nil
}
allowedItems := allowed.Array()
filtered := make([][]byte, 0, len(allowedItems))
changed := false
for _, tool := range allowedItems {
if !xaiToolChoiceMatchesAvailable(tool, available) {
changed = true
continue
}
filtered = append(filtered, []byte(tool.Raw))
}
if !changed {
return false
}
if len(filtered) == 0 {
return doc.Delete("tool_choice") == nil
}
return doc.SetRawBytes("tool_choice.tools", helps.JoinRawJSONArray(filtered)) == nil
}
// xaiToolChoiceKey identifies a selectable tool the way xAI tool_choice entries
// reference it after namespace qualification: type alone for host tools, or
// type+name for function tools.
type xaiToolChoiceKey struct {
toolType string
name string
}
func collectXAIAvailableToolChoiceKeys(body []byte) map[xaiToolChoiceKey]struct{} {
return collectXAIAvailableToolChoiceKeysResults(ojson.GetBytesNoCopy(body, "tools"), ojson.GetBytesNoCopy(body, "input"))
}
func collectXAIAvailableToolChoiceKeysDoc(doc *ojson.Doc) map[xaiToolChoiceKey]struct{} {
if doc == nil {
return make(map[xaiToolChoiceKey]struct{})
}
return collectXAIAvailableToolChoiceKeysResults(doc.Get("tools"), doc.Get("input"))
}
func collectXAIAvailableToolChoiceKeysResults(toolsResult, inputResult ojson.Result) map[xaiToolChoiceKey]struct{} {
keys := make(map[xaiToolChoiceKey]struct{})
collect := func(tools ojson.Result) {
if !tools.IsArray() {
return
}
for _, tool := range tools.Array() {
toolType := strings.TrimSpace(tool.Get("type").String())
if toolType == "" {
continue
}
key := xaiToolChoiceKey{toolType: toolType}
if toolType == xaiFunctionToolType || toolType == xaiCustomToolType {
key.name = strings.TrimSpace(tool.Get("name").String())
if key.name == "" {
continue
}
}
keys[key] = struct{}{}
}
}
collect(toolsResult)
if inputResult.IsArray() {
for _, item := range inputResult.Array() {
if item.Get("type").String() == "additional_tools" {
collect(item.Get("tools"))
}
}
}
return keys
}
func xaiToolChoiceMatchesAvailable(choice ojson.Result, available map[xaiToolChoiceKey]struct{}) bool {
toolType := strings.TrimSpace(choice.Get("type").String())
if toolType == "" {
return false
}
key := xaiToolChoiceKey{toolType: toolType}
if toolType == xaiFunctionToolType || toolType == xaiCustomToolType {
key.name = strings.TrimSpace(choice.Get("name").String())
if key.name == "" {
return false
}
}
_, ok := available[key]
return ok
}
func xaiCountFlattenedToolsWithSeen(tools ojson.Result, seenFunctionNames map[string]struct{}) int {
if !tools.Exists() || !tools.IsArray() {
return 0
}
count := 0
for _, tool := range tools.Array() {
switch tool.Get("type").String() {
case xaiNamespaceToolType:
namespaceName := tool.Get("name").String()
if nestedTools := tool.Get("tools"); nestedTools.IsArray() {
for _, nestedTool := range nestedTools.Array() {
if nestedTool.Get("type").String() == xaiToolSearchType {
continue
}
qualifiedName := qualifyXAINamespaceToolName(namespaceName, nestedTool.Get("name").String())
if qualifiedName != "" && seenFunctionNames != nil {
if _, seen := seenFunctionNames[qualifiedName]; seen {
continue
}
seenFunctionNames[qualifiedName] = struct{}{}
}
count++
}
} else {
count++
}
case xaiToolSearchType:
// Tool search is stripped by normalizeXAITool
case xaiFunctionToolType, xaiCustomToolType:
name := strings.TrimSpace(tool.Get("name").String())
if name != "" && seenFunctionNames != nil {
if _, seen := seenFunctionNames[name]; seen {
continue
}
seenFunctionNames[name] = struct{}{}
}
count++
default:
count++
}
}
return count
}
func xaiCountFlattenedTools(tools ojson.Result) int {
return xaiCountFlattenedToolsWithSeen(tools, make(map[string]struct{}))
}
func xaiTotalFlattenedToolsCount(body []byte, willInjectXSearch bool) int {
seenFunctionNames := make(map[string]struct{})
count := xaiCountFlattenedToolsWithSeen(ojson.GetBytesNoCopy(body, "tools"), seenFunctionNames)
input := ojson.GetBytesNoCopy(body, "input")
if input.Exists() && input.IsArray() {
for _, item := range input.Array() {
if item.Get("type").String() == "additional_tools" {
count += xaiCountFlattenedToolsWithSeen(item.Get("tools"), seenFunctionNames)
}
}
}
if willInjectXSearch && !xaiRequestHasNativeXSearch(body) && !xaiToolChoiceRequiresHostedToolOnlyAny(body) {
count++
}
return count
}
func xaiTotalFlattenedToolsCountDoc(doc *ojson.Doc, willInjectXSearch bool) int {
if doc == nil {
return 0
}
seenFunctionNames := make(map[string]struct{})
count := xaiCountFlattenedToolsWithSeen(doc.Get("tools"), seenFunctionNames)
input := doc.Get("input")
if input.Exists() && input.IsArray() {
for _, item := range input.Array() {
if item.Get("type").String() == "additional_tools" {
count += xaiCountFlattenedToolsWithSeen(item.Get("tools"), seenFunctionNames)
}
}
}
if willInjectXSearch && !xaiRequestHasNativeXSearchDoc(doc) && !xaiToolChoiceRequiresHostedToolOnlyAnyDoc(doc) {
count++
}
return count
}
func xaiShouldFoldNamespaceTools(body []byte, willInjectXSearch bool) bool {
return xaiTotalFlattenedToolsCount(body, willInjectXSearch) > xaiMaxTools
}
func xaiShouldFoldNamespaceToolsDoc(doc *ojson.Doc, willInjectXSearch bool) bool {
return xaiTotalFlattenedToolsCountDoc(doc, willInjectXSearch) > xaiMaxTools
}
func collectXAINamespaceDeclarationsByName(body []byte) map[string][]ojson.Result {
return collectXAINamespaceDeclarationsByNameResults(ojson.GetBytesNoCopy(body, "tools"), ojson.GetBytesNoCopy(body, "input"))
}
func collectXAINamespaceDeclarationsByNameDoc(doc *ojson.Doc) map[string][]ojson.Result {
if doc == nil {
return make(map[string][]ojson.Result)
}
return collectXAINamespaceDeclarationsByNameResults(doc.Get("tools"), doc.Get("input"))
}
func collectXAINamespaceDeclarationsByNameResults(toolsResult, inputResult ojson.Result) map[string][]ojson.Result {
byName := make(map[string][]ojson.Result)
collect := func(tools ojson.Result) {
if !tools.Exists() || !tools.IsArray() {
return
}
for _, tool := range tools.Array() {
if tool.Get("type").String() != xaiNamespaceToolType {
continue
}
namespaceName := strings.TrimSpace(tool.Get("name").String())
if namespaceName == "" {
continue
}
byName[namespaceName] = append(byName[namespaceName], tool)
}
}
collect(toolsResult)
if inputResult.Exists() && inputResult.IsArray() {
for _, item := range inputResult.Array() {
if item.Get("type").String() == "additional_tools" {
collect(item.Get("tools"))
}
}
}
return byName
}
func buildXAINamespaceDispatcherTool(tool ojson.Result, extraDeclarations ...ojson.Result) []byte {
namespaceName := strings.TrimSpace(tool.Get("name").String())
if namespaceName == "" {
return nil
}
description := strings.TrimSpace(tool.Get("description").String())
declarations := make([]ojson.Result, 0, 1+len(extraDeclarations))
declarations = append(declarations, tool)
declarations = append(declarations, extraDeclarations...)
var toolNames []string
var toolDescriptions []string
seenChildren := make(map[string]struct{})
for _, decl := range declarations {
if description == "" {
description = strings.TrimSpace(decl.Get("description").String())
}
nestedTools := decl.Get("tools")
if !nestedTools.IsArray() {
continue
}
for _, child := range nestedTools.Array() {
if child.Get("type").String() == xaiToolSearchType {
continue
}
childName := strings.TrimSpace(child.Get("name").String())
if childName == "" {
continue
}
if _, exists := seenChildren[childName]; exists {
continue
}
seenChildren[childName] = struct{}{}
toolNames = append(toolNames, childName)
childDesc := strings.TrimSpace(child.Get("description").String())
params := child.Get("parameters")
if !params.Exists() {
params = child.Get("input_schema")
}
var paramStr string
if params.Exists() && params.Raw != "" {
rawParams := strings.TrimSpace(params.Raw)
if rawParams != "" && rawParams != "{}" && rawParams != `{"type":"object","properties":{}}` {
inlined := util.InlineLocalRefs(rawParams)
if ojson.Valid(inlined) {
cleanDoc := ojson.NewDocString(inlined)
if cleanDoc.Get("$defs").Exists() {
_ = cleanDoc.Delete("$defs")
}
if cleanDoc.Get("definitions").Exists() {
_ = cleanDoc.Delete("definitions")
}
paramStr = cleanDoc.String()
} else {
paramStr = inlined
}
}
}
var entry string
if childDesc != "" {
if paramStr != "" {
entry = fmt.Sprintf("- %s: %s\n Parameters: %s", childName, childDesc, paramStr)
} else {
entry = fmt.Sprintf("- %s: %s", childName, childDesc)
}
} else {
if paramStr != "" {
entry = fmt.Sprintf("- %s\n Parameters: %s", childName, paramStr)
} else {
entry = fmt.Sprintf("- %s", childName)
}
}
toolDescriptions = append(toolDescriptions, entry)
}
}
fullDescription := description
if len(toolDescriptions) > 0 {
catalog := "Available tools in this namespace:\n" + strings.Join(toolDescriptions, "\n")
if fullDescription != "" {
fullDescription += "\n\n" + catalog
} else {
fullDescription = fmt.Sprintf("Tools in namespace %s.\n\n%s", namespaceName, catalog)
}
} else if fullDescription == "" {
fullDescription = fmt.Sprintf("Tools in namespace %s.", namespaceName)
}
nameProp := map[string]any{
"type": "string",
"description": fmt.Sprintf("Child tool name to execute in namespace %s", namespaceName),
}
if len(toolNames) > 0 {
nameProp["enum"] = toolNames
}
dispatcher := map[string]any{
"type": xaiFunctionToolType,
"name": namespaceName,
"description": fullDescription,
"parameters": map[string]any{
"type": "object",
"properties": map[string]any{
"name": nameProp,
"arguments": map[string]any{
"type": "object",
"description": "Arguments object matching the parameter schema of the selected child tool",
"additionalProperties": true,
},
},
"required": []string{"name"},
},
}
raw, errMarshal := json.Marshal(dispatcher)
if errMarshal != nil {
return nil
}
return raw
}
func normalizeXAITools(body []byte) []byte {
return normalizeXAIToolsWithFold(body, xaiShouldFoldNamespaceTools(body, false))
}
func normalizeXAIToolsDoc(doc *ojson.Doc) bool {
return normalizeXAIToolsWithFoldDoc(doc, xaiShouldFoldNamespaceToolsDoc(doc, false))
}
func normalizeXAIToolsWithFold(body []byte, shouldFold bool) []byte {
if !ojson.ValidBytes(body) {
return body
}
doc := ojson.NewDoc(body)
if !normalizeXAIToolsWithFoldDoc(doc, shouldFold) {
return body
}
return doc.Bytes()
}
func normalizeXAIToolsWithFoldDoc(doc *ojson.Doc, shouldFold bool) bool {
if doc == nil {
return false
}
keepImageGeneration := xaiSupportsNativeImageGeneration(doc.Get("model").String())
var namespaceDecls map[string][]ojson.Result
if shouldFold {
namespaceDecls = collectXAINamespaceDeclarationsByNameDoc(doc)
}
type pendingSet struct {
path string
raw []byte
}
var updates []pendingSet
planAtPath := func(path string) bool {
tools := doc.Get(path)
if !tools.Exists() || !tools.IsArray() {
return true
}
filtered, changed, ok := normalizeXAIToolArrayWithNamespaces(tools, keepImageGeneration, shouldFold, namespaceDecls)
if !ok {
return false
}
if changed {
updates = append(updates, pendingSet{path: path, raw: filtered})
}
return true
}
if !planAtPath("tools") {
return false
}
input := doc.Get("input")
if input.Exists() && input.IsArray() {
for index, item := range input.Array() {
if item.Get("type").String() != "additional_tools" {
continue
}
if !planAtPath(fmt.Sprintf("input.%d.tools", index)) {
return false
}
}
}
if len(updates) == 0 {
return false
}
for _, u := range updates {
if errSet := doc.SetRawBytes(u.path, u.raw); errSet != nil {
return false
}
}
return true
}
func xaiHasFunctionToolNamed(body []byte, name string) bool {
return xaiHasFunctionToolNamedResults(ojson.GetBytesNoCopy(body, "tools"), ojson.GetBytesNoCopy(body, "input"), name)
}
func xaiHasFunctionToolNamedDoc(doc *ojson.Doc, name string) bool {
if doc == nil {
return false
}
return xaiHasFunctionToolNamedResults(doc.Get("tools"), doc.Get("input"), name)
}
func xaiHasFunctionToolNamedResults(tools, input ojson.Result, name string) bool {
if name == "" {
return false
}
if tools.IsArray() {
for _, tool := range tools.Array() {
if tool.Get("type").String() == xaiFunctionToolType && tool.Get("name").String() == name {
return true
}
}
}
if input.IsArray() {
for _, item := range input.Array() {
if item.Get("type").String() == "additional_tools" {
for _, tool := range item.Get("tools").Array() {
if tool.Get("type").String() == xaiFunctionToolType && tool.Get("name").String() == name {
return true
}
}
}
}
}
return false
}
func clampXAIToolsLimit(body []byte, maxTools int, refs map[string]xaiNamespaceToolRef) []byte {
doc := ojson.NewDoc(body)
if !clampXAIToolsLimitDoc(doc, maxTools, refs) {
return body
}
return doc.Bytes()
}
func clampXAIToolsLimitDoc(doc *ojson.Doc, maxTools int, refs map[string]xaiNamespaceToolRef) bool {
if doc == nil {
return false
}
tools := doc.Get("tools")
if !tools.IsArray() || len(tools.Array()) <= maxTools {
return false
}
allTools := tools.Array()
var dispatcherTools []json.RawMessage
var regularTools []json.RawMessage
for _, tool := range allTools {
name := strings.TrimSpace(tool.Get("name").String())
if ref, ok := refs[name]; ok && ref.isDispatcher {
dispatcherTools = append(dispatcherTools, json.RawMessage(tool.Raw))
} else {
regularTools = append(regularTools, json.RawMessage(tool.Raw))
}
}
capped := make([]json.RawMessage, 0, maxTools)
if len(dispatcherTools) >= maxTools {
capped = append(capped, dispatcherTools[:maxTools]...)
} else {
capped = append(capped, dispatcherTools...)
remainingSlots := maxTools - len(dispatcherTools)
if len(regularTools) > remainingSlots {
capped = append(capped, regularTools[:remainingSlots]...)
} else {
capped = append(capped, regularTools...)
}
}
raw, errMarshal := json.Marshal(capped)
if errMarshal != nil {
return false
}
if errSet := doc.SetRawBytes("tools", raw); errSet != nil {
return false
}
pruneXAIOrphanedToolChoiceDoc(doc)
normalizeXAIToolChoiceForToolsDoc(doc)
return true
}
// xaiDeduplicatedToolName returns the unique name key for tool declarations that
// must not repeat in the final xAI tools list (functions, custom tools, and
// namespace dispatchers). Hosted tools without a function name return "".
func xaiDeduplicatedToolName(tool ojson.Result) string {
switch strings.TrimSpace(tool.Get("type").String()) {
case xaiFunctionToolType, xaiCustomToolType, xaiNamespaceToolType:
return strings.TrimSpace(tool.Get("name").String())
default:
return ""
}
}
// promoteXAIAdditionalTools moves Responses Lite tool declarations to the
// top-level tools array because xAI does not accept additional_tools input items.
// Declarations are deduplicated by tool name with first-wins precedence so
// top-level tools remain authoritative over historical additional_tools copies.
func promoteXAIAdditionalTools(body []byte) []byte {
if !ojson.ValidBytes(body) {
return body
}
doc := ojson.NewDoc(body)
if !promoteXAIAdditionalToolsDoc(doc) {
return body
}
return doc.Bytes()
}
func promoteXAIAdditionalToolsDoc(doc *ojson.Doc) bool {
if doc == nil {
return false
}
input := doc.Get("input")
if !input.IsArray() {
return false
}
inputItems := input.Array()
remainingInput := make([]json.RawMessage, 0, len(inputItems))
promotedTools := make([]ojson.Result, 0)
for _, item := range inputItems {
if item.Get("type").String() != "additional_tools" {
remainingInput = append(remainingInput, json.RawMessage(item.Raw))
continue
}
for _, tool := range item.Get("tools").Array() {
promotedTools = append(promotedTools, tool)
}
}
if len(remainingInput) == len(inputItems) {
return false
}
rawInput, errMarshalInput := json.Marshal(remainingInput)
if errMarshalInput != nil {
return false
}
if len(promotedTools) == 0 {
return doc.SetRawBytes("input", rawInput) == nil
}
topLevelTools := doc.Get("tools")
topLevelArray := topLevelTools.Array()
tools := make([]json.RawMessage, 0, len(topLevelArray)+len(promotedTools))
seenNames := make(map[string]struct{}, len(topLevelArray)+len(promotedTools))
if topLevelTools.IsArray() {
for _, tool := range topLevelArray {
if name := xaiDeduplicatedToolName(tool); name != "" {
if _, exists := seenNames[name]; exists {
continue
}
seenNames[name] = struct{}{}
}
tools = append(tools, json.RawMessage(tool.Raw))
}
}
for _, tool := range promotedTools {
if name := xaiDeduplicatedToolName(tool); name != "" {
if _, exists := seenNames[name]; exists {
continue
}
seenNames[name] = struct{}{}
}
tools = append(tools, json.RawMessage(tool.Raw))
}
rawTools, errMarshalTools := json.Marshal(tools)
if errMarshalTools != nil {
return false
}
if errSetInput := doc.SetRawBytes("input", rawInput); errSetInput != nil {
return false
}
if errSetTools := doc.SetRawBytes("tools", rawTools); errSetTools != nil {
return false
}
return true
}
func normalizeXAIToolArray(tools ojson.Result, keepImageGeneration, shouldFold bool) ([]byte, bool, bool) {
return normalizeXAIToolArrayWithNamespaces(tools, keepImageGeneration, shouldFold, nil)
}
func normalizeXAIToolArrayWithNamespaces(tools ojson.Result, keepImageGeneration, shouldFold bool, namespaceDecls map[string][]ojson.Result) ([]byte, bool, bool) {
toolItems := tools.Array()
filtered := make([][]byte, 0, len(toolItems))
seenNames := make(map[string]struct{}, len(toolItems))
appendUnique := func(raw []byte) bool {
if name := xaiDeduplicatedToolName(util.ParseGJSONBytesNoCopy(raw)); name != "" {
if _, exists := seenNames[name]; exists {
return true
}
seenNames[name] = struct{}{}
}
filtered = append(filtered, raw)
return false
}
changed := false
for _, tool := range toolItems {
toolType := tool.Get("type").String()
if toolType == xaiNamespaceToolType {
changed = true
if shouldFold {
namespaceName := strings.TrimSpace(tool.Get("name").String())
if dispatcher := buildXAINamespaceDispatcherTool(tool, namespaceDecls[namespaceName]...); len(dispatcher) > 0 {
_ = appendUnique(dispatcher)
}
continue
}
namespaceName := tool.Get("name").String()
if namespaceTools := tool.Get("tools"); namespaceTools.IsArray() {
for _, nestedTool := range namespaceTools.Array() {
nestedRaw, nestedChanged, ok := normalizeXAITool(nestedTool, namespaceName, keepImageGeneration)
if !ok {
return nil, false, false
}
changed = changed || nestedChanged
if len(nestedRaw) > 0 {
if appendUnique(nestedRaw) {
changed = true
}
}
}
}
continue
}
raw, toolChanged, ok := normalizeXAITool(tool, "", keepImageGeneration)
if !ok {
return nil, false, false
}
changed = changed || toolChanged
if len(raw) > 0 {
if appendUnique(raw) {
changed = true
}
}
}
if !changed {
return nil, false, true
}
return helps.JoinRawJSONArray(filtered), true, true
}
// normalizeXAIToolChoiceForTools drops tool_choice and parallel_tool_calls
// when tools are absent or empty (including after normalizeXAITools filtering).
// xAI rejects payloads that include tool_choice without any tools defined.
// Existence checks avoid unnecessary sjson parse/copy passes.
func normalizeXAIToolChoiceForTools(body []byte) []byte {
doc := ojson.NewDoc(body)
if !normalizeXAIToolChoiceForToolsDoc(doc) {
return body
}
return doc.Bytes()
}
func normalizeXAIToolChoiceForToolsDoc(doc *ojson.Doc) bool {
if doc == nil {
return false
}
tools := doc.Get("tools")
hasTools := tools.Exists() && tools.IsArray() && len(tools.Array()) > 0
if !hasTools {
input := doc.Get("input")
if input.Exists() && input.IsArray() {
for _, item := range input.Array() {
additionalTools := item.Get("tools")
if item.Get("type").String() == "additional_tools" && additionalTools.IsArray() && len(additionalTools.Array()) > 0 {
hasTools = true
break
}
}
}
}
if hasTools {
return false
}
changed := false
if tools.Exists() {
if doc.Delete("tools") == nil {
changed = true
}
}
if doc.Get("tool_choice").Exists() {
if doc.Delete("tool_choice") == nil {
changed = true
}
}
if doc.Get("parallel_tool_calls").Exists() {
if doc.Delete("parallel_tool_calls") == nil {
changed = true
}
}
return changed
}
// normalizeXAINamespaceToolChoice qualifies namespaced function choices using
// the same names sent in the flattened tools list. xAI does not accept the
// Responses namespace field on tool choices.
func normalizeXAINamespaceToolChoice(body []byte) []byte {
return normalizeXAINamespaceToolChoiceWithFold(body, xaiShouldFoldNamespaceTools(body, false))
}
func normalizeXAINamespaceToolChoiceDoc(doc *ojson.Doc) bool {
return normalizeXAINamespaceToolChoiceWithFoldDoc(doc, xaiShouldFoldNamespaceToolsDoc(doc, false))
}
func normalizeXAINamespaceToolChoiceWithFold(body []byte, shouldFold bool) []byte {
if !ojson.ValidBytes(body) {
return body
}
doc := ojson.NewDoc(body)
if !normalizeXAINamespaceToolChoiceWithFoldDoc(doc, shouldFold) {
return body
}
return doc.Bytes()
}
func normalizeXAINamespaceToolChoiceWithFoldDoc(doc *ojson.Doc, shouldFold bool) bool {
if doc == nil {
return false
}
type pendingChoiceEdit struct {
path string
targetName string
}
var edits []pendingChoiceEdit
planAtPath := func(path string) bool {
toolChoice := doc.Get(path)
if !toolChoice.IsObject() || toolChoice.Get("type").String() != xaiFunctionToolType {
return true
}
namespaceName := strings.TrimSpace(toolChoice.Get("namespace").String())
toolName := strings.TrimSpace(toolChoice.Get("name").String())
if namespaceName == "" {
return true
}
qualifiedName := qualifyXAINamespaceToolName(namespaceName, toolName)
var targetName string
if xaiHasFunctionToolNamedDoc(doc, namespaceName) {
targetName = namespaceName
} else if xaiHasFunctionToolNamedDoc(doc, qualifiedName) {
targetName = qualifiedName
} else if shouldFold {
targetName = namespaceName
} else {
targetName = qualifiedName
}
if targetName == "" {
return true
}
edits = append(edits, pendingChoiceEdit{path: path, targetName: targetName})
return true
}
if !planAtPath("tool_choice") {
return false
}
tools := doc.Get("tool_choice.tools")
if tools.IsArray() {
for index := range tools.Array() {
if !planAtPath(fmt.Sprintf("tool_choice.tools.%d", index)) {
return false
}
}
}
if len(edits) == 0 {
return false
}
for _, edit := range edits {
if errSet := doc.Set(edit.path+".name", edit.targetName); errSet != nil {
return false
}
if errDel := doc.Delete(edit.path + ".namespace"); errDel != nil {
return false
}
}
return true
}
// xaiUnsupportedWebSearchFields are OpenAI Responses web_search options that the
// xAI Responses API rejects with "Argument not supported". Options xAI accepts,
// such as filters, user_location and search_content_types, are forwarded as is.
var xaiUnsupportedWebSearchFields = [...]string{"external_web_access", "search_context_size"}
// stripUnsupportedXAIWebSearchFields removes web_search options that xAI rejects
// and reports which ones were removed.
func stripUnsupportedXAIWebSearchFields(raw []byte) ([]byte, []string, bool) {
doc := ojson.NewDoc(raw)
removed, ok := stripUnsupportedXAIWebSearchFieldsDoc(doc)
if !ok {
return nil, nil, false
}
if len(removed) == 0 {
return raw, nil, true
}
return doc.Bytes(), removed, true
}
func stripUnsupportedXAIWebSearchFieldsDoc(doc *ojson.Doc) ([]string, bool) {
if doc == nil {
return nil, false
}
var removed []string
for _, field := range xaiUnsupportedWebSearchFields {
if !doc.Get(field).Exists() {
continue
}
if errDel := doc.Delete(field); errDel != nil {
return nil, false
}
removed = append(removed, field)
}
return removed, true
}
func normalizeXAITool(tool ojson.Result, namespaceName string, keepImageGeneration bool) ([]byte, bool, bool) {
toolType := tool.Get("type").String()
changed := false
if toolType == xaiToolSearchType {
return nil, true, true
}
if toolType == xaiImageGenerationToolType && !keepImageGeneration {
return nil, true, true
}
raw := []byte(tool.Raw)
var toolDoc *ojson.Doc
ensureToolDoc := func() *ojson.Doc {
if toolDoc == nil {
toolDoc = ojson.NewDoc(raw)
}
return toolDoc
}
getField := func(path string) ojson.Result {
if toolDoc != nil {
return toolDoc.Get(path)
}
return tool.Get(path)
}
if toolType == xaiFunctionToolType || toolType == xaiCustomToolType {
if rawParams := getField("parameters"); rawParams.Exists() {
inlinedParams := util.InlineLocalRefs(rawParams.Raw)
if inlinedParams != rawParams.Raw {
td := ensureToolDoc()
if errSet := td.SetRawBytes("parameters", []byte(inlinedParams)); errSet == nil {
if td.Get("parameters.$defs").Exists() {
_ = td.Delete("parameters.$defs")
}
if td.Get("parameters.definitions").Exists() {
_ = td.Delete("parameters.definitions")
}
changed = true
}
}
}
schemaChanged, ok := normalizeXAIObjectRootUnionBranchTypesDoc(ensureToolDoc())
if !ok {
return nil, false, false
}
if schemaChanged {
changed = true
log.Debugf("xai: added object types to root union branches for tool %s.%s", namespaceName, tool.Get("name").String())
}
}
if toolType == xaiCustomToolType {
if errSet := ensureToolDoc().Set("type", xaiFunctionToolType); errSet != nil {
return nil, false, false
}
toolType = xaiFunctionToolType
changed = true
}
if toolType == xaiWebSearchToolType {
removed, ok := stripUnsupportedXAIWebSearchFieldsDoc(ensureToolDoc())
if !ok {
return nil, false, false
}
if len(removed) > 0 {
changed = true
log.Debugf("xai: removed unsupported web_search fields %v", removed)
}
}
if toolType == xaiFunctionToolType && !getField("parameters").Exists() {
if errSet := ensureToolDoc().SetRawBytes("parameters", []byte(`{"type":"object","properties":{}}`)); errSet != nil {
return nil, false, false
}
changed = true
}
// Simplify the Codex Desktop automation schema and root unions that xAI
// rejects because function parameters must resolve exclusively to objects.
if toolType == xaiFunctionToolType && xaiFunctionParametersNeedSimplificationFields(tool.Get("type").String(), getField("name").String(), getField("parameters"), namespaceName) {
td := ensureToolDoc()
if errSet := td.SetRawBytes("parameters", []byte(xaiSafeFunctionParameters)); errSet != nil {
return nil, false, false
}
if strict := tool.Get("strict"); strict.Exists() && strict.Bool() {
if errSet := td.Set("strict", false); errSet != nil {
return nil, false, false
}
}
changed = true
log.Debugf("xai: simplified parameters for tool %s.%s to avoid upstream schema rejection or hang", namespaceName, tool.Get("name").String())
}
if toolType == xaiFunctionToolType && strings.TrimSpace(namespaceName) != "" {
qualifiedName := qualifyXAINamespaceToolName(namespaceName, tool.Get("name").String())
if qualifiedName == "" {
return nil, false, false
}
if errSet := ensureToolDoc().Set("name", qualifiedName); errSet != nil {
return nil, false, false
}
changed = true
}
if changed && toolDoc != nil {
return toolDoc.Bytes(), true, true
}
return raw, false, true
}
func qualifyXAINamespaceToolName(namespaceName, toolName string) string {
namespaceName = strings.TrimSpace(namespaceName)
toolName = strings.TrimSpace(toolName)
if namespaceName == "" || toolName == "" || strings.HasPrefix(toolName, "mcp__") {
return toolName
}
prefix := namespaceName
if !strings.HasSuffix(prefix, "__") {
prefix += "__"
}
if strings.HasPrefix(toolName, prefix) {
return toolName
}
return prefix + toolName
}
func collectXAINamespaceToolRefs(body []byte) map[string]xaiNamespaceToolRef {
return collectXAINamespaceToolRefsWithFold(body, xaiShouldFoldNamespaceTools(body, false))
}
func collectXAINamespaceToolRefsWithFold(body []byte, shouldFold bool) map[string]xaiNamespaceToolRef {
return collectXAINamespaceToolRefsWithFoldResults(ojson.GetBytesNoCopy(body, "tools"), ojson.GetBytesNoCopy(body, "input"), shouldFold)
}
func collectXAINamespaceToolRefsWithFoldDoc(doc *ojson.Doc, shouldFold bool) map[string]xaiNamespaceToolRef {
if doc == nil {
return make(map[string]xaiNamespaceToolRef)
}
return collectXAINamespaceToolRefsWithFoldResults(doc.Get("tools"), doc.Get("input"), shouldFold)
}
func collectXAINamespaceToolRefsWithFoldResults(toolsResult, inputResult ojson.Result, shouldFold bool) map[string]xaiNamespaceToolRef {
refs := make(map[string]xaiNamespaceToolRef)
claimed := make(map[string]struct{})
collect := func(tools ojson.Result) {
if !tools.Exists() || !tools.IsArray() {
return
}
for _, tool := range tools.Array() {
toolType := strings.TrimSpace(tool.Get("type").String())
if toolType == xaiFunctionToolType || toolType == xaiCustomToolType {
if name := strings.TrimSpace(tool.Get("name").String()); name != "" {
claimed[name] = struct{}{}
if shouldFold {
if existing, ok := refs[name]; ok && !existing.isDispatcher {
delete(refs, name)
}
}
}
continue
}
if toolType != xaiNamespaceToolType {
continue
}
namespaceName := strings.TrimSpace(tool.Get("name").String())
if namespaceName == "" {
continue
}
if shouldFold {
if _, exists := claimed[namespaceName]; !exists {
claimed[namespaceName] = struct{}{}
refs[namespaceName] = xaiNamespaceToolRef{
namespace: namespaceName,
name: "",
isDispatcher: true,
children: make(map[string]struct{}),
}
}
}
for _, nestedTool := range tool.Get("tools").Array() {
if nestedTool.Get("type").String() == xaiToolSearchType {
continue
}
toolName := strings.TrimSpace(nestedTool.Get("name").String())
qualifiedName := qualifyXAINamespaceToolName(namespaceName, toolName)
if qualifiedName == "" {
continue
}
if shouldFold {
if dispRef, ok := refs[namespaceName]; ok && dispRef.isDispatcher && dispRef.children != nil {
dispRef.children[toolName] = struct{}{}
}
if _, claimedByTool := claimed[qualifiedName]; !claimedByTool {
if _, exists := refs[qualifiedName]; !exists {
refs[qualifiedName] = xaiNamespaceToolRef{namespace: namespaceName, name: toolName, isDispatcher: false}
}
}
continue
}
if _, exists := claimed[qualifiedName]; exists {
continue
}
claimed[qualifiedName] = struct{}{}
refs[qualifiedName] = xaiNamespaceToolRef{namespace: namespaceName, name: toolName, isDispatcher: false}
}
}
}
collect(toolsResult)
if inputResult.Exists() && inputResult.IsArray() {
for _, item := range inputResult.Array() {
if item.Get("type").String() == "additional_tools" {
collect(item.Get("tools"))
}
}
}
return refs
}
func normalizeXAIInputCustomToolCalls(body []byte) []byte {
doc := ojson.NewDoc(body)
if !normalizeXAIInputCustomToolCallsDoc(doc) {
return body
}
return doc.Bytes()
}
func normalizeXAIInputCustomToolCallsDoc(doc *ojson.Doc) bool {
if doc == nil {
return false
}
input := doc.Get("input")
if !input.Exists() || !input.IsArray() {
return false
}
changed := false
inputArray := input.Array()
items := make([]json.RawMessage, 0, len(inputArray))
for _, item := range inputArray {
var normalized []byte
switch item.Get("type").String() {
case "custom_tool_call":
callID := strings.TrimSpace(item.Get("call_id").String())
name := strings.TrimSpace(item.Get("name").String())
if callID == "" || name == "" {
changed = true
continue
}
itemDoc := ojson.NewDoc([]byte(`{"type":"function_call"}`))
_ = itemDoc.Set("call_id", callID)
_ = itemDoc.Set("name", name)
_ = itemDoc.Set("arguments", xaiCustomToolCallArguments(item.Get("input")))
normalized = itemDoc.Bytes()
case "custom_tool_call_output":
callID := strings.TrimSpace(item.Get("call_id").String())
if callID == "" {
changed = true
continue
}
itemDoc := ojson.NewDoc([]byte(`{"type":"function_call_output"}`))
_ = itemDoc.Set("call_id", callID)
_ = itemDoc.Set("output", xaiCustomToolCallOutput(item.Get("output")))
normalized = itemDoc.Bytes()
default:
items = append(items, json.RawMessage(item.Raw))
continue
}
items = append(items, json.RawMessage(normalized))
changed = true
}
if !changed {
return false
}
rawInput, errMarshal := json.Marshal(items)
if errMarshal != nil {
return false
}
return doc.SetRawBytes("input", rawInput) == nil
}
func xaiCustomToolCallArguments(input ojson.Result) string {
if !input.Exists() {
return "{}"
}
if input.Type == ojson.String {
text := input.String()
trimmed := strings.TrimSpace(text)
if ojson.Valid(trimmed) {
parsed := ojson.Parse(trimmed)
if parsed.IsObject() {
return parsed.Raw
}
}
encoded, errMarshal := json.Marshal(text)
if errMarshal != nil {
return "{}"
}
return `{"input":` + string(encoded) + `}`
}
if input.IsObject() {
return input.Raw
}
if input.Raw != "" {
return `{"input":` + input.Raw + `}`
}
return "{}"
}
func xaiCustomToolCallOutput(output ojson.Result) string {
if !output.Exists() {
return ""
}
if output.Type == ojson.String {
return output.String()
}
return output.Raw
}