fix(provider): never send a message with empty content (the Bedrock/Anthropic 400) — producer + backstop + inbox invariant

[wqymi]

One defect family, one PR: a message reaches the provider with content: [], which Anthropic/Bedrock reject with messages.<N>: user messages must have non-empty content.

This PR now carries the whole family. It absorbs #1963 (closed in favour of this one — same two files, stronger version kept) and adds the remaining producers found while consolidating. Reviewable in four sections: the producer, the send-side backstop, the defence-in-depth, and one per-role inconsistency raised in review.

---

A — THE PRODUCER: the trailing continuation turn was a bare string

ProviderTransform.ensureTrailingUserMessage appends a minimal user turn whenever the conversation would otherwise end with a content-bearing assistant (a "prefill", which Bedrock hard-400s). It appended:

return [...trimmed, { role: "user", content: CONTINUATION_PROMPT }]   // "Continue." — a STRING

ProviderTransform.message is typed for ModelMessage[], where content: string is perfectly legal. But it never runs on a ModelMessage[]. It runs inside the wrapLanguageModel middleware, on args.params.prompt — a LanguageModelV3Prompt, whose user content must be Array<TextPart | FilePart>. That mismatch is silenced by the // @ts-expect-error at session/llm.ts:671 (and session/prompt.ts:596), which is the root enabler.

@ai-sdk/anthropic then does this (dist/index.mjs:2320-2408, v3.0.82, read from node_modules):

for (let j = 0; j < content.length; j++) {
  const part = content[j];
  ...
  switch (part.type) {     // cases for "text" and "file" only — NO default

A string is iterated character by character. Each character's .type is undefined, no case matches, nothing is pushed — and the message ships as {"role":"user","content":[]}. Byte-for-byte the trailing message of the observed failing request.

ensureNonEmptyContent cannot catch this. Per its own ordering contract it runs before ensureTrailingUserMessage, and "Continue." is not empty by any predicate, so the append is never re-inspected.

Fix: content: [{ type: "text", text: CONTINUATION_PROMPT }] (transform.ts:442). Audited the rest of transform.ts for the same shape: :442 was the only bare-string emission. Of the two other placeholder sites, :376 was already correct; :622 emitted an array but applied it to the wrong set of roles — see section D.

Tested at the wire, not at toModelMessages

test/provider/empty-content-wire.test.ts asserts on the real outbound HTTP body, captured by injecting fetch into createAnthropic. Asserting on MessageV2.toModelMessages output would be two transformation layers short of the wire and would not have caught this. A CONTROL case pins the mechanism by feeding the bare-string form directly and asserting it ships as content: [].

Revert probe (fix reverted to the bare string):

101 |     expect(last.content).toHaveLength(1)
Expected length: 1
Received length: 0
(fail) … > ensureTrailingUserMessage's appended turn survives to the wire

112 |     expect(empty).toEqual([])
- []
+ [ { "index": 2, "length": 0, "role": "user" } ]
(fail) … > NO message reaches the wire with empty content
 2 pass / 2 fail

---

B — the send-side backstop, and the two seams it did not cover

ensureNonEmptyContent (transform.ts:364) is the global pre-send invariant: no message reaches the provider with empty content. Policy is deliberately asymmetric — user → backfill (dropping it would end the request on an assistant and trade this 400 for the prefill 400), assistant → drop (residue), tool → leave alone (we cannot synthesize a valid tool-result and injecting text would break tool_use/tool_result pairing).

Revert probe (call removed from message()): 460 pass / 3 fail —
does not filter for non-anthropic providers,
history ending in a content-bearing assistant + SDK-emptied user turn is repaired (@ai-sdk/openai),
empty-string user content is backfilled rather than removed.

Two seams it did not cover, both closed here:

B1 — normalizeMessages' empty-part strip was gated on two literal npm package names. Extracted to stripsEmptyParts() and extended with @ai-sdk/google-vertex/anthropic, @openrouter/ai-sdk-provider and @ai-sdk/openai-compatible — all routes to an API that rejects an empty block inside an otherwise non-empty message. Gating protocol legality on a package name is the hole. The AI SDK's own filter does not save us: its user branch drops empty text parts, but its assistant branch keeps an empty text part that carries providerOptions, and it never inspects reasoning parts at all.

B2 — src/session/goal.ts is the one persisted-parts→provider site with no transform at all. :197 passes model: language — the raw model, no wrapLanguageModel and no middleware anywhere in that file — then :218 calls generateObject. So ProviderTransform.message never runs for the goal judge, and none of its guards apply. Of the seven toModelMessagesEffect callers, the other six are covered and compaction.ts:133 is estimate-only (never sent). ensureNonEmptyContent is now applied by hand at :161.

Also widened session/llm.ts:670 from args.type === "stream" to generate || stream, matching prompt.ts:597. Latent today — this file's only SDK entrypoint is streamText at :599 — but the narrowing would silently drop the entire transform the moment a non-streaming call is added.

---

C — defence in depth: the inbox drain (absorbs #1963)

Inbox.drain is the one user-message producer that does not go through SessionPrompt.createUserMessage, so hasSubstantiveContent (prompt.ts:2164, :4386) never inspects it. It wrote one synthetic role:"user" message and one text part per queued row with text: renderInboxRow(row) persisted verbatim. renderInboxRow used content.text ?? placeholder, and ?? does not catch "" — so a body-less actor_notification (the one row type passed through RAW; type:"text" rows are structurally non-empty because of the <inbox> wrapper) would render to exactly "", giving parts: [{type:"text",text:""}] — length 1, so every parts.length === 0 guard misses it.

Two layers, both from #1963 (they supersede the bare ?? → || this PR previously carried):

• render.ts: a blankTo() helper, so any blank body (not merely a missing one) gets the placeholder, applied to both the actor_notification and the <inbox> branch.
• inbox.ts:268-277: the drain renders before writing and drops any row that renders blank; if every row renders blank it consumes them without writing a message at all. This is the structural invariant — it holds no matter what a future row type renders.

Reachability, stated honestly. This closes a defence gap that no observed transcript exercised: a 5.6 GB production store contains zero user text parts with text = ''. It is not described as an observed producer — section A is the observed producer. Note a genuine disagreement among the investigations: whether a blank body was reachable at all through the actor tool's shell path. Driving the real composition shellWrap(Tool.init(actor)).execute({ script: 'actor send <id> ""' }) with the parse-level guard removed still enqueues nothing and reports Too small: expected string to have >=1 characters → at operation.content, i.e. content: z.string().min(1) does fire — because shell-wrap.ts:121 calls def.execute(parsed) on the def from Tool.init, which is wrap()-decorated, and wrap() runs parameters.parse(args) inside execute. Probes that stop at parseActorScript cannot see this and report the opposite. Either way the fix is warranted and the zero-row census is consistent with it never having fired.

Accordingly, src/tool/actor.ts's comment — which asserted that a shell-parsed op is "NEVER re-validated against parameters" — is corrected: it stated the opposite of the truth, and contradicted shell-wrap.ts:43 in the very module it described. The parse-level guard is kept (upgraded to .trim(), so whitespace-only bodies are rejected too, which min(1) accepts) for two honest reasons: it turns a generic zod dump into one specific teachable message, and it would be the only guard left if the schema were relaxed.

---

D — normalizeContentArray contradicted the per-role policy for tool

Raised in review on this PR and fixed here. normalizeContentArray (transform.ts:615) is the crash guard that replaces a non-string non-array content (object / undefined / null) before anything calls .map() on it. Its fallback covered both user and tool:

if (msg.role === "assistant") return { ...msg, content: [] } as ModelMessage
return { ...msg, content: [{ type: "text", text: EMPTY_CONTENT_PLACEHOLDER }] } as ModelMessage   // user AND tool

So a tool message arriving with non-array content got a text part injected — exactly what ensureNonEmptyContent refuses to do to tool messages (section B), because it risks a tool_use / tool_result pairing mismatch, i.e. it trades this 400 for another one. Two guards in the same file disagreed on the same role.

tool is now returned untouched; only user keeps the backfill. Untouched rather than content: [], because an empty tool_result is itself illegal — "leave tool alone" is the policy both guards now share.

Reachability is effectively nil — tool messages are always constructed with array content — and that is precisely why it was worth closing rather than noting. This PR's headline defect (section A) was also an "unreachable" shape mismatch: a bare string where an array was mandatory, silenced by a @ts-expect-error, then iterated character by character into content: []. A latent per-role inconsistency in the exact dimension this PR is about will mislead the next reader.

Revert probe (tool falling back into the user branch again):

expect(Array.isArray(tool!.content) && tool!.content.some((p) => p.type === "text")).toBe(false)
Expected: false
Received: true
(fail) ProviderTransform.message - non-array content guard > a tool message with non-array content is never text-backfilled

test/provider/transform.test.ts → 240 pass / 0 fail. A follow-up commit strengthens the assertion from "was not text-backfilled" to "content is untouched", which is the actual invariant.

---

Explicitly out of scope (follow-ups, not padded in here)

These were flagged as verbatim part-copiers in the same family, but I could not construct a deterministic reachable case for any of them, and all six flow through ProviderTransform.message on send so the backstop covers them. Listing rather than shipping speculative fixes:

• session/compaction.ts:332 — compacting.prompt ?? … misses ""
• session/compaction.ts:421 (replay), session/session.ts:669 (fork)
• session/import.ts:186, session/opencode-import.ts:232, session/json-migration.ts:294

Also deferred: making goal.ts run the full ProviderTransform.message (image limits, cache markers, provider-option remapping) rather than only the emptiness invariant — a behaviour change outside this defect family.

---

Verification

Ref	Result
e080a8394d — this branch, pristine, pre-fold	517 pass / 0 fail / 21 files
f30b4c84f7 — #1963, pristine	507 pass / 0 fail / 21 files
this branch, folded	535 pass / 0 fail / 24 files

Identical command for all three: bun test test/provider test/inbox test/tool/actor.shell.test.ts test/session/goal.test.ts test/session/message-v2.test.ts --timeout 120000, run from packages/opencode. +3 files is exactly the three new test files. Every test from both folded sides survives.

bun typecheck exit 0.

Revert probe per folded fix (a fold that silently neutralises an assertion is the real risk here):

Fix reverted	Result
continuation turn → bare string	2 pass / 2 fail (verbatim in section A)
ensureNonEmptyContent removed from message()	460 pass / 3 fail (named in section B)
inbox.ts + render.ts → origin/main	37 pass / 10 fail, split 5/5 across both folded test files (drain-no-empty-part.test.ts from #1963, empty-notification-part.test.ts from this branch) — neither side was neutralised
parse-level shell guard removed	3 pass / 1 fail — only its own test; the decisive shellWrap-route case still passed, which is what shows zod is the load-bearing layer
normalizeContentArray tool fallback restored	239 pass / 1 fail — Expected: false / Received: true (verbatim in section D)

One honest note on the second probe: it used to produce 6 failures. It now produces 3 because the section-A producer fix independently repairs the cases the backstop was previously the only thing catching. The three that remain are the ones only the backstop can catch, and the wire case is now carried by its own dedicated test.

---

Follow-up (299b4aa92) — tool-role pin strengthened + reviewer's structural claims verified

Two commits landed after 1fba3205b:

• 9af5a1e61 — the reviewer's non-blocking finding: normalizeContentArray's fallback covered both user and tool, so a tool message with non-array content got a text part injected — contradicting ensureNonEmptyContent's per-role policy (transform.ts:341-360), which deliberately leaves tool alone because injecting text risks a tool_use/tool_result pairing mismatch. Gated on msg.role === "user"; tool returns untouched.
• 299b4aa92 — strengthens that pin and repairs a stale comment.

Chosen tool-role policy: leave the message EXACTLY as-is (not content: []). [] is illegal for providers that require the tool_result block, so it would trade the pairing 400 for a different one — there is no value this layer can honestly synthesize for a tool message. Leaving it untouched also makes both guards converge on the same input: hasNoSendableContent returns true for non-array content (transform.ts:334) and ensureNonEmptyContent's tool branch re-pushes it unchanged.

Why fix an unreachable path at all: this PR's headline defect was an "unreachable" shape mismatch — a bare string where an array was mandatory, silenced by a @ts-expect-error, then iterated character-by-character by @ai-sdk/anthropic into content: []. A latent per-role inconsistency in exactly this dimension will mislead the next reader.

299b4aa92 closes two residual gaps in 9af5a1e61:

1. Its pin only ruled out a text part, so rewriting the branch to content: [] kept it green. Mutation-verified: with return { ...msg, content: [] }, the original test reports 1 pass, 0 fail while both new tests fail. The new pin asserts the same reference (toBe(content)) across undefined / null / object.
2. Nothing pinned the agreement between the two guards — the actual finding. Added a test asserting ensureNonEmptyContent and message reach the same outcome on the same input.

Also corrected the comment block's opening claim, which still read as a blanket guarantee ("ensure msg.content is never a non-string non-array value … that would blow up downstream .map() calls"). That is no longer true for tool, and leaving it stale would license downstream code to assume array content.

Revert probe (gate removed, tests kept) — verbatim:

error: expect(received).toBeUndefined()

Received: [
  {
    type: "text",
    text: "Continue.",
    providerOptions: undefined,
  }
]

Follow-up 299b4aa92 — the pin was under-specified, and one comment was stale

9af5a1e61 (the gate itself) is correct and unchanged. Two residual gaps were closed on top of it.

The original assertion did not pin the policy. It asserted Array.isArray(content) && content.some(p => p.type === "text") === false — which is also green when tool content is rewritten to [], i.e. the other outcome this policy rejects. Mutation evidence: changing the branch to return { ...msg, content: [] } leaves that test at 1 pass / 0 fail, while both replacement pins fail. The pins now assert reference identity (toBe(content)) across undefined / null / object, plus a second test that normalizeContentArray and ensureNonEmptyContent reach the same outcome on the same non-array tool message (hasNoSendableContent returns true for non-array content at transform.ts:334, and the tool branch re-pushes unchanged) — a testable consistency property rather than an aesthetic preference.

"Exactly as-is" is load-bearing, and [] is not a substitute. An empty tool_result block is itself illegal for providers that require it, so content: [] only relocates the 400.

Acknowledged tradeoff, now stated in the comment instead of overstated. Exempting tool narrows this function's crash-guard guarantee: .map() safety no longer holds for tool messages, so downstream code must not assume array content. An attributable TypeError on an unrepairable shape is better than a pairing 400 that points away from the cause. The header comment was corrected from a blanket guarantee to NOT a blanket guarantee — tool is deliberately exempt.

Verdicts on the review's three structural claims (it did not run the suite)

All three CONFIRMED from the code at head.

(a) Pipeline order is correct — CONFIRMED. message() runs normalizeContentArray (transform.ts:951) → … → ensureNonEmptyContent (:977) → ensureTrailingUserMessage (:981), and the ordering contract at :404-412 states why the reverse is unsafe:

ORDERING CONTRACT: ensureNonEmptyContent MUST run before this function. … Running it first and resolving emptiness second would let this function return a list ending in an empty user message (which is what shipped, and what produced the live 400), and resolving emptiness afterwards could drop that message again and re-open the prefill 400. Emptiness first, prefill second — the two cannot fight.

(b) The DELETE consumes ALL rows including dropped blanks — CONFIRMED. Both delete sites key off rows, the full selected set, never the filtered rendered: the all-blank early return at inbox/inbox.ts:277-287 and the normal path at :316-323 both use

.where(inArray(InboxTable.id, rows.map((r) => r.id)))

so a partially-blank batch still consumes the blanks it dropped. The all-blank comment states the intent explicitly (:273-276): they carry no information and must not be re-drained forever. Nothing re-drains forever.

(c) Dropping a mid-history empty assistant is safe — CONFIRMED, both halves.

• Tool-call parts survive sdkVisibleAssistantParts (transform.ts:324-328): the predicate is !part || part.type !== "text" || part.text !== "" || part.providerOptions != null, and a tool-call part satisfies part.type !== "text". So an assistant carrying a tool call is never classified empty by hasNoSendableContent (:337) and is therefore never dropped — pairing is preserved by construction, not by luck.
• The SDK does merge the resulting consecutive same-role messages. @ai-sdk/anthropic@3.0.82 groupIntoBlocks (dist/index.mjs:3057-3102) opens a new block only when the role differs from currentBlock.type, and its case "tool" appends into a user block: if (currentBlock?.type !== "user") { currentBlock = { type: "user", messages: [] }; blocks.push(currentBlock) }. Adjacent user/user or tool/user therefore collapse into one block — no alternation violation.

Verification (this follow-up)

Scoped to test/provider/ + test/inbox/ only, from packages/opencode, as the full suite starves under concurrent sibling runs.

Run	Result
Pristine baseline, 1fba3205b, before any change	457 pass / 6 fail
With this follow-up, 299b4aa92	463 pass / 3 fail
test/provider/transform.test.ts alone, unloaded	241 pass / 0 fail

Every failure in both runs is a bare timed out after 5000ms — zero assertion failures on either side; the failing sets are not even the same between repeat runs of the identical command (one intermediate run showed 19, all timeouts). Total count rises 464 → 466 (the two added tests). bun typecheck exit 0.