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.0"
  ]
}

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

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.
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.