@bivelio/savings-layer 0.4.25 → 0.4.26

package/docs/terminales/README.md

@@ -42,11 +42,17 @@ igual.
 | [Codex CLI](codex.md) | `http://127.0.0.1:8402/v1` (API key) · `…/backend-api/codex` (ChatGPT) | **con** | `codex -c openai_base_url=…` | `bvsala codex` ✅ | [V] validado en mano el 30-08 (426 → fallback HTTP, stream íntegro) |
 | [Goose](goose.md) | `http://127.0.0.1:8402` | **sin** | env `ANTHROPIC_HOST` | `bvsala goose` ✅ | [V] |
 | [Qwen Code](qwen-code.md) | `http://127.0.0.1:8402` | **sin** | env `ANTHROPIC_BASE_URL` + `~/.qwen/settings.json` | `bvsala qwen` ✅ | [V] |
-| [opencode](opencode.md) | `http://127.0.0.1:8402/v1` | **con** | `~/.config/opencode/opencode.json` | — (config de usuario) | [V] |
+| [opencode](opencode.md) | `http://127.0.0.1:8402/v1` | **con** | env `OPENCODE_CONFIG_CONTENT` o `~/.config/opencode/opencode.json` | `bvsala opencode` ✅ (sin escribir en disco) | [V] en código (v1.18.32) |
+| [Kilo Code](kilo.md) (CLI y extensiones) | `http://127.0.0.1:8402/v1` | **con** | env `KILO_CONFIG_CONTENT` o `~/.config/kilo/kilo.json` | `bvsala kilo` ✅ (CLI) | [V] en código (v7.8.1, fork de opencode) |
+| [Copilot CLI](copilot.md) (solo BYOK) | anthropic: `http://127.0.0.1:8402` · openai: `…/v1` | anthropic **sin**, openai **con** | env `COPILOT_PROVIDER_BASE_URL` | `bvsala copilot` ✅ (tipo anthropic) | [V] en la doc oficial; sin validar en mano. Tipo openai: a mano, sin validar (WebSocket → 426) |
+| [Copilot en VS Code](copilot.md#copilot-en-vs-code-byok-custom-endpoint) (solo BYOK) | `http://127.0.0.1:8402/v1/messages` (ruta completa) | ruta completa | UI → Custom Endpoint (`chatLanguageModels.json`) | — | [V] en la doc oficial; sin validar en mano |
+| [Aider](aider.md) | Anthropic: `http://127.0.0.1:8402` · OpenAI: `…/v1` | Anthropic **sin**, OpenAI **con** | env `ANTHROPIC_API_BASE` / `OPENAI_API_BASE` (litellm) | `bvsala aider` ✅ | [V] en código (litellm 1.82.3); OpenAI en stream solo con `BVSALA_GATEWAY_USAGE_INJECT=1` |
+| [Continue](continue.md) (CLI `cn` y extensiones) | `http://127.0.0.1:8402/v1` | **con** | `~/.continue/config.yaml` (`apiBase`) | — (config de usuario) | [V] en código |
 | [Crush](crush.md) | `http://127.0.0.1:8402/v1` | **con**, sin barra final | `~/.config/crush/crushrc` | — (config de usuario) | [V] |
 | [Droid](droid.md) | `http://127.0.0.1:8402` | sin **[I]** | `~/.factory/settings.json` | — (config de usuario) | validar en mano |
 | [Cline](cline.md) | `http://127.0.0.1:8402/v1` | **con** | UI | — | [V] |
-| [Kilo Code](kilo.md) | `http://127.0.0.1:8402/v1` | con **[I]** | UI | — | validar en mano |
+| [Gemini CLI](no-soportados.md#gemini-cli--no-se-mide-todavía) | — | — | env `GOOGLE_GEMINI_BASE_URL` | — | **no se mide**: el gateway no lee el dialecto de Gemini |
+| [Cursor](no-soportados.md#cursor--no-se-puede) | — | — | sus servidores, no tu máquina | — | **no se puede**: Cursor no alcanza `127.0.0.1` |
 | [Python y cualquier SDK](../../README.md#python-and-any-other-language-the-local-gateway) (OpenAI · Anthropic) | OpenAI: `http://127.0.0.1:8403/v1` · Anthropic: `http://127.0.0.1:8402` | OpenAI **con**, Anthropic **sin** | `base_url` del SDK | `bvsala gateway --upstream openai` | [V] en test (upstream falso) |
 
 Reglas de la columna «Base URL»: **nunca barra final**, **nunca redirecciones**
@@ -54,12 +60,28 @@ Reglas de la columna «Base URL»: **nunca barra final**, **nunca redirecciones*
 en vez de seguirlo). Y nunca copies el URL de un terminal a otro: cada SDK añade
 su propio tramo de ruta y el error es silencioso (§ «Comprobar que mide»).
 
-Claude Code, Codex, Goose y Qwen Code tienen **envoltorio propio** (`bvsala
-claude|codex|goose|qwen`): arrancan un gateway en puerto efímero, lanzan el
-terminal apuntándole y lo apagan al salir. Cero configuración persistente. La
+Claude Code, Codex, Goose, Qwen Code, opencode, Kilo, Copilot CLI (BYOK) y Aider
+tienen **envoltorio propio** (`bvsala
+claude|codex|goose|qwen|opencode|kilo|copilot|aider`): arrancan un gateway en
+puerto efímero, lanzan el terminal apuntándole y lo apagan al salir. Cero
+configuración persistente: opencode y Kilo reciben la suya por variable
+(`OPENCODE_CONFIG_CONTENT`, `KILO_CONFIG_CONTENT`), fusionada con la tuya. La
 receta manual de cada guía hace exactamente lo mismo. Para el resto,
 `bvsala doctor` imprime el bloque exacto de cada terminal instalado.
 
+**Al salir, cada envoltorio dice lo que midió.** Dentro de un envoltorio el log
+por petición va callado para no pisar el TUI, así que al terminar imprime por
+stderr una línea como esta:
+
+```
+[bvsala copilot] metering in this run: 41 request(s) metered with the provider's usage · 3 forwarded but NOT metered (nothing is estimated in their place): 3 × the request did not ask for usage (stream_options.include_usage). What each reason means and what to do: docs/terminales/README.md.
+```
+
+Los motivos son los de la tabla `· not metered: …` de abajo. Si ninguna petición
+pasó por el gateway, lo dice también: el terminal no estaba apuntado. `bvsala
+gateway` imprime la misma línea al pararlo con Ctrl-C. Es local, como el aviso de
+tráfico degradado: no viaja a BiVelio.
+
 ## Lo común a todas las guías
 
 ### 1 · Instalar y arrancar el gateway
@@ -192,12 +214,15 @@ Y una condición dura: el terminal debe estar instalado con su **instalador
 nativo** (un `claude.exe` / `codex.exe` en el PATH — Claude Code, Codex, Goose
 y Qwen Code lo tienen [V]). El shim `.cmd` que deja `npm i -g <terminal>` no
 puede lanzarse de forma segura con argumentos (CVE-2024-27980) y `bvsala` se
-niega con una guía en vez de fallar con un ENOENT mudo.
+niega con una guía en vez de fallar con un ENOENT mudo. opencode, Kilo y Copilot
+CLI también se instalan por npm: en Windows, usa su binario nativo (releases de
+GitHub, winget o scoop) **[I: no validado en Windows]**. Aider se instala con pip,
+que deja un `aider.exe`.
 
 ### 4 · Regla BYOK, sin excepción
 
-Todas las recetas del anillo 2 (Goose, Qwen Code, opencode, Crush, Droid, Cline,
-Kilo) son **API key exclusivamente**. Anthropic prohíbe usar el OAuth de Claude
+Todas las recetas del anillo 2 (Goose, Qwen Code, opencode, Kilo, Copilot, Aider,
+Crush, Droid, Cline, Continue) son **API key exclusivamente**. Anthropic prohíbe usar el OAuth de Claude
 Pro/Max en harnesses de terceros (opencode lo documenta; Crush retiró su OAuth en
 ene-2026). El gateway reenviaría un Bearer de suscripción sin inmutarse — y eso
 no se promociona ni se documenta como receta.
@@ -235,10 +260,33 @@ byte:**
   cache TTL, the advisor, context management, OAuth, and betas that do not exist
   yet). Three kinds stay on the hop from your client to the gateway, as HTTP
   requires: hop-by-hop headers (RFC 7230 §6.1, plus `expect` and any header named
-  in `Connection`), `host` and `content-length`.
+  in `Connection`), `host` and `content-length`. One more stays with the gateway
+  because it is addressed to it: `x-bvsala-report`, with which a client asks for
+  its per-request report (below).
 - **The response**: the same bytes and headers, except the transport ones
   (`content-encoding`, `content-length`, `transfer-encoding`), because the
-  gateway receives the body already decompressed.
+  gateway receives the body already decompressed. A request sent with
+  `x-bvsala-report: 1` also gets one header added, `x-bvsala-request-id`; a
+  request without it gets none.
+
+**Per-request reports, in any language.** Send `x-bvsala-report: 1` with a
+request and the gateway keeps the report it recorded for your dashboard for
+that request, and answers with `x-bvsala-request-id`. Read it back from the
+same gateway with `GET /_bvsala/v1/reports/<x-bvsala-request-id>` or
+`GET /_bvsala/v1/reports?response_id=<the id of the provider's response>`;
+add `wait_ms=<milliseconds>` (30,000 at most) to wait for a request still in
+flight. The answer carries `status` (`metered`, `not_metered` with the same
+`reason` as the log line, or `pending`) and, when metered, the `SavingsReport`
+the gateway queued for your dashboard: nothing is computed for this answer.
+`GET /_bvsala/v1/status` returns the gateway's version, upstream origin and
+license state. These routes are answered by the gateway and never forwarded;
+the gateway listens on 127.0.0.1 only, they send no CORS headers, they answer
+403 to a `Host` other than 127.0.0.1 or localhost (so a web page cannot reach
+them by rebinding its own name to 127.0.0.1), no route lists reports (you need
+the id), and like every other route they answer 402 when the license does not
+serve. The gateway
+keeps the last 1,000 reports for one hour at most, in memory; nothing is
+written to disk and nothing more is sent to BiVelio.
 
 "No lever armed" means any of: a license without that lever's feature,
 `BVSALA_GATEWAY_ELISION=0`, or a lever you have not turned on (the sibling
@@ -254,7 +302,7 @@ would fail it.
 | Lever | Applies to | What changes | What does not |
 |---|---|---|---|
 | Cache TTL (`cache_ttl_tuning`, on by default with PRO) | `/v1/messages` requests where a large part of the prompt is new (session start, compaction); a chained turn travels untouched | every `cache_control` with `ttl: "1h"` becomes `"5m"`, the top-level one included (a 1-hour top-level marker behind 5-minute block markers would be a 400) | a key named `cache_control` inside a tool call's `input` or a tool's `input_schema` is content and stays as it is; so does the advisor's `caching`; headers are untouched |
-| Per-turn effort (`BVSALA_GATEWAY_ESFUERZO=low…max`) | `/v1/messages` for `claude-fable-5-1`, `claude-mythos-5-1` and `claude-opus-5`, when the request carries no `output_config` of its own (top level or in a message) | one message appended at the end of `messages`, `{"role":"system","content":[],"output_config":{"effort":…}}`, and `mid-conversation-output-config-2026-07-01` appended after your `anthropic-beta` value | your `anthropic-beta` value is kept verbatim in front; nothing earlier in `messages` moves |
+| Per-turn effort (`BVSALA_GATEWAY_ESFUERZO=low` or `medium`) | `/v1/messages` for `claude-fable-5-1`, `claude-mythos-5-1`, `claude-opus-5-5` and `claude-opus-5`, when the level is below the model's default effort (`high`; `medium` on `claude-opus-5-5`) and the request carries no `output_config` of its own (top level or in a message); a level at or above the default leaves the request untouched | one message appended at the end of `messages`, `{"role":"system","content":[],"output_config":{"effort":…}}`, and `mid-conversation-output-config-2026-07-01` appended after your `anthropic-beta` value | your `anthropic-beta` value is kept verbatim in front; nothing earlier in `messages` moves |
 | Sibling model (`BVSALA_GATEWAY_MODELO_HERMANO=1`) | `/v1/messages` and `/v1/messages/count_tokens` for `claude-fable-5`, except with a forced `tool_choice` or the 1M-context beta | `model` becomes `claude-fable-5-1` | headers are untouched |
 | Context-editing dials (`BVSALA_GATEWAY_DIALES_ELISION=1`; measured as a net loss, off) | `/v1/messages` | your `clear_tool_uses_20250919` edit in `context_management` is replaced by ours | your other edits are kept, `clear_thinking_20251015` first; your `anthropic-beta` value is kept verbatim, with `context-management-2025-06-27` appended if it was not there |
 | Usage in Chat Completions streams (`BVSALA_GATEWAY_USAGE_INJECT=1`, off) | streaming `…/chat/completions` requests without `stream_options` of their own | `"stream_options":{"include_usage":true},` inserted as text right after the opening `{` | the rest of the body, byte for byte (nothing is re-serialized); headers are untouched; a 400 or 422 gets your original request once more |

package/docs/terminales/aider.md

@@ -0,0 +1,74 @@
+# Aider a través del gateway
+
+**Fuente:** `docs/investigacion/2026-09-27/agentes-de-codigo.md`: código de
+`Aider-AI/aider` (rama `main` a 2026-05-22; la última release publicada es la
+v0.86, de agosto de 2025) y de `BerriAI/litellm` 1.82.3, la versión que fija
+`main` de aider. Aider llama a los modelos a través de litellm, así que las
+variables que mandan son las de litellm [V].
+
+## Qué necesitas
+
+- `aider` en el PATH y tu **API key** (`ANTHROPIC_API_KEY` o `OPENAI_API_KEY`).
+- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (ver [README](README.md)).
+
+## Envoltorio: `bvsala aider [args…]`
+
+```bash
+bvsala aider                                            # modelos de Anthropic
+BVSALA_GATEWAY_UPSTREAM=openai bvsala aider --model gpt-…   # modelos de OpenAI
+```
+
+Un gateway habla con un solo proveedor, así que el envoltorio enruta uno:
+
+- **Anthropic (por defecto).** Con `ANTHROPIC_API_KEY` presente, aider elige
+  Sonnet por defecto [V]. El envoltorio exporta `ANTHROPIC_API_BASE`, que litellm
+  lee **antes** que `ANTHROPIC_BASE_URL`, y litellm añade `/v1/messages` si la
+  URL no termina así: **sin `/v1`** [V].
+- **OpenAI**, con `BVSALA_GATEWAY_UPSTREAM=openai`: exporta `OPENAI_BASE_URL` y
+  `OPENAI_API_BASE` (litellm las lee en ese orden), **con `/v1`** [V].
+
+Lo que no es del proveedor enrutado va directo y no se mide (por ejemplo, un
+modelo débil de otro proveedor). Al salir, el envoltorio imprime cuántas
+peticiones midió y cuáles reenvió sin medir, y por qué.
+
+### La trampa de OpenAI: el usage en stream
+
+litellm solo añade `stream_options: {"include_usage": true}` cuando habla con
+`api.openai.com` **directamente** (`get_stream_options`: sin `api_base`, o con
+host `api.openai.com`) [V]. Detrás del gateway el host es `127.0.0.1`, así que
+los streams de OpenAI **no piden su contador** y se reenvían sin medir. Dos
+salidas:
+
+```bash
+BVSALA_GATEWAY_UPSTREAM=openai BVSALA_GATEWAY_USAGE_INJECT=1 bvsala aider --model gpt-…
+BVSALA_GATEWAY_UPSTREAM=openai bvsala aider --model gpt-… --no-stream
+```
+
+La primera añade la opción en el gateway (el último chunk llega con `choices`
+vacío, lo mismo que aider recibe cuando habla con OpenAI directo); la segunda
+pide respuestas enteras, que traen el `usage` en el JSON. Anthropic no tiene
+esta trampa: su stream siempre trae el contador.
+
+## Manual
+
+```bash
+bvsala gateway                                           # 8402, Anthropic
+ANTHROPIC_API_BASE=http://127.0.0.1:8402 aider           # SIN /v1
+
+bvsala gateway --upstream openai --port 8403
+OPENAI_API_BASE=http://127.0.0.1:8403/v1 aider --model gpt-…   # CON /v1
+```
+
+## La trampa típica
+
+- `--openai-api-base` en la línea de comandos o `openai-api-base:` en
+  `.aider.conf.yml` pisan la variable (aider la reescribe al arrancar) [V].
+- Un `api_base` en `extra_params` de `.aider.model.settings.yml` manda sobre
+  todo: esa petición no pasa por el gateway.
+
+## Qué ya mide aider
+
+Aider enseña tokens y coste por mensaje, con los precios de litellm; cuando la
+respuesta no trae `usage`, cuenta los tokens con su tokenizador local, que es
+una estimación [V]. El gateway añade el contador del proveedor en cada
+petición, el aviso de lo que no pudo medir y el panel del equipo.

package/docs/terminales/continue.md

@@ -0,0 +1,47 @@
+# Continue (CLI `cn` y extensiones) a través del gateway
+
+**Fuente:** `docs/investigacion/2026-09-27/agentes-de-codigo.md`: código de
+`continuedev/continue` (extensión v2.1.0, junio de 2026) y su doc de `cn`. Continue
+se configura por **archivo** (`~/.continue/config.yaml`, el mismo para la CLI y
+las extensiones de VS Code y JetBrains) [V]: no hay envoltorio, `bvsala doctor`
+imprime el bloque.
+
+## La forma del URL [V]
+
+El proveedor `anthropic` de Continue tiene `apiBase` por defecto
+`https://api.anthropic.com/v1/`, añade la barra final si falta y resuelve
+`new URL("messages", apiBase)`. Por eso: **con `/v1`**; la barra final la pone él.
+
+## `~/.continue/config.yaml`
+
+```yaml
+models:
+  - name: Claude via bvsala
+    provider: anthropic
+    model: <Anthropic model id>
+    apiKey: <your Anthropic API key>
+    apiBase: http://127.0.0.1:8402/v1
+```
+
+Y `bvsala gateway` corriendo aparte. En la CLI también vale `cn --config <fichero>`
+con un fichero que lleve ese `apiBase`.
+
+## Comprobar
+
+```
+[gateway] POST /v1/messages  · <modelo> · $0.001234 (in 120, cache↑0 cache↓0, out 8)
+```
+
+- `[gateway] POST /messages → 404` → falta el `/v1`.
+- nada en el log → el modelo activo no es el de este bloque.
+
+## La trampa típica
+
+- **Gateway apagado con la config escrita**: Continue falla con ese modelo hasta
+  que arranques `bvsala gateway`.
+- El autocompletado usa su propio modelo (`roles: [autocomplete]`): si no apunta
+  al gateway, no se mide.
+
+## Nota BYOK
+
+**API key exclusivamente.** Nunca el OAuth de una suscripción Claude Pro/Max.

package/docs/terminales/copilot.md

@@ -0,0 +1,114 @@
+# GitHub Copilot (CLI y VS Code) a través del gateway — solo con tu propia clave
+
+**Fuente:** `docs/investigacion/2026-09-27/agentes-de-codigo.md`: la doc oficial
+de GitHub «Using your own LLM models in GitHub Copilot CLI» (fuente en
+`github/docs`, consultada el 2026-09-27) y la de VS Code «AI language models in
+VS Code» (fechada el 16-09-2026).
+
+**Lo primero:** Copilot solo pasa por un base URL cuando usas **tu propia clave
+de proveedor (BYOK)**. Los modelos alojados por GitHub van a GitHub y no se
+pueden medir aquí; su gasto lo enseña `/usage` (créditos de IA de GitHub y
+tokens por modelo). Con BYOK, la CLI funciona **sin cuenta de GitHub** [V].
+
+## Copilot CLI
+
+### Qué necesitas
+
+- `copilot` en el PATH (en Windows, el instalador nativo: el shim `.cmd` de npm no
+  se puede lanzar con argumentos de forma segura y `bvsala` se niega con una guía).
+- BYOK configurado y funcionando **directo** [V]:
+
+  ```bash
+  export COPILOT_PROVIDER_TYPE=anthropic
+  export COPILOT_PROVIDER_BASE_URL=https://api.anthropic.com
+  export COPILOT_PROVIDER_API_KEY=…          # tu clave de Anthropic
+  export COPILOT_MODEL=<modelo de Claude>
+  ```
+
+  (Con OpenAI, el tipo por defecto, el base URL es `https://api.openai.com/v1`: ver «El tipo `openai`» abajo.)
+- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (ver [README](README.md)).
+
+### Envoltorio: `bvsala copilot [args…]`
+
+```bash
+bvsala copilot
+```
+
+Con `COPILOT_PROVIDER_TYPE=anthropic`, arranca el gateway contra
+`api.anthropic.com` y lanza `copilot` con `COPILOT_PROVIDER_BASE_URL` apuntando
+al gateway, **con la misma ruta que ya tenías**. Tu modelo y tu clave no se
+tocan. Al salir imprime cuántas peticiones midió y cuáles reenvió sin medir, y
+por qué.
+
+Se niega, antes de arrancar nada y con el motivo, cuando:
+
+- no hay `COPILOT_PROVIDER_BASE_URL` (estás en los modelos de GitHub: nada que medir);
+- el tipo es `openai` (el de por defecto): todavía no, ver abajo;
+- el tipo es `azure` u otro, o el base URL no es `https://api.anthropic.com`: el
+  gateway solo tarifa la API del propio proveedor a su precio de lista, y Azure,
+  un modelo local o un revendedor facturan distinto (o nada).
+
+### Manual (tipo `anthropic`)
+
+```bash
+bvsala gateway                                                   # Anthropic, 8402
+COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:8402 copilot          # SIN /v1
+```
+
+Cada `POST /v1/messages` se mide con su contador (Messages siempre lo trae).
+
+### El tipo `openai`: sin envoltorio hasta validarlo en mano
+
+La doc oficial lo describe como «any other OpenAI Chat Completions API‑compatible
+endpoint» [V], pero el changelog de la CLI dice que desde la 1.0.64 también
+habla la **Responses API por WebSocket** con BYOK («Add websocket responses
+support for BYOK OpenAI-compatible providers») [V]. El gateway responde **426**
+a todo intento de WebSocket (así cae Codex a HTTP), y **no sabemos** si la CLI
+de Copilot hace lo mismo: la CLI no es de código abierto. Un envoltorio que
+puede romper la sesión no se publica sin probarlo. A mano, y mirando el log:
+
+```bash
+bvsala gateway --upstream openai --port 8403
+COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:8403/v1 copilot       # CON /v1
+```
+
+- `… → 426 (WebSocket not supported …)` seguido de líneas `POST /v1/responses`
+  o `POST /v1/chat/completions` con `$` → la CLI cayó a HTTP y se mide.
+- Solo el 426 y la sesión falla → no funciona detrás del gateway; vuelve a la
+  URL directa.
+- `not metered: the request did not ask for usage` → relanza el gateway con
+  `BVSALA_GATEWAY_USAGE_INJECT=1`.
+
+### Lo que no pasa por aquí
+
+Lo que va a GitHub con BYOK igualmente (`/delegate`, búsqueda de código,
+telemetría sin `COPILOT_OFFLINE=true`) no es inferencia de tu proveedor [V].
+
+## Copilot en VS Code (BYOK, «Custom Endpoint»)
+
+No se detecta ni se envuelve (es una extensión): la receta la imprime `bvsala doctor`.
+
+1. **Manage Language Models** → **Add Models** → **Custom Endpoint**.
+2. Tipo de API: **Messages** (Anthropic). VS Code abre `chatLanguageModels.json`.
+3. En el modelo, la **ruta completa** en `url`:
+
+   ```json
+   "url": "http://127.0.0.1:8402/v1/messages"
+   ```
+
+   VS Code usa tal cual una URL que ya lleva `/messages`, `/chat/completions` o
+   `/responses`; si no, añade la ruta y, si falta, `/v1` [V]. Con la ruta
+   completa no hay nada que adivinar.
+4. `bvsala gateway` corriendo aparte.
+
+El BYOK de VS Code cubre el chat y las tareas auxiliares (títulos, mensajes de
+commit) [V]; las sugerencias en línea y los embeddings siguen en GitHub y no se
+miden aquí. Las tareas auxiliares usan `chat.utilityModel` y
+`chat.utilitySmallModel`, no el modelo del chat: si quieres medirlas, apúntalas
+también a un modelo del Custom Endpoint.
+
+## Nota BYOK
+
+Tu clave, tu factura: es exactamente el caso que el gateway mide. Nunca enrutes
+por aquí el OAuth de una suscripción Claude Pro/Max: Anthropic lo prohíbe en
+harnesses de terceros.

package/docs/terminales/kilo.md

@@ -1,50 +1,73 @@
 # Kilo Code a través del gateway
 
-**Fuente:** `docs/PASARELA-S3-TERMINALES.md` §3. Kilo Code configura por **UI**
-(proveedor custom con Provider API «Anthropic Messages»; la config queda en
-`kilo.json`, detectable) [V]. **La forma del base URL es inferida [I] por
-linaje Cline: probar con `/v1` primero y validar en mano contra el log del
-gateway.** No hay validación hecha; esta guía lo dice tal cual.
+**Fuente:** `docs/investigacion/2026-09-27/agentes-de-codigo.md` (código de
+`Kilo-Org/kilocode` v7.8.1, 2026-09-25). Desde la serie 7, Kilo es un fork de
+opencode (`.opencode-version`: v1.18.26): la CLI (`kilo`), la extensión de VS
+Code y la de JetBrains leen la misma configuración, `kilo.json`, y el proveedor
+`anthropic` se apunta con `provider.anthropic.options.baseURL`. Su capa de
+protocolo añade `/messages` a `https://api.anthropic.com/v1`: **con `/v1`** [V].
+Esto sustituye a la receta anterior (proveedor custom por UI, forma inferida).
 
 ## Qué necesitas
 
-- Kilo Code instalado en VS Code.
-- Tu **API key** de Anthropic.
-- `bvsala gateway` corriendo en `http://127.0.0.1:8402` (necesita `BIVELIO_SERVICE_KEY` y una licencia BiVelio activa; ver [README](README.md)).
+- Kilo (CLI `kilo`, o la extensión) con el proveedor **`anthropic`** y tu **API key** de Anthropic.
+- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
 
-## Pasos en la UI
+**Lo que no pasa por aquí:** el proveedor por defecto de Kilo es su propia
+pasarela (Kilo Gateway, modelos alojados por Kilo con su cuenta). Ese tráfico va
+a Kilo, no a un base URL tuyo, y no se mide. Tampoco los demás proveedores.
 
-1. Ajustes de Kilo Code → añade un **proveedor custom**.
-2. **Provider API**: «Anthropic Messages».
-3. Pega tu **API key** de Anthropic.
-4. **Base URL** — prueba primero:
+## Envoltorio (CLI): `bvsala kilo [args…]`
 
-   ```
-   http://127.0.0.1:8402/v1
-   ```
+```bash
+export BIVELIO_SERVICE_KEY=bvk_…
+bvsala kilo
+```
 
-   **Sin barra final.**
-5. Elige el modelo y guarda.
+Kilo acepta la configuración entera en `KILO_CONFIG_CONTENT` y la fusiona por
+encima de la global y de la de proyecto [V]. El envoltorio arranca un gateway
+efímero y lanza `kilo` con esa variable apuntando el proveedor `anthropic` a
+`http://127.0.0.1:<puerto>/v1`. **No escribe nada en disco.** Si ya exportas tu
+propio `KILO_CONFIG_CONTENT`, lo fusiona y solo cambia ese `baseURL`; si no es un
+objeto JSON, se niega antes de arrancar sin repetir su valor. Al salir imprime
+cuántas peticiones midió y cuáles reenvió sin medir, y por qué.
 
-## Validar en mano (obligatorio antes de fiarte)
+## Manual (CLI y extensiones): `~/.config/kilo/kilo.json`
 
-Manda un mensaje trivial y mira la ventana del gateway:
+```json
+{
+  "provider": {
+    "anthropic": {
+      "options": {
+        "baseURL": "http://127.0.0.1:8402/v1"
+      }
+    }
+  }
+}
+```
 
-- `[gateway] POST /v1/messages  · <modelo> · $…` → **con `/v1`** es la forma
-  buena; confírmalo en S3 (pasar el [I] a [V]).
-- `[gateway] POST /v1/v1/messages → 404` → Kilo ya añade `/v1`: quita el `/v1`
-  del base URL (`http://127.0.0.1:8402`) y repite.
-- `[gateway] POST /messages → 404` → falta el `/v1`; vuelve a ponerlo.
-- nada en el log → el proveedor custom no es el activo.
+**Con `/v1`, sin barra final.** Precedencia (de menos a más): global
+(`~/.config/kilo/kilo.json`), `KILO_CONFIG`, proyecto (`./kilo.json`,
+`.kilo/kilo.json`), `KILO_CONFIG_CONTENT`, gestionada [V]. Arranca el gateway
+aparte con `bvsala gateway`.
+
+## Comprobar
+
+```
+[gateway] POST /v1/messages  · <modelo> · $0.001234 (in 120, cache↑0 cache↓0, out 8)
+```
+
+- `[gateway] POST /messages → 404` → falta el `/v1`.
+- `[gateway] POST /v1/v1/messages → 404` → sobra un `/v1`.
+- nada en el log → el modelo activo no es del proveedor `anthropic` (¿Kilo Gateway?).
 
 ## La trampa típica
 
-- **Adivinar el `/v1`**: de ahí el paso de validación. Un URL mal formado falla
-  en silencio (404 del upstream, nada medido, error genérico en la UI).
-- **Gateway apagado**: `kilo.json` recuerda el base URL; sin `bvsala gateway`
-  corriendo, Kilo fallará hasta que lo arranques o cambies de proveedor.
+- **Gateway apagado con la config escrita**: `kilo.json` recuerda el base URL;
+  sin `bvsala gateway` corriendo, Kilo falla hasta que lo arranques o quites la
+  clave. El envoltorio no tiene esta trampa.
 
 ## Nota BYOK
 
 **API key exclusivamente.** Anthropic prohíbe usar el OAuth de Claude Pro/Max en
-harnesses de terceros; esta receta es la del proveedor custom con API key.
+harnesses de terceros; esta receta es la del proveedor `anthropic` con API key.

package/docs/terminales/no-soportados.md

@@ -0,0 +1,41 @@
+# Lo que el gateway no mide hoy, y por qué
+
+**Fuente:** `docs/investigacion/2026-09-27/agentes-de-codigo.md`. Decir que no es
+parte de la receta: un terminal apuntado al gateway que no se puede medir sería
+pagar una licencia por un proxy vacío.
+
+## Gemini CLI — no se mide todavía
+
+Gemini CLI acepta un base URL propio: `GOOGLE_GEMINI_BASE_URL` (y
+`GOOGLE_VERTEX_BASE_URL` con Vertex), en HTTPS salvo que apunte a `localhost` o
+`127.0.0.1` [V: `docs/reference/configuration.md` de `google-gemini/gemini-cli`,
+2026-09-27]. El problema no es enrutarlo: es que habla la **API de Gemini**
+(`…/models/<modelo>:streamGenerateContent`, contador en `usageMetadata`), y el
+gateway solo sabe leer el contador de Anthropic Messages y de OpenAI Chat
+Completions y Responses. Cada petición se reenviaría con la línea
+`not metered: no usage dialect for this route`, sin coste.
+
+Hasta que el gateway lea ese dialecto, el contador de Gemini CLI es su propio
+`/stats model` (tokens por modelo y cuota) [V]. Qué haría falta para medirlo, y
+por qué no se ha hecho hoy (los precios de contexto largo de los modelos Pro),
+está en el informe.
+
+## Cursor — no se puede
+
+Cursor manda **todas** las peticiones, también las de tu propia clave, a través
+de sus servidores: «all requests are routed through Cursor's servers for final
+prompt building» [V: cursor.com/docs/settings/api-keys, 2026-09-27]. Un gateway
+en `127.0.0.1` es inalcanzable desde ahí, y exponerlo a Internet no es una
+opción (escucha solo en loopback a propósito). Las claves propias, además, solo
+cubren los modelos de chat; Tab sigue con los modelos de Cursor [V]. El contador
+de Cursor es su panel de uso.
+
+## Copilot con modelos de GitHub — no pasa por un base URL
+
+Sin BYOK, Copilot (CLI y VS Code) usa los modelos alojados por GitHub, que van a
+GitHub y no a un base URL tuyo. Con BYOK sí se mide: ver [copilot.md](copilot.md).
+
+## Kilo Gateway — no pasa por un base URL tuyo
+
+El proveedor por defecto de Kilo son sus modelos alojados; ese tráfico va a Kilo.
+Con el proveedor `anthropic` y tu clave sí se mide: ver [kilo.md](kilo.md).

package/docs/terminales/opencode.md

@@ -1,15 +1,40 @@
 # opencode a través del gateway
 
-**Fuente:** `docs/PASARELA-S3-TERMINALES.md` §3 [V]. opencode enruta por
-**archivo de configuración**, no por variable de entorno, y su capa
-`packages/llm` añade `/messages` al `baseURL`: por eso aquí el URL lleva `/v1`.
+**Fuente:** `docs/PASARELA-S3-TERMINALES.md` §3 [V] y
+`docs/investigacion/2026-09-27/agentes-de-codigo.md` (código de
+`anomalyco/opencode` v1.18.32, 2026-09-27). opencode enruta por **configuración**,
+y su capa de protocolo añade `/messages` a `https://api.anthropic.com/v1` por
+defecto: por eso aquí el URL lleva `/v1` [V].
 
 ## Qué necesitas
 
 - `opencode` instalado, proveedor `anthropic` con tu **API key** de Anthropic.
 - `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
 
-## Config de usuario: `~/.config/opencode/opencode.json`
+## Envoltorio: `bvsala opencode [args…]`
+
+```bash
+export BIVELIO_SERVICE_KEY=bvk_…
+bvsala opencode
+```
+
+opencode acepta la configuración entera en la variable `OPENCODE_CONFIG_CONTENT`
+y la fusiona **por encima** de la global y de la de proyecto (`config.ts`: se
+carga después de `opencode.json` global, del de proyecto y de `.opencode/`; solo
+la config de cuenta remota y la gestionada por la empresa van después) [V]. El
+envoltorio arranca un gateway efímero y lanza `opencode` con esa variable
+apuntando `provider.anthropic.options.baseURL` a `http://127.0.0.1:<puerto>/v1`.
+**No escribe nada en disco** y todo muere al salir.
+
+- Si ya exportas tu propio `OPENCODE_CONFIG_CONTENT`, el envoltorio lo
+  **fusiona**: solo cambia `provider.anthropic.options.baseURL`; tu clave, tus
+  modelos y lo demás siguen igual. Si no es un objeto JSON (por ejemplo, JSONC
+  con comentarios), se niega antes de arrancar y no repite su valor.
+- Solo pasa por el gateway el proveedor `anthropic`. Los demás proveedores
+  (OpenAI, OpenCode Zen, OpenRouter…) van directos y no se miden.
+- Al salir imprime cuántas peticiones midió y cuáles reenvió sin medir, y por qué.
+
+## Manual: `~/.config/opencode/opencode.json`
 
 ```json
 {
@@ -27,11 +52,6 @@
 [V]. El `opencode.json` de proyecto pisa al global: si tienes uno en el repo,
 ahí es donde manda.
 
-No hay envoltorio `bvsala opencode`: el enrutado es config de usuario. El
-`bvsala doctor --write opencode` previsto en S3 hará un merge JSON conservador
-de este bloque (con copia `.bak`) en tu config de usuario, nunca en archivos
-del repo.
-
 ### Alternativa [V]: `baseURL` desde variable de entorno
 
 ```json
@@ -56,10 +76,12 @@ opencode
 
 - **Sin `/v1`** → opencode pide `http://127.0.0.1:8402/messages` → `[gateway] POST /messages → 404`.
 - **Barra final** (`…/v1/`) → no.
-- **Config de proyecto** con otro `baseURL` pisando al global sin que lo sepas.
+- **Config de proyecto** con otro `baseURL` pisando al global sin que lo sepas
+  (con el envoltorio no pasa: su variable manda sobre los dos).
 - **Gateway apagado con la config escrita**: opencode falla hasta que arranques
   `bvsala gateway` de nuevo. La config es persistente; el gateway, no. (La
-  variante `{env:…}` sin exportar la variable también falla, por vacío.)
+  variante `{env:…}` sin exportar la variable también falla, por vacío.) El
+  envoltorio no tiene esta trampa.
 
 ## Nota BYOK