Files
CLIProxyAPI/internal/runtime/executor/xai_executor_request.go
Luis Pater 6e6afab99a refactor: migrate gjson, sjson, and base64 to MoeForge/moego
- Replace tidwall/gjson and tidwall/sjson with github.com/MoeForge/moego/ojson
  and encoding/base64 with github.com/MoeForge/moego/base64 across the main
  module and examples
- Introduce cross-method *ojson.Doc request rewriting pipelines across
  thinking, signature, client/codex, runtime/executor/helps, pluginhost, and
  all provider executors with FinalizePayloadDoc as the final semantic barrier
- Convert all consecutive JSON mutations (>= 2 Set/SetRaw/Delete operations)
  to batch edits on ojson.Doc
- Upgrade read-only byte paths to ojson.GetBytesNoCopy,
  ojson.GetManyBytesNoCopy, and util.ParseGJSONBytesNoCopy with explicit
  strings.Clone ownership protection across streaming and persistent state
- Use base64.StdEncoding.ValidateString for zero-allocation signature checks
  and base64.EncodeDataURL for single-allocation data URL construction
2026-11-03 03:05:04 +08:00

2987 lines
87 KiB
Go

package executor
import (
"bytes"
"context"
"encoding/json"
"fmt"
"net/http"
"strconv"
"strings"
"sync"
"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
}
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
}