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.mdindex 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.goindex 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.goindex 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)+ }}