CF provider: malformed messages for multi-turn tool conversations via /ai/v1/chat/completions

[stackbilt-admin]

Summary

When AI_GATEWAY_ID is set (enabling the /ai/v1/chat/completions path in cloudflare-ai-binding.ts), the Cloudflare provider fails on multi-turn tool conversations with:

```
AiError: Bad input: Error: oneOf at '/' not met, 0 matches:
required properties at '/' are 'prompt',
Type mismatch of '/messages/0/content', 'array' not in 'string',
Type mismatch of '/messages/1/content', 'string' not in 'null',
required properties at '/messages/1' are 'role,content'
```

Single-turn tool requests succeed. The bug only surfaces when messages contains prior function_call + function_call_output history.

Root cause (localized)

cloudflare.ts — formatRequest() message builder (around line 588–623):

When the request includes messages with toolCalls and toolResults, the resulting messages array contains:

• A user message whose content ends up as an array (not a string) in some paths — CF's /ai/v1/chat/completions requires string content
• An assistant message with content: null and tool_calls — the endpoint schema may require this to be absent rather than null

The /ai/run/{model} path (used without AI_GATEWAY_ID) does not exhibit this error — its schema appears more permissive.

Impact

• Any multi-turn tool-loop request routed through cloudflare provider via AI_GATEWAY_ID fails
• Affects @cf/openai/gpt-oss-120b, @cf/moonshotai/kimi-k2.6, and all other CF tool-capable models
• In llm-gateway: the error is a plain Error (not a typed LLMProviderError), which additionally blocks fallback (separate gateway-side workaround already applied)

Suggested fix

In cloudflare.ts formatRequest():

1. Ensure all message.content values are coerced to string | null, never string[], before building the CF payload
2. For assistant messages with tool_calls, verify whether the /ai/v1/chat/completions endpoint requires content to be omitted vs null
3. Consider throwing InvalidRequestError (or another typed error) instead of propagating the raw AiError, so callers can distinguish bad-input from transient failures

Reproduction

// Construct an LLMRequest with prior tool loop history:
const request = {
  messages: [
    { role: 'user', content: 'list files' },
    { role: 'assistant', content: '', toolCalls: [{ id: 'c1', type: 'function', function: { name: 'bash', arguments: '{"command":"ls"}' } }] },
    { role: 'user', content: 'file1\nfile2', toolResults: [{ id: 'c1', output: 'file1\nfile2' }] },
  ],
  tools: [{ type: 'function', function: { name: 'bash', description: 'run shell', parameters: { type: 'object', properties: { command: { type: 'string' } }, required: ['command'] } } }],
  model: '@cf/openai/gpt-oss-120b',
};
// CloudflareProvider.generateResponse(request) → AiError: Bad input

Environment

• @stackbilt/llm-providers v1.14.4
• AI_GATEWAY_ID set (triggers /ai/v1/chat/completions path in binding)
• Verified: /ai/run/ endpoint works for same payload, /ai/v1/chat/completions fails

[stackbilt-admin]

Hey folks,

I dug into Cloudflare’s own docs and changelog after hitting this error. Here’s what I found:

The chat completions spec now explicitly allows message.content to be either a string or an array of { text, type } objects. In other words, the schema our code was tripping over has been broadened — arrays aren’t verboten anymore.
On 2026‑02‑17 Cloudflare shipped a set of bug fixes for /v1/chat/completions that directly address the problems we’re seeing. Specifically, they fixed the bug where the content field only accepted strings, added support for array content, and made the API accept assistant messages with content: null and tool_calls. This is exactly the malformed input error reported in our repro.

So the root cause here isn’t that Cloudflare’s API is fundamentally broken — it’s that our provider code and/or the AI Gateway layer are pinned to an older version that predates these fixes. Two actionable next steps:

Upgrade dependencies. Make sure we’re using the latest workers-ai-provider and @stackbilt/llm-providers versions so we pick up the February 2026 fixes. The docs confirm that multi‑turn tool calls with array content and content: null are now supported.
Fallback to /ai/run/ in the interim. If upgrading isn’t feasible right now, the /ai/run/ endpoint is more permissive and still handles our multi‑turn payloads. That’s a temporary workaround until we get our bindings up to date.

I’ll leave it to the maintainers to decide whether we want to keep this issue open until we bump the gateway/provider versions, or close it since Cloudflare has already fixed the underlying API. Happy to help test once we roll forward.

— CodeBeast

[stackbilt-admin]

Clarification on the setup + current status

The 502 is already fixed — gateway-side

The immediate Codex 502 was resolved by a gateway-level workaround committed to llm-gateway at dca372c. No changes to @stackbilt/llm-providers were needed to unblock Codex. That fix is live and verified.

What llm-providers#91 actually tracks

The issue is an upstream quality improvement in the CF provider: fixing the message format so multi-turn tool conversations don't fail validation on /ai/v1/chat/completions in the first place, and surfacing a typed error (InvalidRequestError or similar) instead of a plain Error so callers can distinguish bad-input from transient failures.

Neither of these is blocking anything right now — the gateway fallback handles it. But both are worth fixing for correctness.

How aegis claude / aegis codex work

These are launcher scripts in aegis-daemon/cli/aegis.mjs. They:

1. Set ANTHROPIC_BASE_URL=http://localhost:8787 (for aegis claude) or inject a model catalog JSON (for aegis codex)
2. Launch the native Claude Code or Codex CLI normally
3. The harness talks to llm-gateway on port 8787, which routes through @stackbilt/llm-providers

So the chain is: Claude Code / Codex → llm-gateway (port 8787) → llm-providers → CF Workers AI / Groq / etc.

To test your llm-providers changes locally

npm link works, or swap the dep to file: — either is fine. But for this specific issue (CF message format), you don't need aegis claude to test it: a unit test that constructs an LLMRequest with prior tool loop history and calls CloudflareProvider.generateResponse() directly is sufficient and faster.

Once the fix is ready: publish a new patch version → llm-gateway's ^1.14.x dep picks it up on next npm install. No linking needed in production.

Summary

• Codex is unblocked ✓
• llm-providers#91 = CF formatRequest() message format fix + typed error surfacing (improvement, not blocker)
• No npm link dance needed on your end unless you want end-to-end local testing