# OmniRoute — Guía autorouting y combos `auto/*`

Fecha: 13-sep-2026 · Estado: documentación estable para replicar en cualquier equipo (sobremesa / portátil / VPS)

---

## 1. Qué es OmniRoute en este setup

OmniRoute es un **proxy/router de modelos** self-hosted que corre en local. Hace routing entre tus proveedores conectados con fallback automático, circuit breakers, y combos virtuales.

- **Servidor**: paquete npm global `omniroute`
  - Comando: `omniroute serve` → lanza `node .../omniroute/dist/server-ws.mjs`
  - Escucha en: `http://localhost:20128` (OpenAI-compatible `/v1`)
- **Datos**: `C:\Users\juanm\.omniroute\`
  - `storage.sqlite` (estado, streaks, kv de combos)
  - `call_logs\AAAA-MM-DD\*.json` (cada request ruteado: modelo real elegido, tokens, fallbacks)
  - `logs\application\app.log` (routing trace: decisiones, fallbacks, límites)
  - `.env` (config servidor, secretos — nunca exponer)
  - `server\.pid` / `supervisor\.pid`
- **Supervisor**: `omniroute.mjs serve` es el padre; el worker real es `server-ws.mjs`
- **Sin autostart por tarea programada en sobremesa** (se lanza manualmente). Replicar igual en portátil.

## 2. Estado actual: bug de opencode y los 38 modelos manuales

**Problema raíz**: el plugin `@omniroute/opencode-plugin` no puede registrar providers fuera del catálogo models.dev de opencode → los `auto/*` NO aparecen en el picker por defecto.
- Issues: anomalyco/opencode **#38839** (provider hook skipped for non-catalog providers) y **#25630** (Regression: plugin provider.models() hook no longer populates custom providers, post #25167).

**Workaround aplicado (decisión: mantener hasta que se arregle el bug)**:
- Los **38 modelos `auto/*`** están declarados **a mano** en `~/.config/opencode/opencode.jsonc` → sección `provider.omniroute`,
  con label amigable (`Auto ♟ Best Coding`, etc.) y `baseURL: http://localhost:20128/v1`, `npm: @ai-sdk/openai-compatible`.
- El plugin se carga con: `providerId: omniroute`, `baseURL: http://localhost:20128`.
- El **enrutado y el failover funcionan igual aunque los modelos estén a mano**: la lógica de routing vive 100% en el servidor OmniRoute, opencode solo manda el nombre `auto/...` a `localhost:20128`. El picker manual solo afecta al catálogo visible, NO al comport­amiento de routing.

**Check automático del fix**:
- `scripts/check_omniroute_fix.ps1` (tarea programada `OmnirouteFixCheck`, diaria 09:00) consulta los issues #38839/#25630.
- Si alguno está cerrado → crea `documentacion/omniroute_fix_fixed.flag` y actualiza `documentacion/omniroute_fix_status.txt`.
- Cuando exista ese flag: avisar al usuario → reactivar catálogo dinámico del plugin y quitar los 38 modelos manuales de `opencode.jsonc`.

## 3. Cómo funciona el routing `auto/*` (mecánica por detrás)

Los `auto/*` **no son modelos reales**: son **alias virtuales de ruta**. OmniRoute los materializa al vuelo en cada request sin guardarlos en la BD (tabla `combos` vacía).

Flujo real (trace de `app.log`):
```
POST /v1/chat/completions | auto/best-coding | 28 msgs | 71 tools
Virtual auto-combo created: auto/best-coding (2 candidates)          ← shortlist puntuada
Combo "auto/best-coding" [auto] with 13 models                       ← pool total (nested "auto")
auto with nested resolution: 13 total targets
Auto selection: oc/big-pickle | intent=medium task=default | strategy=lkgp | LKGP
Trying model 1/8: oc/big-pickle
ROUTING oc/big-pickle ⇒ opencode/big-pickle                          ← modelo REAL elegido
Model oc/big-pickle succeeded (880ms, 0 fallbacks)
```

- En cada request el **Auto-Combo Engine puntúa a los candidatos con 15 factores**: salud del provider, cuota restante, coste, latencia, task fit, calidad, disponibilidad de sesión, etc.
- **`lkgp` = Last-Known-Good**: sticky al último target que funcionó mientras siga OK (no cambia por aburrimiento).
- **Fallback automático**: si el elegido falla (429/5xx/timeout), re-engancha al siguiente candidato **dentro del mismo request** (sin que opencode se entere).
- **Recuperación**: circuit breakers/cooldowns auto-reset; el primer éxito limpia el estado de error. Un candidato agotado deja de ganar el scoring y vuelve cuando recupera cuota.

### Mapa de variantes (catalog real, `open-sse/services/autoCombo/builtinCatalog.ts`)

| Modelo | Variante | Optimiza |
|---|---|---|
| `auto` | default | Balanceado (LKGP) |
| `auto/best-coding` | `coding` | Quality-first para código |
| `auto/best-reasoning` | `smart` | Calidad + 10% exploración |
| `auto/best-fast` | `fast` | Menor latencia |
| `auto/best-vision` | `smart` (+filtro visión) | Calidad en inputs visuales |
| `auto/best-chat` | default | Chat general |
| `auto/best-coding-fast` | `fast` | Velocidad en código |
| `auto/best-free` | `cheap` | Solo tier free |
| `auto/best-chaos` | `chaos` | Despacho paralelo top-N |
| `auto/pro-*` | idem | Tier de pago forzado |
| `auto/coding`, `auto/fast`, `auto/cheap`, `auto/offline`, `auto/smart`, `auto/chat` | idem | Variantes básicas |
| `auto/coding:fast`, `auto/coding:pro`, `auto/vision`, `auto/multimodal`, `auto/reasoning` | sufijo | Categoría[:tier] |
| `auto/gemini`, `auto/llama`, `auto/glm`, `auto/claude-sonnet`, `auto/claude-opus`... | familia | Solo esa familia como candidatos |

Los 38 declarados a mano en opencode.jsonc son este catálogo `auto/*`.

## 4. Límites y quotas

- **Límite de contexto del combo `auto/*`: 200.000 tokens (`source=target`)** — confirmado en logs: `Combo context limit: 200000 (source=target)`.
  - `source` = lo que opencode envía (conversación + tools)
  - `target` = lo que el modelo de destino admite
- **Salida (out)**: sin tope fijo en el combo; depende del modelo real que rute en ese momento.
- **"¿Me bloquean por usarlo varios días?"**: NO. Los bloqueos (circuit breaker / model lockout) solo saltan ante fallos reales repetidos (429/5xx/timeout) y se auto-recuperan. El único bloqueo real sería agotar la cuota de TODOS los candidatos a la vez (cuenta opencode = `big-pickle` + reserva del pool).

## 5. Candidatos actuales para `auto/best-coding` (13-sep-2026)

- **Shortlist directa: 2 candidatos** (log: `2 candidates`). Ganador actual estable: `oc/big-pickle` → provider `opencode` (cuenta opencode, API key `OMNI-1`).
- **Pool anidado: 13 targets** (combo base `auto` con "nested resolution").
- **Intentos de fallback por request: hasta 8** (`Trying model 1/8`); si todos fallan → error al usuario.
- La identidad exacta del 2º candidato **no está persistida** en la BD: la construye el engine en runtime puntuando tus conexiones. Para verla en vivo: `call_logs` o `logs/application/app.log` (líneas con `Auto selection:`/`VRouting`).

## 6. Replicación en el portátil

Para que el asistente del portátil deje todo igual:

1. **Instalar servidor**: `npm i -g omniroute` (mismo paquete que en sobremesa).
2. **Config `.omniroute`**: copiar `C:\Users\juanm\.omniroute\.env` (secretos) y, si se quiere historial, `storage.sqlite` + `call_logs`.
3. **Lanzar**: `omniroute serve` (debe quedar escuchando en `http://localhost:20128`).
4. **Config opencode** (`~/.config/opencode/opencode.jsonc`):
   - Plugin: `file:///C:/Users/juanm/AppData/Roaming/opencode/plugins/omniroute/dist/index.js` con `{ "providerId": "omniroute", "baseURL": "http://localhost:20128" }`
   - Provider `omniroute`: `npm @ai-sdk/openai-compatible`, `baseURL http://localhost:20128/v1`, los 38 modelos `auto/*` (ver sección 3 para el catálogo; el JSON exacto está en el opencode.jsonc de la sobremesa).
5. **Fix checker**: copiar `scripts/check_omniroute_fix.ps1` + tarea `OmnirouteFixCheck` (diaria 09:00).
6. Comprobar en `logs/application/app.log` que aparece `Combo context limit: 200000 (source=target)`.

## 7. Origen de esta guía

Recopilado 13-sep-2026 en sesión RE (sobremesa): logs reales del servidor, `builtinCatalog.ts` del paquete npm, y verificación en vivo con requests de opencode bajo `omniroute/auto/best-coding`. Memoria Engram asociada (project `biblioteca_conocimiento_laboratorio`): "Cómo funcionan los modelos auto/* de OmniRoute (alias virtuales + routing)". Esta guía se sincroniza a todos los equipos vía git + Engram Cloud para que el asistente pueda aplicarla en el portátil.