13-sep: [conocimiento] guia OmniRoute autorouting auto/* + fix checker + listados videoclub

documentacion/omniroute-guia-autorouting-combos.md

@@ -0,0 +1,110 @@
+# 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.