opencode-stability-guard

OpenCode stability plugin focused on the local entrypoint that fronts the Thailand llm-failover-gateway chain.

What It Does

• Injects proxy env vars into the Bun process at startup
• Monitors Cloudflare Tunnel entrypoint and remote gateway /healthz
• Distinguishes gateway health failures from remote gateway degradation
• Restarts the local gateway LaunchAgent when repairable local failures are detected
• Attempts session-level recovery for transient network failures
• Writes debug logs only when debug mode is enabled

Installation

{
  "plugin": [
    "[email protected]",
    "opencode-openai-codex-auth"
  ]
}

Place it before auth/provider plugins so proxy bootstrap and watchdog are ready before outbound requests start.

Environment

| Variable | Default | Description | |----------|---------|-------------| | OPENCODE_STABILITY_PROXY_URL | http://127.0.0.1:7897 | Proxy bootstrap target | | OPENCODE_STABILITY_ENTRYPOINT | https://ai.d4w2sa.top | Cloudflare Tunnel / gateway entrypoint | | OPENCODE_STABILITY_GATEWAY_MODE | remote | remote = treat gateway as signal source only (CF Tunnel) | | OPENCODE_STABILITY_POLL_MS | 15000 | Background watchdog interval | | OPENCODE_STABILITY_FAILURE_THRESHOLD | 2 | Consecutive failures before repair | | OPENCODE_STABILITY_REPAIR_COOLDOWN_MS | 60000 | Cooldown after repair | | OPENCODE_STABILITY_SESSION_RETRY_LIMIT | 3 | Max automatic continue retries per session | | OPENCODE_STABILITY_DEGRADED_NOTIFY_AFTER_MS | 600000 | Remote degraded state must remain stable for 10 minutes before a toast is shown | | OPENCODE_STABILITY_RECOVERY_NOTIFY_AFTER_MS | 60000 | Recovery must remain stable for 1 minute before a success toast is shown | | OPENCODE_STABILITY_TOASTS | true | Show repair/degraded toasts | | OPENCODE_STABILITY_GATEWAY_KEY | REMOTE_CLIPROXY_API_KEY | Auth key used by business probes | | OPENCODE_STABILITY_DEBUG | false | Enable file-based debug logging | | OPENCODE_STABILITY_DEBUG_LOG | ~/.local/state/opencode/stability-guard.log | Debug log path |

Debug Logging

The plugin never writes diagnostics to stdout/stderr during normal operation. When OPENCODE_STABILITY_DEBUG=1, it appends structured lines to the debug log file so FRP jitter and chain-level failures can be analyzed later without polluting the OpenCode TUI.

Useful events:

• health_snapshot — watchdog or session-error evaluation result
• session_error_received — raw session.error payload type, normalized text, recoverable flag
• session_error_ignored — why a session.error was not eligible for automatic recovery
• session_resume_wait_start / session_resume_wait_tick / session_resume_wait_end — bounded recovery window while local listener comes back
• session_resume_decision — why a failed session was resumed or skipped
• session_resume_skip — skipped because retry limit, single-flight recovery, or cooldown was active
• session_resume_sent / session_resume_failed — automatic continue outcome

The guard now treats transient TLS / certificate verification failures as recoverable network faults and can issue speculative continue retries when TCP to the entrypoint is still reachable but HTTPS probes are temporarily failing.

Automatic continue retries are capped per active recovery window. Once the session resumes normal assistant output, the retry budget is reset so long-lived sessions do not permanently exhaust recovery after a few unrelated transient faults.

Sidecar Compatibility

When opencode-tool-liveness is installed alongside the guard, this plugin also writes best-effort recovery summaries to .opencode/tool-liveness/guard.json and appends session.recovery lines into .opencode/tool-liveness/events.jsonl. This keeps observability and callback summaries outside the OpenCode core while preserving the guard's existing recovery behavior.