Package Exports

opencode-session-fallback
opencode-session-fallback/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (opencode-session-fallback) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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": [
    "opencode-session-fallback@0.1.2"
  ]
}

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.