Summary

When a provider returns a technically successful response with stopReason=stop and payloads=0 (empty content), runWithModelFallback does not advance to the next configured fallback model. The user sees ⚠️ Agent couldn't generate a response. Please try again. even when a valid fallbacks: [...] chain is configured.

We see this 1–2 times per day with google/gemini-3-flash-preview as primary and anthropic/claude-haiku-4-5 as fallback.

Reproduction

1. Configure an agent with:

   model: {
     primary: "google/gemini-3-flash-preview",
     fallbacks: ["anthropic/claude-haiku-4-5"],
   }

2. Trigger a turn where Gemini returns stopReason=stop with empty content blocks (intermittent, ~1/200 turns in our deployment).
3. Expected: fallback to Haiku, user sees Haiku's answer.
4. Actual: user sees ⚠️ Agent couldn't generate a response. Please try again.

Root cause

runWithModelFallback (src/agents/model-fallback.ts:633) advances candidates only when the run callback throws. The embedded Pi runner (src/agents/pi-embedded-runner/run.ts:1901, the if (incompleteTurnText) branch) returns a successful result with an isError: true payload instead of throwing — so the fallback loop sees success (model-fallback.ts:788) and returns the user-facing error to the caller without trying any fallback.

HTTP 4xx/5xx errors go through coerceToFailoverError and become FailoverError instances, so the fallback chain triggers correctly for them. Only the "successful but empty" case falls through.

The internal DEFAULT_EMPTY_RESPONSE_RETRY_LIMIT = 1 (src/agents/pi-embedded-runner/run/incomplete-turn.ts:83) retries the same provider/model — it does not switch models.

Logs (from production deploy)

[agent/embedded] incomplete turn detected: runId=2d12b7f7-... sessionId=8fe3bddf-... stopReason=stop payloads=0 — surfacing error to user

Suggested fix

In src/agents/pi-embedded-runner/run.ts ~line 1901, inside the if (incompleteTurnText) block, throw a FailoverError with reason: "empty_response" when:

• attempt.replayMetadata.replaySafe === true (no side-effects yet — Tool calls already done would be unsafe to replay), and
• a fallback candidate is still available (caller-provided hint, e.g. params.fallbacksRemaining > 0).

Otherwise keep the existing return path so we don't replay turns that already sent messages or executed mutating tools.

Sketch:

// run.ts ~1901
if (incompleteTurnText) {
  // existing logging + lifecycle marks ...

  if (
    attempt.replayMetadata.replaySafe &&
    (params.fallbacksRemaining ?? 0) > 0
  ) {
    throw new FailoverError(
      "empty response (payloads=0) — failing over to next model",
      {
        reason: "empty_response",
        provider: activeErrorContext.provider,
        model: activeErrorContext.model,
      },
    );
  }
  // existing return path ...
}

FailoverError reason union (src/agents/pi-embedded-helpers/errors.ts) needs "empty_response" added. runWithModelFallback already treats every FailoverError instance as a failover trigger via isFailoverError(normalized) (model-fallback.ts:868), so no additional change to the fallback loop should be needed.

The runner needs to know whether a fallback chance exists — pass fallbacksRemaining (or similar) from runWithModelFallback into the run callback.

Test plan

• Mock provider returns stopReason=stop, payloads=[].
• Agent with model.primary=mock-empty, fallbacks=["mock-good"] → second call hits mock-good, final result is from the fallback.
• Negative: no fallbacks configured → keep current user-error behavior.
• Negative: replayMetadata.replaySafe=false → no failover (side-effects already happened).
• Cache stability: empty-payload turns must not invalidate the cached prefix on the failover model unless re-prompting requires it.

Environment

• OpenClaw: 2026.5.3
• Primary: google/gemini-3-flash-preview
• Fallback: anthropic/claude-haiku-4-5
• Frequency: 1–2× per day in our production deployment

Downstream context

I'm tracking this on the deploy side as HendrikHarren/openclaw-deploy#124 and #127, and have a deploy-repo PR (HendrikHarren/openclaw-deploy#TBD) that fixes a separate config-side bug (Helm template was emitting fallback: "string" singular instead of fallbacks: [array], which OpenClaw silently ignored). The deploy fix at minimum restores HTTP-5xx fallback behaviour. The empty-payload case described here remains.

Happy to send a PR with the fix + tests if maintainers think the suggested approach is right.