fix(llm-dialog): Filter empty text content blocks to prevent API errors

[jkomoros]

What Broke

Users started encountering this error when using LLM-based patterns:

AI_APICallError: messages: text content blocks must be non-empty

Affected patterns:

• demo-setup: Execute button would fail immediately on second run
• omnibot: Started failing after tool calls
• Any pattern using llmDialog with tools and caching

User experience:

• First execution: Works fine
• Reset and re-execute: Fails with API error
• Cache-busting workarounds (Date.now() timestamps) were needed

Why It Broke

This issue emerged from the intersection of three changes:

1. Tool Call Caching Enabled (Nov 6, commit d394ec8)

Previously, requests with tools were excluded from caching to prevent incomplete responses. The commit enabled caching for tool calls with this rationale:

"With the sequential request architecture, each request includes complete context (including tool results from previous rounds), making each response cacheable."

This was correct in theory but exposed a hidden issue.

2. Anthropic API Behavior

When Claude responds with tool calls, the API can return responses like:

{
  "role": "assistant",
  "content": [
    {"type": "text", "text": ""},          // ← Empty text block
    {"type": "tool_use", "id": "...", ...}
  ]
}

The empty text block is valid in the initial response (Anthropic accepts it as input).

3. Stricter API Validation (Recent)

Anthropic's API recently became stricter about outgoing requests - it now rejects empty text blocks when they're sent back in conversation history, even though it can return them in responses.

The sequence:

1. User sends message → LLM responds with empty text + tool call → cached
2. Tools execute → tool results added to conversation
3. Next LLM request → sends cached messages including empty text → API rejects

Why This Fix Works

The fix filters empty text content blocks at two critical points:

1. When Building Assistant Messages (buildAssistantMessage)

// Before: Included all text parts, even empty ones
...content.filter((part) => part.type === "text")

// After: Only include non-empty text
...content.filter((part) =>
  part.type === "text" && 
  part.text && 
  part.text.trim() !== ""
)

Prevents empty text parts from being stored in the first place.

2. Before Sending to API (startRequest)

const rawMessages = messagesCell.withTx(tx).get();
const filteredMessages = rawMessages.map((msg) => {
  if (Array.isArray(msg.content)) {
    const filteredContent = msg.content.filter((part) => {
      if (part.type === "text") {
        return part.text && part.text.trim() !== "";
      }
      return true; // Keep tool-call, tool-result, etc.
    });
    return { ...msg, content: filteredContent };
  }
  return msg;
});

Handles cached messages that already have empty text parts (defense in depth).

Why Both Filters Are Necessary

Filter #1 alone: Would fix new conversations but cached conversations would still have empty text

Filter #2 alone: Would fix the API error but continue storing empty text unnecessarily

Both together:

• Prevents new empty text from being stored
• Filters existing empty text from cached messages
• Ensures API compatibility regardless of source

Testing

Verified the fix resolves all known issues:

✅ demo-setup pattern:

• Execute button works on first run
• Reset → Execute works without errors
• Tool calls execute successfully
• Multiple execute cycles work

✅ omnibot:

• Tool calls work
• Conversation continues correctly
• No API errors

✅ Server logs:

• No "text content blocks must be non-empty" errors
• Clean LLM API responses

Why This Is The Right Fix

This isn't a workaround - it addresses the fundamental issue:

Reality: LLM APIs can return empty text blocks in responses

• Anthropic does this, especially with tool calls
• We don't control their response format

Constraint: Those same APIs reject empty text blocks in requests

• Stricter outgoing validation than incoming
• We must filter before sending

Caching implication: Empty text blocks can persist across requests

• Once cached, they're sent in subsequent requests
• Must filter both at storage time and send time

The fix ensures CommonTools never sends empty text blocks to any LLM API, regardless of what the API returns or what's in the cache.

Alternative Considered

Could disable caching for tool calls again, but that would:

• Lose performance benefits of caching tool interactions
• Not fix already-cached conversations
• Not prevent the issue if Anthropic returns empty text in non-tool responses

Filtering empty text is the correct solution.

---

Fixes issues reported by @jkomoros (Alex) via Claude Code investigation.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

---

Summary by cubic

Prevents Anthropic "messages: text content blocks must be non-empty" errors by validating fresh responses and hardening tool handling. Conversations with tool calls now re-run reliably without cache-busting.

• Bug Fixes
  • Validate fresh responses with hasValidContent; replace empty/invalid content with a friendly error.
  • Ensure tool results always include output (use explicit null when needed); verify tool call/result ID match and surface a clear error on mismatch.
  • Do not transform cached history; legacy invalid caches may error, but new runs won’t write bad data.

^{Written for commit af30df9. Summary will update automatically on new commits.}

[cubic-dev-ai]

No issues found across 1 file

[bfollington]

Can this lead to an empty content array? That doesn't seem like it would be valid either.

[bfollington]

This is one possible solution to https://linear.app/common-tools/issue/CT-1031/interruptedaborted-tool-call-can-end-up-caching-empty-string-as

I need to check if there are any other edgecases before merging.

[cubic-dev-ai]

No issues found across 1 file