fix(runtime-fallback): 9 critical bug fixes for auto-retry, agent preservation, and model override

[youngbinkim0]

Summary

Fixes 9 critical bugs in the runtime-fallback feature from #1408 that prevented it from working end-to-end. After these fixes, runtime-fallback correctly:

• Detects Anthropic "credit balance too low" errors (HTTP 400)
• Automatically retries with the next fallback model
• Preserves the original agent identity during retry
• Allows manual model override via the UI without being overridden by fallback state

Related PR

This builds on top of #1408 (feat/runtime-fallback-only). All fixes are applied to the same branch.

Bug Fixes (9 total)

1. extractStatusCode() missed nested data.statusCode

Problem: Anthropic errors have structure {name: "APIError", data: {statusCode: 400, message: "..."}} but extractStatusCode only checked top-level status/statusCode properties.
Fix: Added (errorObj.data as Record<string, unknown>)?.statusCode check.

2. Error regex pattern too strict

Problem: /credit.?balance.?too.?low/ failed because actual Anthropic message has multi-character gaps between words.
Fix: Changed to /credit.*balance.*too.*low/i.

3. Zod schema rejected valid config silently

Problem: Schema had .max(10) for max_fallback_attempts, but users could reasonably want more. Zod silently rejected the entire runtime_fallback block when any field failed validation.
Fix: Bumped schema limit to .max(20).

4. getFallbackModelsForSession() returned empty array

Problem: session.error event doesn't include agent and session IDs don't contain agent names for main sessions. The function couldn't find fallback models.
Fix: Added fallback logic: try "sisyphus" first, then iterate all known agents until one with fallback_models is found.

5. "No model info available, cannot fallback"

Problem: Neither session.error nor session.created events include the current model. Without a model, createFallbackState() couldn't be initialized.
Fix: Added detectAgentFromSession() helper to derive model from agent config when event data is missing.

6. No auto-retry after fallback model selection

Problem: The hook set pendingFallbackModel but required the user to manually resend their message.
Fix: Added ctx.client.session.promptAsync calls that fetch the last user message from the session and resend it with the fallback model. Added sessionRetryInFlight guard to prevent double-retries.

7. Fallback model reverted after one message

Problem: chatMessageHandler cleared pendingFallbackModel after one use, so subsequent messages reverted to the original (failing) model.
Fix: Changed to persistent override: checks state.currentModel !== state.originalModel on every chat.message and applies the fallback model continuously.

8. Manual UI model changes overridden by persistent fallback

Problem: After fix #7 made fallback persistent, users could no longer change models via the UI because the fallback state would override their selection.
Fix: Added detection in chatMessageHandler: if requestedModel !== state.currentModel, the user changed the model manually, so reset fallback state via createFallbackState(requestedModel).

9. Auto-retry defaulted to Sisyphus agent

Problem: promptAsync body only included model + parts, no agent field. OpenCode defaults to "sisyphus" when agent is omitted.
Fix: Added agent: resolvedAgent to both auto-retry promptAsync calls. Also added:

• resolveAgentForSession() with 3-tier resolution: event agent → session memory → session ID pattern
• normalizeAgentName() for display variants like "Prometheus (Planner)" → "prometheus"
• resolveAgentForSessionFromContext() that fetches recent messages to find agent

Additional Improvements

• Added 400 to default retry_on_errors (Anthropic "credit balance" = HTTP 400)
• Added credit.*balance.*too.*low and insufficient.?credits? patterns to RETRYABLE_ERROR_PATTERNS
• Moved AGENT_NAMES and agentPattern to module scope for reuse
• Registered runtimeFallback hooks in event.ts and chat-message.ts
• Cleanup of sessionRetryInFlight in session deletion and stale session cleanup
• User message extraction reads from message.parts first, then message.info.parts

Files Changed

File	Changes
src/hooks/runtime-fallback/index.ts	All 9 bug fixes, agent resolution, auto-retry logic
src/hooks/runtime-fallback/index.test.ts	New agent preservation test, updated mocks
src/hooks/runtime-fallback/constants.ts	Added 400 to retry codes, credit balance patterns
src/config/schema/runtime-fallback.ts	Bumped max_fallback_attempts to 20
src/plugin/chat-message.ts	Register runtimeFallback chat.message hook
src/plugin/event.ts	Register runtimeFallback event hook

Key Discoveries

1. Anthropic "credit balance too low" = HTTP 400 (not 402). Error type is invalid_request_error.
2. OpenCode's session.error event is sparse — only sessionID + error. No agent, no model.
3. Zod validation silently rejects entire config section on any field failure.
4. OpenCode defaults to sisyphus when agent omitted from promptAsync body.
5. Agent names in events can be display names (e.g., "Prometheus (Planner)") — need normalization.

Testing

• ✅ 25 tests passing (bun test src/hooks/runtime-fallback/index.test.ts)
• ✅ Typecheck clean (bun run typecheck)
• ✅ Manually verified end-to-end: Anthropic credit error → auto-fallback → auto-retry → correct agent preserved → manual model override works

---

Summary by cubic

Fixes runtime-fallback so it reliably auto-switches and retries on provider errors, preserves the right agent, and respects manual model changes. Adds agent/category fallback_models with provider-aware selection and a runtime_fallback config for cooldowns, session timeouts, and notifications.

• New Features

  • runtime_fallback config (enabled, retry_on_errors incl 400, max_attempts up to 20, cooldown, timeout, toast).
  • Support fallback_models on agents and categories; model resolution honors them at init and runtime with provider checks.
  • Auto-retry resends the last user message with the resolved agent; persistent override until the user changes models.

• Bug Fixes

  • Broaden error detection and status parsing (Anthropic credit errors on 400, nested data.statusCode, stricter status code matching).
  • Robust model/agent resolution when events lack data; agent preserved in auto-retry with guards against double retries.
  • Persistent fallback across messages with correct reset on manual model changes; fix provider constraints for userFallbackModels.
  • Harden fallback progression and success detection; add per-model cooldown and session-level timeout to advance when a model hangs.

^{Written for commit 3d0e070. Summary will update on new commits.}

[github-actions]

All contributors have signed the CLA. Thank you! ✅
_{Posted by the CLA Assistant Lite bot.}

[youngbinkim0]

I have read the CLA Document and I hereby sign the CLA

[youngbinkim0]

recheck

[youngbinkim0]

recheck

[cubic-dev-ai]

2 issues found across 27 files

Confidence score: 3/5

• Potential user-impacting inconsistency in src/shared/model-resolution-pipeline.ts: new userFallbackModels reads connected providers only from cache, ignoring constraints.connectedProviders, which could change model resolution behavior.
• Code duplication in src/hooks/runtime-fallback/index.ts auto-retry handlers raises maintenance risk and could lead to subtle divergence, though it’s not an immediate blocker.
• Pay close attention to src/shared/model-resolution-pipeline.ts and src/hooks/runtime-fallback/index.ts - connected provider handling and duplicated retry logic.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="src/hooks/runtime-fallback/index.ts">

<violation number="1" location="src/hooks/runtime-fallback/index.ts:473">
P2: Significant code duplication in auto-retry logic between `session.error` and `message.updated` event handlers. The logic for fetching session messages, extracting the last user message, parsing parts, and calling `promptAsync` is duplicated almost verbatim (approximately 40+ lines). This increases maintenance burden and risk of inconsistencies.</violation>
</file>

<file name="src/shared/model-resolution-pipeline.ts">

<violation number="1" location="src/shared/model-resolution-pipeline.ts:105">
P1: Inconsistent handling of `constraints.connectedProviders` - the new `userFallbackModels` logic reads connected providers only from cache, ignoring the `constraints.connectedProviders` parameter that is respected in `categoryDefaultModel` and `fallbackChain` logic. This prevents callers from enforcing specific provider constraints in the user fallback code path.</violation>
</file>

---

Since this is your first cubic review, here's how it works:

• cubic automatically reviews your code and comments on bugs and improvements
• Teach cubic by replying to its comments. cubic learns from your replies and gets better over time
• Add one-off context when rerunning by tagging @cubic-dev-ai with guidance or docs links (including llms.txt)
• Ask questions if you need clarification on any suggestion

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}