opencode-session-fallback

OpenCode plugin that catches quota/auth-pool exhaustion on a running session and resumes the same sessionID on a configured fallback lane.

What It Does

• Listens to session.error events from OpenCode
• Detects quota/auth-pool exhaustion signatures such as:
  • auth_unavailable + no auth available
  • insufficient_quota
  • quota exceeded
• Resolves the current agent from session history
• Reads agent markdown frontmatter to find:
  • fallback_agent on the source agent
  • model on the fallback agent
• Aborts the failed turn and injects a continuation prompt into the same session with the fallback model and fallback system prompt

The plugin does not require patching OpenCode core. It relies on the existing plugin event surface and the session prompt API.

Agent Contract

The source agent should declare a fallback target:

---
fallback_agent: metis
---

The fallback agent should declare the model it runs on:

---
model: cliproxy_gpt/gpt-5.4
---

The fallback prompt body is appended to a short continuation system block so the new lane keeps working from the same session state instead of restarting.

Installation

{
  "plugin": [
    "[email protected]"
  ]
}

In opencode-heartbeat, the recommended entrypoint is role-level heartbeat.json -> opencode.extraPlugins.

For the bundled cliproxy_fault/* drill provider used by end-to-end validation, the plugin also treats the Anthropic SDK connectivity wrapper error as an eligible fallback signal. This branch is test-only and scoped to the cliproxy_fault/ provider prefix.

Environment

| Variable | Default | Description | |----------|---------|-------------| | OPENCODE_SESSION_FALLBACK_ATTEMPT_LIMIT | 1 | Max automatic retries per session | | OPENCODE_SESSION_FALLBACK_DEBUG | false | Enable file-based debug logging | | OPENCODE_SESSION_FALLBACK_DEBUG_LOG | log/opencode-session-fallback.debug.log | Debug log path |

Behavior Notes

• Recovery is session-local. The plugin retries on the same sessionID.
• The default retry budget is one automatic continuation per session.
• The plugin listens to both session.error and session.status(type=retry) so provider-auth pool exhaustion can be intercepted before OpenCode collapses the turn into a generic terminal abort.
• Recovery currently uses model + system override and does not depend on OpenCode core accepting agent: metis from every caller.
• If the plugin cannot resolve the fallback target from agent markdown, it leaves the original error untouched.