oh-my-opencode-slim/src/hooks/foreground-fallback/codemap.md

src/hooks/foreground-fallback/

Responsibility

Provides reactive model fallback for foreground (interactive) sessions when rate-limit or provider-limit signals are observed in event streams.

Design

• index.ts exports:
  • ForegroundFallbackManager
  • isRateLimitError(error)
• Manager state is per-session maps for:
  • active model (sessionModel)
  • mapped agent (sessionAgent)
  • attempted models (sessionTried)
  • dedupe timestamp (lastTrigger)
  • in-flight fallback lock (inProgress)
• Rate-limit detection is regex based and also checks structured payload fields (message, statusCode, data.message, data.responseBody).
• Fallback selection uses resolveChain(agentName, currentModel) with ordered priority:
  1. exact agent chain (if configured)
  2. no-chain if agent is known but unconfigured
  3. infer from current model
  4. flattened fallback across all chains
• Re-submission uses client.session.promptAsync with last-user message parts and parsed { providerID, modelID } target.

Flow

1. handleEvent receives each plugin event.
2. On message.updated, session.error, and retry session.status, it checks rate-limit markers and calls tryFallback(sessionID) when matched.
3. subagent.session.created updates session-to-agent mappings for better chain resolution.
4. tryFallback(sessionID) enforces:
   • feature enablement flag,
   • one-at-a-time lock,
   • dedupe window (DEDUP_WINDOW_MS = 5000).
5. It marks current model attempted, chooses next untried model from the chain, fetches latest user message via session.messages, aborts the active prompt via session.abort(), waits 500ms, and re-prompts with promptAsync.
6. Success updates session model memory; failures log structured diagnostics.
7. session.deleted cleanup removes all per-session bookkeeping to avoid memory growth.

Integration

• Wired through plugin-level event hook in src/index.ts.
• Uses ctx.client.session APIs (messages, abort, promptAsync) and depends on runtime fallback chains provided from configuration.
• Designed as an interactive-session safety net when delegated/caller-side retry logic is unavailable or too late.