@bivelio/savings-layer 0.4.24 → 0.4.26

package/docs/terminales/README.md

@@ -8,15 +8,19 @@ terminal). Cada afirmación va marcada **[V]** (verificada en fuente) o **[I]**
 ## Qué es esto
 
 `bvsala gateway` es un proxy local medidor: escucha en `127.0.0.1`, reenvía
-cada petición **byte a byte** al proveedor (`https://api.anthropic.com` por
-defecto) y, una vez servida la respuesta, lee el `usage` del stream y lo
-convierte en coste. Tus prompts jamás salen de tu máquina hacia BiVelio — solo
-cuentas y coste. Es fail-closed como el SDK: arranca solo con tu clave de
-servicio (`BIVELIO_SERVICE_KEY`) y una licencia BiVelio activa, que recoge con
-esa clave y cuya firma verifica en tu máquina. Una vez arrancado, jamás corta
-una petición en curso: si la licencia caduca o se revoca, solo las peticiones
-NUEVAS reciben un HTTP 402 hasta renovarla. La medición es best-effort: con la
-ingesta caída, reenvía y avisa.
+cada petición al proveedor (`https://api.anthropic.com` por defecto) —**byte a
+byte**, salvo las palancas que se explican abajo (con licencia PRO, la de tarifa
+va encendida por defecto)— y, una vez servida la respuesta, lee el `usage` del
+stream y lo convierte en coste. Ni tus prompts, ni las respuestas, ni la clave de
+tu proveedor salen de tu máquina hacia BiVelio: solo viaja el uso de cada
+petición —cuentas de tokens, coste, el id del modelo, un id de petición y los ids
+opacos de asiento y de sesión—, y la lista exacta de campos está en la
+LICENSE §5. Es fail-closed como el SDK: arranca solo con tu clave de servicio
+(`BIVELIO_SERVICE_KEY`) y una licencia BiVelio activa, que recoge con esa clave y
+cuya firma verifica en tu máquina. Una vez arrancado, jamás corta una petición en
+curso: si la licencia caduca o se revoca, solo las peticiones NUEVAS reciben un
+HTTP 402 hasta renovarla. La medición es best-effort: con la ingesta caída,
+reenvía y avisa.
 
 Mide cada petición. Con licencia PRO aplica por defecto **una sola palanca**:
 rebaja el TTL de escritura de caché mientras la sesión sigue caliente — cambia la
@@ -38,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**
@@ -50,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
@@ -188,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.
@@ -205,3 +234,130 @@ no se promociona ni se documenta como receta.
 di eso, nunca «aprobado por Anthropic». El contrato del gateway es una lista
 abierta de cabeceras y campos que crece con cada release del terminal; el
 passthrough byte a byte es lo que lo mantiene vivo sin tocar nada.
+
+## What the gateway guarantees: it forwards what your client sends
+
+A proxy in front of your provider can raise your bill without breaking anything
+you can see: a lost cache marker, a dropped beta header, a block it does not
+recognise. This gateway is built not to do that, and a test suite checks it
+against a fake upstream on 127.0.0.1: `test/gateway-no-empeora.test.ts`, which
+runs in our CI on every pull request and every push to `main`. The source
+repository is not public, so this section lists exactly what the suite checks.
+
+**With no lever armed, your provider receives what your client sent, byte for
+byte:**
+
+- **The request body**, including `tool_reference` blocks (from the provider's
+  tool search and from a client-side search tool such as Claude Code's), tools
+  with `defer_loading`, `cache_control` in every place the API reads it (top
+  level, `system`, `tools`, and text, image, document, `tool_use` and
+  `tool_result` blocks, including blocks nested inside a `tool_result` or inside
+  a document's `source.content`), each with its `ttl: "1h"`, the advisor tool
+  with its `advisor_tool_result` blocks, thinking signatures, and fields the
+  gateway does not know. Not a JSON equivalent: the same bytes.
+- **The path and query string** (`/v1/messages?beta=true`).
+- **Every request header**, including every `anthropic-beta` value (the 1-hour
+  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`. 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. 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
+model, per-turn effort, the context-editing dials and usage injection are off by
+default). The suite checks each of these with the request exactly as Claude
+Code sends it (compact JSON, which every armed lever would rewrite) and with a
+hand-formatted one, and next to each it runs the same setup with the lever armed
+and checks that the request does change, so a lever that stopped switching off
+would fail it.
+
+**With a lever armed, the only change is the one it declares:**
+
+| 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` 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 |
+
+A lever that changes the body parses it and writes it back: your provider reads
+the same JSON values, although whitespace and the way strings are escaped may
+differ. When writing it back would change anything else (a number JavaScript
+prints differently, such as `1.0`, `1e5`, `-0` or an integer beyond 2^53; an
+object key that looks like an array index, which JavaScript moves to the front;
+a key repeated in the same object; invalid UTF-8; a compressed body), no lever
+is applied and the request travels byte for byte. If the provider answers 400 to
+a request a lever changed, the gateway sends your original request once more,
+unchanged, and meters that one.
+
+**Degraded traffic.** The gateway also watches, with the provider's own usage
+counters, for requests that come out worse than your client asked for:
+
+| Log line: `[gateway] degraded traffic (session …) · …` | What it means |
+|---|---|
+| `prompt caching: … no cache read and no cache write` | the request marked `cache_control` at its end (top level or in the last message), the provider counted at least 4,096 input tokens (the largest minimum cacheable prompt in [Anthropic's prompt caching documentation](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), checked on 2026-09-27) and reported neither a cache read nor a cache write |
+| `cache TTL: … wrote the cache at the 5-minute TTL only` | every `cache_control` asked for `ttl: "1h"`, the TTL lever did not touch the request, and the provider wrote only 5-minute entries |
+| `tool search: … tool search is off` | Claude Code traffic (a `x-claude-code-session-id` header or a `claude-cli/` user agent) sent at least 40 full tool definitions, none with `defer_loading` and no `tool_reference`. Claude Code turns tool search off by default behind any proxy, this gateway included: `bvsala claude` turns it back on in a new window, or export `ENABLE_TOOL_SEARCH=true` |
+
+Each kind is logged once per session (Claude Code's session id; once per gateway
+process for clients that send none) and every case is counted. `bvsala` prints
+the totals when it exits, because the per-request log is silent inside `bvsala
+claude|codex|goose|qwen` (unless `BVSALA_GATEWAY_LOG=1`). None of this is sent to BiVelio: the usage record has
+no field for it (LICENSE §5), so it stays on your machine.
+
+**Limits.**
+
+- The guarantee covers what the gateway sends. It cannot make the provider
+  cache: the watcher reports, it does not fix.
+- The cache TTL lever changes the price of a cache write, never the content the
+  model reads, and it is a trade: if a 5-minute entry expires before the next
+  turn starts, that turn pays for a cache write that a 1-hour entry would have
+  saved. The lever only acts where a large part of the prompt is being written
+  anyway (session start, compaction), and `BVSALA_GATEWAY_ELISION=0` turns it
+  off.
+- On a request that declares server tools (web search, web fetch, code
+  execution, tool search, the advisor, MCP servers; the gateway counts any typed
+  tool other than a client tool such as bash or the text editor), the cache TTL
+  lever still applies but its saving is recorded as zero. When Claude uses a
+  server tool, the provider caches its result at the 5-minute TTL on its own,
+  whatever TTL your markers ask for, and reports that write in the same
+  `ephemeral_5m_input_tokens` counter
+  ([Anthropic's documentation](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-use-with-prompt-caching#server-tool-results-are-cached-automatically),
+  checked on 2026-09-27), so the invoice cannot tell which part the lever wrote.
+- The two cache checks need the provider's usage: a request that is not metered
+  is not checked. The prompt-caching check uses the largest documented minimum
+  for every model, so a future model with a larger minimum would raise false
+  alarms until the threshold moves.
+- For the same reason, the TTL check skips requests that declare server tools.
+- The tool-search check only looks at Claude Code traffic: another client with
+  many tools may never have used tool search, and that is not degraded traffic.
+- Header names arrive in lower case (HTTP header names are case-insensitive),
+  and a header your client sends twice arrives once, with both values joined by
+  a comma, in order.

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/claude-code.md

@@ -117,8 +117,13 @@ con cada release de Claude Code; BV-SALA repite el smoke test de `bvsala claude`
 contra cada versión nueva.
 
 Las cabeceras `x-claude-code-session-id` / `agent-id` / `parent-agent-id`
-llegan en el tráfico real y hoy se reenvían sin consumirlas: el coste por sesión
-y por subagente está previsto en S3 §1.3, todavía no en el panel.
+llegan en el tráfico real y se reenvían al proveedor sin tocarlas. Además, el
+gateway LEE las dos primeras y, si tienen forma de identificador, adjunta su
+valor (`sessionId`, `agentId`) al registro de uso que manda a BiVelio: es lo que
+reparte el coste por sesión y por subagente en el panel. Son los ids que Claude
+Code ya pone en sus propias peticiones, no una persona ni un contenido;
+`parent-agent-id` no se lee. La lista completa de lo que viaja está en la
+LICENSE §5.
 
 ## Nota BYOK y wording
 

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).