@voidrot/opencode-router

An OpenCode provider plugin that wraps any OpenAI-compatible API (e.g. LiteLLM) with:

• Defensive XML tool-call parsing — catches tool calls emitted as <task agent="...">, <tool_call>, <function=...>, <task skill="...">, and other XML formats that some models produce instead of native function-call JSON.
• Fallback model chains — transparently retry with alternative models when the primary model fails.
• Configurable retry backoff — exponential backoff with jitter, per-status-code retry limits.
• finish_reason correction — overrides "stop" to "tool-calls" when tool calls are detected, preventing OpenCode from prematurely ending the agent loop.

Installation

npm install @voidrot/opencode-router

Peer dependencies (bring your own versions):

npm install ai @ai-sdk/openai-compatible

Usage

In your opencode.json:

{
  "provider": {
    "my-router": {
      "npm": "@voidrot/opencode-router",
      "options": {
        "baseURL": "http://localhost:4000",
        "apiKey": "your-key",
        "fallbackModels": ["backup-model-id"],
        "retryBaseDelayMs": 1000,
        "retryMultiplier": 2,
        "allowedFails": {
          "429": 3,
          "503": 2
        }
      },
      "models": {
        "my-primary-model": {
          "name": "Primary Model",
          "fallbackModels": ["my-backup-model"]
        }
      }
    }
  }
}

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | baseURL | string | — | Base URL of the OpenAI-compatible API | | apiKey | string | — | API key | | fallbackModels | string[] or Record<string, string[]> | [] | Global or per-model fallback chains | | retryBaseDelayMs | number | 1000 | Base delay for exponential backoff | | retryMultiplier | number | 2 | Backoff multiplier per retry | | allowedFails | Record<string, number> | {} | Number of retries per HTTP status code (e.g. { "429": 3 }) |

License

MIT