Skip to content

Every agent's model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.

gateway: xAI's own API takes no null required in a tool's schema (#3392, kongkongklng)

vincentaba11fc4de5d
diff --git a/docs/subsystems/gateway-routing.md b/docs/subsystems/gateway-routing.md
index 0566fa6e6..023bccc09 100644
--- a/docs/subsystems/gateway-routing.md
+++ b/docs/subsystems/gateway-routing.md
@@ -280,7 +280,7 @@ recorded as a prediction failure (`noPrediction`).
- A tool's `strict` that an upstream turns away (`toolStrictRefusal` in [`strict_refused.go`](../../internal/gateway/strict_refused.go): "Unsupported Chat Completions API field: tools[0].function.strict", OpenAI-style unknown_parameter, "Extra inputs are not permitted" and pydantic's extra_forbidden on it) is asked once more without it, in Chat's `tools[].function` and Responses' `tools[]` alike, and marked for that provider and API (`toolStrictRefused`): its next requests go without it at once. OpenCode 2 sends `"strict": false` on every tool through `@ai-sdk/openai-compatible`, and a custom provider that refused it ended the session (#1980). An upstream that hasn't refused it still gets it, as the ChatGPT backend needs it (#383). `TestToolStrictLeftOutWhereRefused` (real OpenCode 2.0.25 requests), `TestToolStrictRefusalWordings`.
- A history call to a tool the request doesn't declare, which an agent that loads its tools on demand sends (pi's and T3 Code's `tool_search`: the tools a search found are called in the history but not declared in the next request's `tools`, and pi sends `"tools": []` with no tools left; Gearclickist on Discord), goes as sent where it is taken: OpenAI's Chat and Responses, the ChatGPT backend and Gemini take it, and Anthropic takes a call to a tool it isn't given ([`undeclared_tools.go`](../../internal/gateway/undeclared_tools.go)). Anthropic refuses calls with no tools at all ("Requests which include `tool_use` or `tool_result` blocks must define tools"), so `anthropicBody` declares a stub for each tool the history called when the request has none (description "Called earlier in this conversation; not available now.", any object as its input) with `tool_choice` `none`, as the Kiro plugin declares its history's tools for Kiro. An upstream that turns the request away naming such a tool as not found, unknown or not defined, or that says tools must be defined beside the calls (`refusesHistoryTools`: a relay in front of Kiro or Bedrock, a vendor checking each name), is asked once more with a stub declared for each tool the history called and `tools` lacks (`withHistoryTools`, Chat, Responses and Messages bodies, relayed or translated), `tool_choice` `none` only where the client offered no tools, and marked for that provider and API (`historyToolsRefused`): its next requests carry the stubs at once. A Responses call under a namespace is the namespace's, and a request whose calls are all declared goes as it was. `TestUndeclaredHistoryToolRefusedThenStubbed`, `TestToollessHistoryToAnthropicDeclaresStubs`, `TestToollessHistoryRefusedOnChat`, `TestUndeclaredHistoryToolTakenAsSent`, `TestRefusesHistoryToolsMatch`.
- A Codex custom tool (exec, apply_patch) that a Responses upstream turns away (`customToolRefusal` in [`custom_tool.go`](../../internal/gateway/custom_tool.go): DeepSeek's 400 "Unsupported custom tool: 'exec'. Only 'apply_patch' is supported.", #2656; xAI's 422 "tools[N].type: unknown variant `custom`, expected one of …", Rust's own wording of the type, #3392) ends the relay: `passthrough` marks the model (`customToolRefused`) and returns not done, and `attempt` translates the request on the same API (`ownAPI`), where each custom tool is offered as a function taking its `input` and a call comes back as the `custom_tool_call` Codex runs, its name kept. A marked model's next requests with a custom tool are translated at once; one without stays relayed, and an upstream that never refused them still gets them as sent. A compaction (`keepsCompaction`) isn't translated, and gets the refusal. Where the refusal reaches a group untranslated it is a shape refusal (`shapeRefused`): the next member is asked. `TestCustomToolTranslatedWhereRefused`, `TestCustomToolRefusalInGroup`, `TestCustomToolRefusalWordings`.
-- xAI's own API (api.x.ai, wherever a Grok model is served — the Grok subscription's plugin shapes its own bodies, provider's `grokShaped`) takes neither of two things a client's wire puts in wrong (`xaiBody` in [`xai_body.go`](../../internal/gateway/xai_body.go), shaped in `passthrough` and on the built body in `forwardTranslated` alike, for a custom-tool refusal puts a Codex request on the translated path from the next turn on; there is nothing to learn, xAI takes neither at all, #3392's follow-up): Codex hands a sealed reasoning item back with `"content": null` beside its `encrypted_content`, which the backend answers "Could not decode the compaction blob. Ensure it is unmodified from the compact response." (the first turn goes through, every one after it 400s) — the null goes, the item otherwise as it came; and Claude Code, its messages carrying a system turn mid-conversation since Anthropic made them GA, sends one that xAI's Messages answers "Invalid request content: Invalid message role." — each folds into the top-level `system`, its text and blocks (a `cache_control` kept) as they came, the only place that API takes the role. `TestXAITakesCodexsSealedReasoningBack`, `TestXAILearnsCustomToolsThenTakesTheReplay`, `TestXAIFoldsClaudesSystemTurn`.
+- xAI's own API (api.x.ai, wherever a Grok model is served — the Grok subscription's plugin shapes its own bodies, provider's `grokShaped`) takes none of three things a client's wire puts in wrong (`xaiBody` in [`xai_body.go`](../../internal/gateway/xai_body.go), shaped in `passthrough` and on the built body in `forwardTranslated` alike, for a custom-tool refusal puts a Codex request on the translated path from the next turn on; there is nothing to learn, xAI takes none of them at all, #3392's follow-up): Codex hands a sealed reasoning item back with `"content": null` beside its `encrypted_content`, which the backend answers "Could not decode the compaction blob. Ensure it is unmodified from the compact response." (the first turn goes through, every one after it 400s) — the null goes, the item otherwise as it came; and Claude Code, its messages carrying a system turn mid-conversation since Anthropic made them GA, sends one that xAI's Messages answers "Invalid request content: Invalid message role." — each folds into the top-level `system`, its text and blocks (a `cache_control` kept) as they came, the only place that API takes the role; and a tool's schema can say `"required": null` where none are (Claude Code's own tools, an MCP server's among them — Anthropic's API takes the null), which xAI's validation of each schema answers "Invalid request content: Schema validation failed: [standard_violation] /required: null is not of type \"array\"" (the claude calls 400ed once the system turns folded) — the key goes from every shape a body leaves magpie in, `input_schema`, `parameters` and `function`'s, at the schema's root or nested, a real array of names kept as it came. `TestXAITakesCodexsSealedReasoningBack`, `TestXAILearnsCustomToolsThenTakesTheReplay`, `TestXAIFoldsClaudesSystemTurn`, `TestXAITakesANullRequiredToolSchema`, `TestXaiBodyDropsNullRequiredInEveryShape`.
- A tool call's arguments reach the client as the vendor writes them, translated too (echo_ts on Discord: Codex on Copilot about 10x slower, an apply_patch shown only once whole). The Responses decoder hands each `function_call_arguments.delta` and `custom_tool_call_input.delta` on as a `KToolArgs` delta (`argsDelta`), holding back only the one that would make the JSON whole until `.done`, which `endCall` checks against the final arguments; the Responses encoder streams a custom tool's input as `custom_tool_call_input.delta` (`customStream` in [`custom_tool.go`](../../internal/gateway/custom_tool.go)) before its `.done`. A Copilot account's Responses request is relayed with a `web_search` tool in it (`searchesItself`; checked on a real account 2026-10-17), and Copilot is never picked to search for another provider's model (`searchRank`). It is translated instead when a tool marks a parameter `"encrypted": true` (`asksSealing`, MultiAgentV2's `spawn_agent`): Copilot seals such an argument and can't read its own seal on the subagent's turn. `TestCallArgsStreamWhenTranslated`, `TestCustomInputStreams`, `TestResponsesCallArgsStream`, `TestCopilotRelayedUnlessAskedToSeal`, `TestCopilotUltraSubagentWithWebSearch`.
- A relayed Responses stream gives each output item the one id its `response.output_item.added` gave it, in every event after that carries an `item_id` or an `item`, and in the `output` of `response.completed`, `response.incomplete` or `response.failed` (`idTidy` in [`itemids.go`](../../internal/gateway/itemids.go), applied in `passthrough` before `phaseTidy`). GitHub Copilot's `/responses` gives an item another id in every event (checked 2026-10-19 on a real account, gpt-5.5 with web_search), and Codex starts an item by the added's id and ends one by the done's, so a commentary message was shown twice and a web search never ended (echo_ts on Discord, `TestCopilotItemKeepsItsID`). An upstream whose ids agree goes through byte for byte (`TestItemIDsThatAgreeGoAsTheyCame`); a translated reply's ids are magpie's own.
- A model's reply limit is published within the window beside it (#1438, `provider.OutputWithin`, `Entry.PublishedOutput`): `/v1/models`' `max_output_tokens` (`modelObject`), Cursor Private Inference's `capabilities.max_output_tokens` (`cursorLocalModel`), Muse Code's `limit.output` (`museModels`), the GUI's model and group rows (`providerInfo`, `providersState`), `magpie model output`, and every agent's file (`agent.maxTokens`, #338). The window and the output can come from different sources: Grok's backend lists grok-4.7's 256000 window, and models.dev fills its 500000 output (`catalog.Decorate` and `Provider.replyLimit` fill an output only where the vendor gives none). An unknown window or output is published as it is. The catalog keeps the unclamped `Entry.Output`, and a group's member is still asked for no more than that (`outputLimit`, `withMaxOutput`), so a request isn't lowered by the clamp. A limit the user set stays in their settings as they set it (`TestModelListsKeepOutputWithinTheWindow`). Outside a group, only a Max output the user set for the model (`Entry.OutputSet`) lowers a request (`userOutput`): Claude Code asks a claude-* model for its own full limit (128000 on Opus 5.5) and is told no figure of magpie's for it (`claudeOutput`), and a key whose quota is held per request as max_tokens times the price turned every turn away (YaCo on Discord, `TestUserMaxOutputLowersAPlainProvidersRequest`). A vendor's or models.dev's figure doesn't lower it, since it may be stale.
diff --git a/internal/gateway/xai_body.go b/internal/gateway/xai_body.go
index 8a990b5c1..d8bef6fc0 100644
--- a/internal/gateway/xai_body.go
+++ b/internal/gateway/xai_body.go
@@ -7,7 +7,7 @@ import (
"github.com/yetone/magpie/internal/provider"
)
-// xAI's own API (api.x.ai), wherever a Grok model is served, takes two
+// xAI's own API (api.x.ai), wherever a Grok model is served, takes three
// things a client's wire puts in wrong, as the Grok subscription's plugin
// shapes its bodies too (provider's grokShaped):
//
@@ -20,17 +20,24 @@ import (
// them GA), which xAI's Messages answers "Invalid request content:
// Invalid message role." (#3392: every claude call 400ed) — each folds
// into the top-level system, the only place it takes the role.
+// - A tool's schema can say "required": null where none are (Claude
+// Code's tools, an MCP server's among them — Anthropic's API takes
+// it), which xAI answers "Invalid request content: Schema validation
+// failed: [standard_violation] /required: null is not of type
+// \"array\"" (#3392: the claude calls 400ed after the system-turn
+// fix) — the key goes, null says none.
//
// The relay and the translation shape alike: a refusal of custom tools
// puts a Codex request on the translated path from the next turn on
// (custom_tool.go), and there is nothing to learn from either answer —
-// xAI takes no null content and no system turn at all.
+// xAI takes no null content, no system turn and no null required at all.
// xaiBody shapes body as xAI's own API takes it on proto.
func xaiBody(p provider.Provider, proto provider.Protocol, body []byte) []byte {
if p.Host() != "api.x.ai" {
return body
}
+ body = withoutNullToolRequired(body)
switch proto {
case provider.Responses:
return withoutNullReasoningContent(body)
@@ -137,3 +144,68 @@ func systemTurnsFolded(body []byte) []byte {
}
return out
}
+
+// withoutNullToolRequired is a body whose tool schemas carry no null
+// required (#3392). xAI validates each tool's schema as a JSON Schema
+// and refuses the null at its root or anywhere nested; a client's wire
+// puts it there where none are required (Anthropic's API takes it). The
+// schemas are found under every shape a body leaves magpie in:
+// input_schema (Anthropic), parameters (Responses) and function's
+// parameters (chat).
+func withoutNullToolRequired(body []byte) []byte {
+ if !bytes.Contains(body, []byte(`"tools"`)) || !bytes.Contains(body, []byte(`"required"`)) {
+ return body
+ }
+ dec := json.NewDecoder(bytes.NewReader(body))
+ dec.UseNumber()
+ var m map[string]any
+ if dec.Decode(&m) != nil || m == nil {
+ return body
+ }
+ dirty := false
+ tools, _ := m["tools"].([]any)
+ for _, t := range tools {
+ tm, _ := t.(map[string]any)
+ if tm == nil {
+ continue
+ }
+ for _, k := range []string{"parameters", "input_schema"} {
+ if dropNullRequired(tm[k]) {
+ dirty = true
+ }
+ }
+ if fm, _ := tm["function"].(map[string]any); fm != nil {
+ if dropNullRequired(fm["parameters"]) {
+ dirty = true
+ }
+ }
+ }
+ if !dirty {
+ return body
+ }
+ out, err := marshalPlain(m)
+ if err != nil {
+ return body
+ }
+ return out
+}
+
+// dropNullRequired deletes every "required": null in v, recursively, and
+// says whether it did; a real array of names stays as it came.
+func dropNullRequired(v any) bool {
+ obj, _ := v.(map[string]any)
+ if obj == nil {
+ return false
+ }
+ dirty := false
+ if r, there := obj["required"]; there && r == nil {
+ delete(obj, "required")
+ dirty = true
+ }
+ for _, child := range obj {
+ if dropNullRequired(child) {
+ dirty = true
+ }
+ }
+ return dirty
+}
diff --git a/internal/gateway/xai_body_test.go b/internal/gateway/xai_body_test.go
index 5bbfe3e6d..d429b1946 100644
--- a/internal/gateway/xai_body_test.go
+++ b/internal/gateway/xai_body_test.go
@@ -24,6 +24,7 @@ const (
xaiCompactionRefusal = `{"code":"invalid-argument","error":"Could not decode the compaction blob. Ensure it is unmodified from the compact response."}`
xaiUnknownCustom = `Failed to deserialize the JSON body into the target type: tools[6].type: unknown variant ` + "`custom`" + `, expected one of ` + "`function`" + `, ` + "`web_search`" + `, ` + "`shell`" + `, ` + "`tool_search`"
xaiInvalidRole = `{"type":"error","error":{"type":"invalid_request_error","message":"Invalid request content: Invalid message role."}}`
+ xaiNullRequired = `{"type":"error","error":{"type":"invalid_request_error","message":"Invalid request content: Schema validation failed: [standard_violation] /required: null is not of type \"array\""}}`
)
// The reporter's second turn: Codex's replay of the sealed reasoning item
@@ -201,7 +202,81 @@ func TestXAIFoldsClaudesSystemTurn(t *testing.T) {
}
}
-// A body xAI takes is passed through untouched: the two shapers change
+// #3392's third round, as kongkongklng reported it after the system-turn
+// fix: codex went through, every Claude call still 400ed xAI's schema
+// validation "Invalid request content: Schema validation failed:
+// [standard_violation] /required: null is not of type \"array\"" — a
+// tool's schema said "required": null where none were (Claude Code's own
+// tools or an MCP server's; Anthropic's API takes the null, xAI validates
+// the schema). The null required goes, root or nested; a real array of
+// names stays.
+func TestXAITakesANullRequiredToolSchema(t *testing.T) {
+ f := &fake{t: t, reply: sse(
+ `event: message_start`+"\n"+`data: {"type":"message_start","message":{"id":"msg_1","type":"message","role":"assistant","model":"grok-4.7","content":[],"usage":{"input_tokens":1,"output_tokens":0}}}`,
+ `event: content_block_delta`+"\n"+`data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"ok"}}`,
+ `event: content_block_stop`+"\n"+`data: {"type":"content_block_stop","index":0}`,
+ `event: message_delta`+"\n"+`data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":1}}`,
+ `event: message_stop`+"\n"+`data: {"type":"message_stop"}`)}
+ f.refuse = func(body []byte) (int, string) {
+ if bytes.Contains(body, []byte(`"required":null`)) {
+ return 400, xaiNullRequired
+ }
+ return 0, ""
+ }
+ up := setup(t, provider.Anthropic, f)
+ if err := provider.Save(provider.Provider{ID: "fake", Name: "Fake", Key: "k", Models: []string{"grok-4.7"}, Anthropic: "http://api.x.ai"}); err != nil {
+ t.Fatal(err)
+ }
+ s := New()
+ addr := strings.TrimPrefix(up.URL, "http://")
+ s.client = &http.Client{Transport: &http.Transport{DialContext: func(ctx context.Context, network, _ string) (net.Conn, error) {
+ return (&net.Dialer{}).DialContext(ctx, network, addr)
+ }}}
+ // the reporter's shape: Bash's schema with its real required array
+ // beside an MCP-flavoured tool whose schema says required: null at the
+ // root and one whose nested property does (texts cut)
+ rec := httptest.NewRecorder()
+ s.Handler().ServeHTTP(rec, httptest.NewRequest("POST", "/v1/messages", strings.NewReader(`{"model":"fake/grok-4.7","stream":true,"max_tokens":128000,
+ "tools":[{"name":"Bash","description":"Run a command","input_schema":{"type":"object","properties":{"command":{"type":"string"}},"required":["command"]}},
+ {"name":"mcp__server__search","description":"Search","input_schema":{"type":"object","properties":{"query":{"type":"string"}},"required":null}},
+ {"name":"mcp__server__nested","description":"Nested","input_schema":{"type":"object","properties":{"opts":{"type":"object","properties":{"a":{"type":"string"}},"required":null},"b":{"type":"number"}}}}],
+ "messages":[{"role":"user","content":[{"type":"text","text":"hello"}]}]}`)))
+ if rec.Code != 200 {
+ t.Fatalf("%d %s\nxAI got %s", rec.Code, rec.Body, f.got)
+ }
+ if bytes.Contains(f.got, []byte(`"required":null`)) {
+ t.Errorf("null required left in a tool schema: %s", f.got)
+ }
+ for _, said := range []string{`"required":["command"]`, `"query"`, `"opts"`, `"mcp__server__nested"`} {
+ if !bytes.Contains(f.got, []byte(said)) {
+ t.Errorf("xAI's schemas lost %q: %s", said, f.got)
+ }
+ }
+}
+
+// The other two shapes a tool schema leaves magpie in get the same null
+// out: Responses' parameters and chat's function.parameters.
+func TestXaiBodyDropsNullRequiredInEveryShape(t *testing.T) {
+ p := provider.Provider{ID: "fake", Chat: "https://api.x.ai/v1", Responses: "http://api.x.ai/v1"}
+ chat := `{"model":"fake/grok-4.7","tools":[{"type":"function","function":{"name":"Bash","parameters":{"type":"object","properties":{"command":{"type":"string"}},"required":null}}},{"type":"function","function":{"name":"Read","parameters":{"type":"object","properties":{"path":{"type":"string"}},"required":["path"]}}}],"messages":[]}`
+ got := xaiBody(p, provider.Chat, []byte(chat))
+ if bytes.Contains(got, []byte(`"required":null`)) {
+ t.Errorf("chat shape kept the null: %s", got)
+ }
+ if !bytes.Contains(got, []byte(`"required":["path"]`)) || !bytes.Contains(got, []byte(`"command"`)) {
+ t.Errorf("chat shape lost a real schema: %s", got)
+ }
+ responses := `{"model":"fake/grok-4.7","tools":[{"type":"function","name":"exec_command","parameters":{"type":"object","properties":{"cmd":{"type":"string"}},"required":null}}],"input":[]}`
+ got = xaiBody(p, provider.Responses, []byte(responses))
+ if bytes.Contains(got, []byte(`"required":null`)) {
+ t.Errorf("responses shape kept the null: %s", got)
+ }
+ if !bytes.Contains(got, []byte(`"cmd"`)) {
+ t.Errorf("responses shape lost a real schema: %s", got)
+ }
+}
+
+// A body xAI takes is passed through untouched: the shapers change
// nothing else about it, and another host's own quirks stay its own.
func TestXaiBodyLeavesWhatItTakes(t *testing.T) {
plain := `{"model":"m","input":[{"type":"message","role":"user","content":[{"type":"input_text","text":"hi"}]},{"type":"reasoning","id":"rs_1","encrypted_content":"gAABblob"}],"messages":[{"role":"user","content":"hi"}],"system":"prompt"}`
@@ -240,4 +315,10 @@ func TestXaiBodyLeavesWhatItTakes(t *testing.T) {
if got := xaiBody(p, provider.Responses, []byte(xaiSecondTurn)); !bytes.Equal(got, []byte(xaiSecondTurn)) {
t.Errorf("other host shaped: %s", got)
}
+ // a schema whose required are all real arrays keeps its bytes
+ real := `{"model":"fake/grok-4.7","tools":[{"type":"function","function":{"name":"Bash","parameters":{"type":"object","properties":{"command":{"type":"string"}},"required":["command"]}}}],"messages":[]}`
+ xp := provider.Provider{ID: "fake", Chat: "https://api.x.ai/v1"}
+ if got := xaiBody(xp, provider.Chat, []byte(real)); !bytes.Equal(got, []byte(real)) {
+ t.Errorf("real required arrays changed: %s", got)
+ }
}