@bivelio/savings-layer 0.4.22 → 0.4.25

package/docs/terminales/README.md

@@ -8,10 +8,18 @@ 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. Nunca corta el tráfico: sin clave o con la ingesta caída,
+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**:
@@ -21,6 +29,11 @@ por turno) van apagadas hasta que las enciendes. Y mide **todo el tráfico de in
 que el terminal enruta por el base URL — no «todo el tráfico»: cada guía dice
 lo que su terminal manda por fuera.
 
+En suscripción (login de claude.ai en Claude Code, cuenta ChatGPT en Codex) no
+hay factura por tokens: ese tráfico se mide a precio de lista equivalente y
+nunca se le acredita ahorro ni comisión; la licencia por asiento hace falta
+igual.
+
 ## Índice
 
 | Guía | Base URL exacto | `/v1` | Enrutado [V] | Envoltorio | Estado |
@@ -34,6 +47,7 @@ lo que su terminal manda por fuera.
 | [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 |
+| [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**
 (un 3xx en el base URL es fallo por diseño del cliente, y el gateway lo reenvía
@@ -52,25 +66,43 @@ receta manual de cada guía hace exactamente lo mismo. Para el resto,
 
 ```bash
 npm i -g @bivelio/savings-layer      # trae el binario `bvsala`
-export BIVELIO_SERVICE_KEY=bvk_…     # clave de servicio, desde tu panel. Sin ella: reenvía, NO mide
+export BIVELIO_SERVICE_KEY=bvk_…     # clave de servicio, desde tu panel. Obligatoria: sin ella el gateway no arranca
 bvsala gateway                        # escucha en http://127.0.0.1:8402
-bvsala gateway --puerto 8500          # otro puerto si el 8402 está ocupado
+bvsala gateway --port 8500            # otro puerto si el 8402 está ocupado
 ```
 
-Al arrancar imprime dos líneas; la segunda te dice si estás midiendo:
+Al arrancar imprime, entre otras, estas líneas:
 
 ```
-[bvsala gateway] v0.4.4 escuchando en http://127.0.0.1:8402
-[bvsala gateway] medición: ACTIVA (clave de servicio presente)
+[bvsala gateway] v0.4.x listening on http://127.0.0.1:8402 → https://api.anthropic.com
+[bvsala gateway] license: PRO, active until 2026-10-24 (+14 days grace), collected with your service key and verified on this machine
+[bvsala gateway] metering: ON (service key present)
 ```
 
-`medición: APAGADA (falta BIVELIO_SERVICE_KEY)` = el terminal funciona igual,
-pero nada llega a tu panel.
+Si no arranca (sale con código 1), el mensaje dice exactamente qué falta:
+
+| Mensaje | Qué pasa | Arreglo |
+|---|---|---|
+| `BIVELIO_SERVICE_KEY is not set` | falta la clave de servicio | créala en el panel (Instalar, paso 2), expórtala y relanza |
+| `BIVELIO_SERVICE_KEY is not recognised` | clave borrada, rotada o copiada a medias | crea otra |
+| `your organization has no active BiVelio license` | no hay suscripción | suscríbete en Cuenta y relanza |
+| `your BiVelio license expired on …` | licencia caducada y sin gracia | renueva en Cuenta |
+| `could not collect your license from savings.bivelio.com` | sin acceso a savings.bivelio.com | revisa la conexión; como respaldo, `BIVELIO_LICENSE_KEY` (se verifica sin red y se sustituye a mano cada período) |
+| un HTTP 402 en el terminal a mitad de sesión | la licencia caducó o se revocó con la sesión abierta | renueva; las peticiones que ya estaban en curso no se cortaron |
+
+Si lanzas `bvsala gateway` como servicio (launchd/systemd), un fallo de licencia
+queda en el log del servicio con código 1 y el terminal solo verá «connection
+refused»: mira ese log.
 
 Un gateway habla con **un** upstream (`BVSALA_GATEWAY_UPSTREAM`, por defecto
 `https://api.anthropic.com`). Los terminales del dialecto Anthropic comparten
 instancia; Codex necesita la suya contra OpenAI — `bvsala codex` la arranca
-sola con el upstream correcto según tu modo de auth (ver su guía).
+sola con el upstream correcto según tu modo de auth (ver su guía). Desde la
+próxima versión, `bvsala gateway --upstream openai|anthropic|<origen>` lo elige
+sin variable de entorno (el flag manda sobre `BVSALA_GATEWAY_UPSTREAM`). Para un
+SDK de OpenAI (Python, Node…) arranca uno con `--upstream openai` en otro puerto;
+en streaming, la petición tiene que llevar `stream_options.include_usage` o el
+gateway la reenvía sin medirla y lo dice en el log.
 
 ### 2 · Comprobar que mide: el log del gateway
 
@@ -88,13 +120,56 @@ las otras líneas:
 |---|---|---|
 | `[gateway] POST /v1/v1/messages → 404` | el base URL lleva `/v1` **de más** para ese terminal | quita el `/v1` |
 | `[gateway] POST /messages → 404` | al base URL le **falta** `/v1` (el SDK solo añade `/messages`) | añade el `/v1` |
-| `[bvsala gateway] el modelo "…" no está en el catálogo de precios; su uso se reenvía pero no se mide.` | modelo fuera de catálogo (a propósito: presente-y-mal es peor que ausente) | nada; se reenvía sin medir |
+| `[gateway] POST /v1/messages → 402 (license expired)` | la licencia caducó, se revocó o la org está bloqueada: las peticiones NUEVAS se rechazan (las que estaban en curso terminaron) | renueva en Cuenta; el terminal enseña el motivo |
 | nada de nada | el terminal no está apuntando al gateway (config no leída, env pisado por config, otro puerto) | revisa la trampa de su guía |
 
+Cada petición que el gateway reenvía **sin medir** deja su propia línea con
+`· not metered: <motivo>`, y en su lugar no se estima nada. Los motivos, tal y
+como salen hoy:
+
+| `· not metered: …` | Qué pasa | Arreglo |
+|---|---|---|
+| `no BIVELIO_SERVICE_KEY` | un gateway arrancado desde código sin clave de servicio: reenvía, no mide (el CLI `bvsala` ni arranca sin ella) | exporta `BIVELIO_SERVICE_KEY` |
+| `model "…" has no list price in the catalog` | modelo fuera del catálogo de precios, a propósito: un precio presente y equivocado es peor que ninguno (la consola lo avisa una vez por modelo) | nada; se reenvía sin medir |
+| `could not read the model from the request body (content-encoding: …)` | el cuerpo no se pudo leer: JSON ilegible o una compresión que este Node no abre (zstd, el de Codex, necesita Node ≥ 22.15) | actualiza Node |
+| `the request did not ask for usage (stream_options.include_usage)` | Chat Completions en stream sin `include_usage`: el proveedor no manda contador | añade `stream_options={"include_usage": True}` a la llamada, o arranca con `BVSALA_GATEWAY_USAGE_INJECT=1` |
+| `…; usage injection skips compressed request bodies` | la inyección está puesta, pero solo añade la opción a cuerpos sin comprimir | pídelo en la llamada |
+| `…, and the upstream rejects that option` | el upstream rechazó `stream_options` y la inyección quedó apagada para el resto del proceso | en stream no hay arreglo desde el gateway; con `stream: false` sí se mide |
+| `the stream ended without the provider's final usage event` | el stream se cortó antes de su evento final (`message_delta`, `response.completed`/`incomplete`/`failed`, el chunk de uso o `[DONE]`): sin él no hay contador | nada |
+| `the response ended as response.failed without usage` | la Responses API cerró con `response.failed` sin `usage`. Si lo trae, sí se mide | nada |
+| `the response ended as response.incomplete without usage` | la Responses API cerró con `response.incomplete` sin `usage`. Si lo trae, sí se mide: un `response.incomplete` por `max_output_tokens` o por el filtro de contenido lo factura el proveedor | nada |
+| `the response carried no usage` | respuesta JSON (`stream: false`) sin `usage` | nada |
+| `the response was too large to read its usage` | respuesta JSON de más de 5 MB: el gateway no la guarda entera para leerla | nada |
+| `the response is neither JSON nor an event stream (content-type: …)` | el upstream contestó con otro tipo de contenido en una ruta que sí sabe medir | revisa el upstream |
+| `no usage dialect for this route` | ruta sin contador que el gateway sepa leer (embeddings, imágenes, audio…): solo mide `/v1/messages`, `…/chat/completions` y `…/responses` | nada |
+
+Con `BVSALA_GATEWAY_COALESCE=1` (apagada por defecto), una petición idéntica a
+otra que sigue en vuelo no viaja: recibe la réplica y su línea lleva
+`· COALESCED (call avoided)`. Detrás va `· by reference: floor $… (cache read
+price, …)` cuando se valora con el contador de la petición que sí viajó —a
+precio de lectura de caché, sin primas y con la salida solo si el cuerpo trae
+`temperature: 0` y el modelo no razona (la misma guarda de modelo que el SDK)—,
+o `· estimated, not by reference: <motivo>` cuando no. Esa línea es la
+valoración local: el panel todavía recibe estas peticiones como `estimated`, y
+no entran en la base de la comisión, porque el gateway aún no lee los tokens de
+razonamiento que declara el proveedor y la regla `reference-v2` los exige.
+
+| `· estimated, not by reference: …` | Por qué no |
+|---|---|
+| `no-primary-record` | la petición que viajó no dejó su contador final (ni evento final del stream ni `usage` en el JSON) |
+| `subscription` | tráfico de suscripción (Claude o ChatGPT): no hay factura por token |
+| `unofficial-upstream` | el gateway no habla con `api.anthropic.com` ni `api.openai.com` (un mock, un proxy, Azure, un revendedor): el precio de lista no está en ninguna factura |
+| `layer-changed-request` | una palanca cambió lo que viajó (modelo, cuerpo, cabeceras; también la rebaja de TTL de la caché): ya no es la petición del cliente byte a byte |
+| `primary-failed` | la petición que viajó cerró con `response.failed` |
+| `client-disconnected` | el cliente de esta petición se fue antes de recibir la réplica entera |
+| `service-tier` | el `service_tier` pedido o el servido no tiene precio por token publicado (`scale`, uno nuevo) |
+| `no-cached-price` | el modelo no tiene precio de lectura de caché en su propia fila del catálogo |
+| `no-credit` | el contador no deja nada que acreditar |
+
 Claude Code manda además un `HEAD /api/hello` antes de la primera llamada: es
 la sonda de vida, no una inferencia.
 
-`bvsala doctor [--puerto N]`: sondea el PATH y la existencia de las configs de
+`bvsala doctor [--port N]`: sondea el PATH y la existencia de las configs de
 usuario (nunca lee su contenido) e imprime el bloque exacto por terminal con el
 puerto indicado. Solo imprime: no escribe ninguna configuración.
 
@@ -134,3 +209,107 @@ 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`.
+- **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.
+
+"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…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 |
+| 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/claude-code.md

@@ -12,8 +12,10 @@ construcción, con test.
   `apiKeyHelper`): es el segmento que BV-SALA mide y factura. Con login de
   claude.ai el enrutado también funciona — la doc oficial lo sanciona: el login
   sigue siendo la credencial activa y «its usage limits and billing apply» [V] —
-  pero ahí no hay factura por token que recortar.
-- `bvsala` instalado y `BIVELIO_SERVICE_KEY` exportada (ver [README](README.md)).
+  pero ahí no hay factura por token: el gateway lo mide a precio de lista
+  equivalente y nunca le acredita ahorro ni comisión (la licencia por asiento
+  hace falta igual).
+- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
 
 ## Envoltorio: `bvsala claude` (recomendado)
 
@@ -115,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/cline.md

@@ -14,7 +14,7 @@ que se usa.
 
 - Cline instalado en VS Code.
 - Tu **API key** de Anthropic.
-- `bvsala gateway` corriendo en `http://127.0.0.1:8402` (ver [README](README.md)).
+- `bvsala gateway` corriendo en `http://127.0.0.1:8402` (necesita `BIVELIO_SERVICE_KEY` y una licencia BiVelio activa; ver [README](README.md)).
 
 ## Pasos en la UI
 

package/docs/terminales/codex.md

@@ -11,9 +11,10 @@ cifras.
 
 - `codex` en el PATH.
 - Login en Codex: **API key de OpenAI** (el caso que se monetiza) o
-  suscripción ChatGPT (se enruta y se mide, pero **no se monetiza**: no hay
-  factura por tokens; ver más abajo).
-- `bvsala` instalado y `BIVELIO_SERVICE_KEY` exportada (ver [README](README.md)).
+  suscripción ChatGPT (se enruta y se mide a precio de lista equivalente, **sin
+  comisión**: no hay factura por tokens; la licencia por asiento hace falta
+  igual; ver más abajo).
+- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
 
 ## Envoltorio: `bvsala codex [args…]`
 
@@ -92,26 +93,26 @@ que el tráfico real enseñó y el gateway ya contempla:
    de Codex frente a su backend: aparece igual **sin** gateway (comprobado).
 4. **Barra final.** `…/v1/` no.
 
-## Modo suscripción ChatGPT — validado, medido, NO monetizado
+## Modo suscripción ChatGPT — validado, medido, sin comisión
 
 Validado en mano el 30-08 (prefijo `/backend-api/codex`, upstream
 `https://chatgpt.com`): 200, stream íntegro, `usage` presente en
 `response.completed` y registro `measured` en la ingesta. **Pero un suscriptor
 no paga por tokens**: la cifra que ve es el equivalente a precio de lista por
 API key, no una factura; y como la comisión de BV-SALA solo toca ahorro medido
-sobre gasto real, este tráfico **no se monetiza** — igual que el OAuth de
+sobre gasto real, este tráfico **no genera comisión** — igual que el OAuth de
 suscripción en Claude Code (`docs/PASARELA-F0.md`: «el caso que NO
 facturamos»). OpenAI ni bendice ni prohíbe el proxy de suscripción (silencio
 del staff, a diferencia de Anthropic, que lo documenta). Postura idéntica a
 Claude Code: cero persistencia de `Authorization` / `ChatGPT-Account-ID`,
 binario sin modificar, y no se promociona como modo de ahorro.
 
-**Laguna conocida:** el registro que emite el gateway para un suscriptor es hoy
-**idéntico** al de una API key (`basis: measured`, coste a precio de lista) —
-el panel no puede distinguirlos. Mientras la comisión sea 0 no hay efecto; antes
-de que S4 calcule comisión sobre ahorro medido, S2 etiquetará la auth de
-suscripción en el wire para que ese tráfico jamás entre en la base. Está en el
-plan (`docs/PLAN-PASARELA-API-KEY.md`, S3).
+**Comisión 0 por diseño (desde la versión en que el gateway exige licencia):**
+el gateway clasifica como suscripción el tráfico de `/backend-api/…` o con
+upstream chatgpt.com (y el de Claude Code con `anthropic-beta: oauth-*`) y no le
+acredita ahorro: `baseline == actual`. Laguna que queda: el registro no lleva
+etiqueta propia en el wire, así que el panel no distingue suscripción de API key
+(exige migración; fuera de este frente).
 
 ## Validaciones en mano
 

package/docs/terminales/crush.md

@@ -10,7 +10,7 @@ relativa, y eso dicta la forma del URL: **con `/v1`, sin barra final**.
 - `crush` instalado.
 - `ANTHROPIC_API_KEY` exportada (Crush retiró su OAuth de Claude en ene-2026:
   solo API key).
-- `bvsala` instalado y `BIVELIO_SERVICE_KEY` exportada (ver [README](README.md)).
+- `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/crush/crushrc`
 

package/docs/terminales/droid.md

@@ -9,7 +9,7 @@ lo dice tal cual; no hay validación hecha.
 ## Qué necesitas
 
 - `droid` instalado, en modo BYOK con tu **API key** de Anthropic.
-- `bvsala` instalado y `BIVELIO_SERVICE_KEY` exportada (ver [README](README.md)).
+- `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: `~/.factory/settings.json`
 

package/docs/terminales/goose.md

@@ -9,7 +9,7 @@ forma del URL.
 
 - `goose` en el PATH, con el proveedor Anthropic elegido.
 - `ANTHROPIC_API_KEY` exportada (Goose es solo BYOK).
-- `bvsala` instalado y `BIVELIO_SERVICE_KEY` exportada (ver [README](README.md)).
+- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
 
 ## Envoltorio: `bvsala goose`
 

package/docs/terminales/kilo.md

@@ -10,7 +10,7 @@ gateway.** No hay validación hecha; esta guía lo dice tal cual.
 
 - Kilo Code instalado en VS Code.
 - Tu **API key** de Anthropic.
-- `bvsala gateway` corriendo en `http://127.0.0.1:8402` (ver [README](README.md)).
+- `bvsala gateway` corriendo en `http://127.0.0.1:8402` (necesita `BIVELIO_SERVICE_KEY` y una licencia BiVelio activa; ver [README](README.md)).
 
 ## Pasos en la UI
 

package/docs/terminales/opencode.md

@@ -7,7 +7,7 @@
 ## Qué necesitas
 
 - `opencode` instalado, proveedor `anthropic` con tu **API key** de Anthropic.
-- `bvsala` instalado y `BIVELIO_SERVICE_KEY` exportada (ver [README](README.md)).
+- `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`
 

package/docs/terminales/qwen-code.md

@@ -10,7 +10,7 @@ catálogo a propósito (más abajo).
 - `qwen` en el PATH.
 - **Una API key de Anthropic** (`ANTHROPIC_API_KEY`), con Qwen Code configurado
   para usar el proveedor Anthropic.
-- `bvsala` instalado y `BIVELIO_SERVICE_KEY` exportada (ver [README](README.md)).
+- `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: `~/.qwen/settings.json`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivelio/savings-layer",
-  "version": "0.4.22",
+  "version": "0.4.25",
   "description": "The savings layer for your LLM bill: a library inside your code that lets through only what has to be paid for and returns a SavingsReport per call, measured with your provider's own meter and kept apart from estimates. Commercial license, paid per seat, commission only on measured savings. Your prompts never leave your infrastructure.",
   "keywords": [
     "llm",
@@ -15,6 +15,10 @@
     "email": "support@bivelio.com",
     "url": "https://savings.bivelio.com"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BiVelio/bivelio-savings-layer.git"
+  },
   "license": "SEE LICENSE IN LICENSE",
   "author": "BiVelio Inc.",
   "type": "module",
@@ -27,6 +31,26 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./ai-sdk": {
+      "types": "./dist/adapters/ai-sdk.d.ts",
+      "import": "./dist/adapters/ai-sdk.js",
+      "default": "./dist/adapters/ai-sdk.js"
+    },
+    "./mastra": {
+      "types": "./dist/adapters/mastra.d.ts",
+      "import": "./dist/adapters/mastra.js",
+      "default": "./dist/adapters/mastra.js"
+    },
+    "./langchain": {
+      "types": "./dist/adapters/langchain.d.ts",
+      "import": "./dist/adapters/langchain.js",
+      "default": "./dist/adapters/langchain.js"
+    },
+    "./anthropic-sdk": {
+      "types": "./dist/adapters/anthropic-sdk.d.ts",
+      "import": "./dist/adapters/anthropic-sdk.js",
+      "default": "./dist/adapters/anthropic-sdk.js"
+    },
     "./package.json": "./package.json"
   },
   "bin": {
@@ -59,6 +83,8 @@
     "example:basic": "BVSALA_DEV_OPEN=1 tsx examples/basic/index.ts",
     "example:handoff": "BVSALA_DEV_OPEN=1 tsx examples/multi-agent/handoff.ts",
     "example:serialization": "BVSALA_DEV_OPEN=1 tsx examples/serialization/format-selector.ts",
+    "example:otel": "BVSALA_DEV_OPEN=1 tsx examples/exporters/otel.ts",
+    "example:focus": "BVSALA_DEV_OPEN=1 tsx examples/exporters/focus.ts",
     "example:licensed": "tsx examples/licensing/licensed.ts",
     "license:demo": "tsx examples/licensing/demo.ts",
     "example:revocation": "tsx examples/licensing/revocation.ts",
@@ -72,6 +98,8 @@
     "web:dev": "node apps/web/serve.mjs",
     "prepublishOnly": "pnpm run build",
     "ab:publish": "tsx benchmarks/publish.ts",
+    "ab:sonda": "BVSALA_DEV_OPEN=1 tsx --env-file-if-exists=.env.bench benchmarks/sonda-del-banco.ts",
+    "medicion:reproducir": "node apps/web/public/measure/reproduce.mjs",
     "verja:calibrar": "tsx corpus/calibrar-la-verja.ts",
     "corpus:arnes": "tsx corpus/arnes/informe.ts",
     "corpus:auditar": "tsx corpus/auditoria/auditar.ts",
@@ -85,24 +113,62 @@
     "salida:anatomia": "tsx benchmarks/salida/anatomia.ts",
     "salida:por-clase": "tsx benchmarks/salida/por-clase.ts",
     "luz-verde": "bash scripts/luz-verde.sh",
-    "sonda:sdk": "BVSALA_DEV_OPEN=1 tsx --env-file-if-exists=.env.bench benchmarks/sdk/sonda.ts"
+    "sonda:sdk": "BVSALA_DEV_OPEN=1 tsx --env-file-if-exists=.env.bench benchmarks/sdk/sonda.ts",
+    "sbom:tarball": "tsx scripts/sbom.ts",
+    "cache-semantica": "BVSALA_DEV_OPEN=1 tsx benchmarks/cache-semantica/arnes.ts",
+    "cache-semantica:publicar": "tsx benchmarks/cache-semantica/publicar.ts"
   },
   "devDependencies": {
     "@noble/curves": "^2.2.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/sdk-trace-base": "^2.11.0",
     "@types/node": "^22.10.2",
     "gpt-tokenizer": "^3.4.0",
+    "hyparquet": "^1.31.2",
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
+    "vitest": "^2.1.8",
+    "@ai-sdk/openai": "4.0.78",
+    "@anthropic-ai/sdk": "0.128.0",
+    "@langchain/core": "1.2.13",
+    "@mastra/core": "1.71.0",
+    "ai": "7.0.118",
+    "ai-v6": "npm:ai@6.0.293",
+    "langchain": "1.5.14",
+    "zod": "4.6.5"
   },
   "packageManager": "pnpm@10.17.1",
   "peerDependencies": {
-    "gpt-tokenizer": "^3"
+    "@opentelemetry/api": "^1.9.0",
+    "gpt-tokenizer": "^3",
+    "@anthropic-ai/sdk": ">=0.103.0 <1",
+    "@langchain/core": ">=1.1.0 <2",
+    "@mastra/core": ">=1.68.0 <2",
+    "ai": "^6.0.0 || ^7.0.0",
+    "langchain": ">=1.1.0 <2"
   },
   "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
     "gpt-tokenizer": {
       "optional": true
+    },
+    "@anthropic-ai/sdk": {
+      "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
+    },
+    "@mastra/core": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "langchain": {
+      "optional": true
     }
   }
 }