@hostwebhook/platform-contracts 0.5.0 → 0.7.0

package/README.md

@@ -72,10 +72,55 @@ nadie que la ate al otro lado es una lista que vuelve a divergir — que es
 exactamente de donde se venía: había seis copias de los operadores de filtro y
 ninguna igual a otra.
 
+## Precios de los modelos
+
+Lo que los proveedores de LLM cobran por millón de tokens. Entrada y salida se
+tarifan **por separado**, con precios que suelen llevar un 5x entre ellos.
+
+```ts
+import {
+  calculateCost,
+  findPricingKey,
+  isModelPriced,
+  MODEL_PRICING,
+} from '@hostwebhook/platform-contracts';
+
+calculateCost('claude-sonnet-4-6', 1_000_000, 1_000_000);  // → 18 USD
+findPricingKey('claude-sonnet-4-6-20260101');              // → 'claude-sonnet-4-6'
+findPricingKey('modelo-que-no-existe');                    // → null
+```
+
+⚠️ **`null` no es cero.** `findPricingKey` devuelve `null` para un modelo que la
+tabla no conoce, y entonces `calculateCost` da `0`. Ese 0 significa «no sé
+cuánto vale», no «es gratis». Quien vaya a decidir algo con el número —un tope
+de gasto, una factura, una pantalla— tiene que preguntar antes con
+`isModelPriced()`. Tratar el 0 como gratis deja pasar sin límite justo los
+modelos recién salidos, que son los caros.
+
+La resolución **no adivina**: sólo vale una clave de la tabla que sea prefijo
+del modelo pedido, y hasta un separador. Así `claude-sonnet-4-6-20260101`
+encuentra su base, y `claude-opus-9` no hereda la tarifa de un vecino.
+
+### 🔴 Hay dos copias de esta tabla
+
+Ésta es la fuente de verdad desde el 2026-08-31.
+`hw-llm-traces/src/common/utils/pricing.ts` es la copia que hay que retirar; el
+PR que la hace consumir este paquete va en ese repo y todavía no está hecho.
+Mientras tanto, un cambio de tarifa se hace aquí **y** se copia allí.
+
+### Por qué aquí y no en la api
+
+Los topes de gasto del Chat Trigger se comprueban en el camino caliente del
+chat, una vez por turno. Preguntar la tarifa por red a `hw-llm-traces` metería
+latencia en cada turno y, si ese servicio está caído o sin configurar, el tope
+se caería **abierto** — que es lo mismo que no tenerlo.
+
 ## Qué no va aquí
 
-- Precios e ids de Stripe: viven en la configuración de la api, que es la única
-  que habla con Stripe. Cambiarlos no puede obligar a publicar un paquete.
+- Precios **de venta** e ids de Stripe: viven en la configuración de la api, que
+  es la única que habla con Stripe. Cambiarlos no puede obligar a publicar un
+  paquete. (No confundir con `precios/`, que es lo que los proveedores de LLM
+  nos cobran a nosotros — ver arriba.)
 - Límites por plan: `plan.constants.ts` en la api.
 - Etiquetas de pantalla: cómo se llama un operador para el usuario es cosa del
   dashboard (`lib/operadores.ts`). Aquí van las claves, no los textos.

package/dist/index.d.ts

@@ -6,9 +6,17 @@
  * escribe dos veces, un día se escribe distinto.
  *
  * Lo que NO entra: nada específico de un servicio, nada con secretos, y nada
- * cuyo cambio deba poder desplegarse sin publicar un paquete (precios, ids de
- * Stripe, límites por plan).
+ * cuyo cambio deba poder desplegarse sin publicar un paquete (precios de
+ * VENTA, ids de Stripe, límites por plan).
+ *
+ * ⚠️ «Precios» ahí arriba significa lo que HostWebhook le COBRA a un cliente.
+ * `precios/` es la otra cosa que se llama igual: lo que los proveedores de LLM
+ * NOS cobran a nosotros por token. Entra porque no es una palanca comercial
+ * sino un dato de entrada para un cálculo, y porque la api lo necesita en el
+ * camino caliente del chat, donde no puede ir a preguntárselo a otro servicio
+ * por red. La cabecera de `precios/tabla-de-precios.ts` lo cuenta entero.
  */
 export * from './addons';
 export * from './operadores';
+export * from './precios';
 export * from './servicios';

package/dist/index.js

@@ -22,9 +22,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * escribe dos veces, un día se escribe distinto.
  *
  * Lo que NO entra: nada específico de un servicio, nada con secretos, y nada
- * cuyo cambio deba poder desplegarse sin publicar un paquete (precios, ids de
- * Stripe, límites por plan).
+ * cuyo cambio deba poder desplegarse sin publicar un paquete (precios de
+ * VENTA, ids de Stripe, límites por plan).
+ *
+ * ⚠️ «Precios» ahí arriba significa lo que HostWebhook le COBRA a un cliente.
+ * `precios/` es la otra cosa que se llama igual: lo que los proveedores de LLM
+ * NOS cobran a nosotros por token. Entra porque no es una palanca comercial
+ * sino un dato de entrada para un cálculo, y porque la api lo necesita en el
+ * camino caliente del chat, donde no puede ir a preguntárselo a otro servicio
+ * por red. La cabecera de `precios/tabla-de-precios.ts` lo cuenta entero.
  */
 __exportStar(require("./addons"), exports);
 __exportStar(require("./operadores"), exports);
+__exportStar(require("./precios"), exports);
 __exportStar(require("./servicios"), exports);

package/dist/precios/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Lo que cuesta un token, por modelo.
+ *
+ * Un solo módulo por ahora: `tabla-de-precios`. Está en su propia carpeta
+ * porque lo que va a crecer aquí son las tarifas —contexto largo, audio,
+ * lotes— y no las formas de contrato, que es de lo que va `servicios/`.
+ *
+ * ⚠️ Aquí NO van los precios de venta ni los ids de Stripe. Ver la cabecera de
+ * `tabla-de-precios.ts`: son cosas distintas que se llaman igual.
+ */
+export * from './tabla-de-precios';

package/dist/precios/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Lo que cuesta un token, por modelo.
+ *
+ * Un solo módulo por ahora: `tabla-de-precios`. Está en su propia carpeta
+ * porque lo que va a crecer aquí son las tarifas —contexto largo, audio,
+ * lotes— y no las formas de contrato, que es de lo que va `servicios/`.
+ *
+ * ⚠️ Aquí NO van los precios de venta ni los ids de Stripe. Ver la cabecera de
+ * `tabla-de-precios.ts`: son cosas distintas que se llaman igual.
+ */
+__exportStar(require("./tabla-de-precios"), exports);

package/dist/precios/tabla-de-precios.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Cuánto cuesta un millón de tokens, por modelo y en USD.
+ *
+ * ## 🔴 Ésta es la FUENTE DE VERDAD desde el 2026-08-31
+ *
+ * La tabla nació en `hw-llm-traces/src/common/utils/pricing.ts`. Esa copia
+ * **hay que retirarla**: mientras siga ahí existen dos tablas, y dos tablas de
+ * lo mismo divergen —es literalmente el fallo que este paquete existe para
+ * evitar—. El PR que hace que `hw-llm-traces` importe de aquí y borre su
+ * fichero va en ESE repo y todavía no está hecho.
+ *
+ * Hasta que lo esté: **cualquier cambio de tarifa se hace aquí y se copia
+ * allí**, no al revés.
+ *
+ * ## Por qué esto vive en un paquete y no en la api
+ *
+ * Porque la api va a poner topes de gasto en dólares al Chat Trigger, y eso
+ * ocurre en el camino caliente del chat, una vez por turno. Preguntárselo por
+ * red a `hw-llm-traces` metería latencia en cada turno, y peor: si el servicio
+ * de trazas está caído o sin configurar, el tope se caería ABIERTO. Un tope de
+ * gasto que falla abierto no es un tope.
+ *
+ * Es el mismo motivo por el que las listas de operadores están en este
+ * paquete y no pegadas a su evaluador: lo necesitan los dos lados y no puede
+ * escribirse dos veces.
+ *
+ * ⚠️ Ojo con la regla de al lado, que se parece y NO es ésta: los precios de
+ * VENTA y los ids de Stripe —lo que HostWebhook le cobra a un cliente— siguen
+ * fuera, en la configuración de la api. Esto de aquí es lo que los proveedores
+ * de LLM nos cobran a nosotros: es un dato de entrada para un cálculo, no una
+ * palanca comercial que haya que poder mover sin publicar.
+ *
+ * ## (!) ESTA TABLA CADUCA
+ *
+ * Última verificación: 2026-08-26, contra las páginas oficiales:
+ *   OpenAI     https://developers.openai.com/api/docs/pricing
+ *   Anthropic  https://platform.claude.com/docs/en/about-claude/pricing
+ *   Google     https://ai.google.dev/gemini-api/docs/pricing
+ *
+ * La versión anterior llevaba parada desde el 2026-04-18 —y el servicio sin
+ * redesplegar desde entonces—, así que para agosto le faltaban familias
+ * enteras: gpt-5.5, gpt-5.6, Opus 5, Sonnet 5, Gemini 3.5/3.6/3.7. Un modelo
+ * ausente ya no se cobra con la tarifa de un vecino —`findPricingKey` se niega
+ * a adivinar— pero sale a coste CERO y con clave `null`: revisa esta tabla
+ * cuando veas trazas sin precio.
+ *
+ * Se conservan modelos retirados a propósito: las trazas históricas siguen
+ * consultándose y tienen que seguir cuadrando.
+ *
+ * ## Lo que esta tabla NO modela (aceptable para estimar coste)
+ *
+ *   - Contexto largo: `gemini-3.1-pro` y `gemini-2.5-pro` casi doblan tarifa
+ *     por encima de 200k tokens de entrada. Se usa siempre la base, así que
+ *     INFRAVALORA los prompts muy largos.
+ *   - Audio: `gemini-2.5-flash` y `3.1-flash-lite` cobran más el audio que el
+ *     texto. Aquí todo va a tarifa de texto.
+ *   - Anthropic: `inference_geo` "us" multiplica por 1,1, y el modo rápido de
+ *     Opus 5 / 4.8 cuesta $10/$50. No se modelan: HostWebhook no los usa.
+ *   - Descuento del 50% de las APIs por lotes. Nadie lo usa todavía.
+ *   - (!) Claude 4.7 en adelante usa un tokenizador nuevo que produce ~30% MÁS
+ *     tokens para el mismo texto. El precio por token no cambia, pero la
+ *     factura por la misma conversación sí.
+ *
+ * ⚠️ Quien ponga un tope de gasto sobre esto tiene que saber que INFRAVALORA
+ * en los casos de arriba. El tope real queda por encima del nominal.
+ */
+export interface ModelPricing {
+    input: number;
+    output: number;
+}
+export declare const MODEL_PRICING: Record<string, ModelPricing>;
+/**
+ * Qué entrada de la tabla pone precio a este modelo, o `null` cuando de verdad
+ * no lo sabemos.
+ *
+ * ## Por qué la regla es «la clave conocida es PREFIJO del modelo pedido»
+ *
+ * La versión anterior iba al revés: recortaba el modelo pedido y buscaba la
+ * primera clave que empezara por ese trozo. Dos fallos, los dos MEDIDOS
+ * ejecutando la función con 1M de entrada y 1M de salida:
+ *
+ *   - `gpt-5.4-turbo-2026` recortaba a `gpt-5.4` y `find()` devolvía la PRIMERA
+ *     clave declarada que empieza así —`gpt-5.4-pro`, a $30/$180—. Cobraba $210
+ *     donde la base `gpt-5.4` cuesta $17.50. Doce veces de más, y el ORDEN DE
+ *     DECLARACIÓN del objeto decidía la factura.
+ *   - `claude-opus-5` recortaba a `claude-opus` y cobraba $30 con la tarifa de
+ *     `claude-opus-4-7`. Un modelo ausente salía con un precio inventado y de
+ *     aspecto plausible.
+ *
+ * La dirección correcta es la contraria: sólo vale una clave que sea prefijo
+ * DEL MODELO PEDIDO, y gana la más larga. Eso cubre el caso real —un snapshot
+ * con fecha, `claude-sonnet-4-6-20260101`— y se niega a adivinar cuando de
+ * verdad es un modelo nuevo. Mejor decir «no lo sé» que cobrar la tarifa de
+ * otro.
+ *
+ * La frontera importa: `gpt-4` NO puede prestar su precio a `gpt-45-turbo`,
+ * así que el carácter siguiente tiene que ser un separador.
+ *
+ * ⚠️ Ese `null` es INFORMACIÓN, no un hueco que rellenar. Hay código aguas
+ * abajo que necesita distinguir «gratis» de «no sé cuánto vale» —un tope de
+ * gasto, sin ir más lejos—. Quien lo «mejore» adivinando le devuelve al
+ * llamante un número inventado con pinta de bueno.
+ */
+export declare function findPricingKey(model: string): string | null;
+/** True cuando la tabla sabe de verdad cuánto vale este modelo. */
+export declare function isModelPriced(model: string): boolean;
+/**
+ * Coste en USD, redondeado a 6 decimales (precisión de micro-dólar).
+ *
+ * ⚠️ Devuelve 0 para modelos que no sabemos poner en precio: usa
+ * `isModelPriced()` o `findPricingKey()` para distinguir «gratis» de «no lo
+ * sé» ANTES de enseñarle un 0 a una persona —o de dejar pasar un turno de chat
+ * porque su coste «no llega al tope»—.
+ *
+ * ⚠️ Entrada y salida se tarifan POR SEPARADO, con precios distintos y a
+ * menudo con un factor de 5x entre ellos. Sumar tokens y multiplicar por un
+ * precio único da un número que no es el de nadie.
+ *
+ * ## (!) `outputTokens` YA incluye el razonamiento
+ *
+ * `reasoningTokens` es INFORMATIVO y no se cobra aparte, porque los dos
+ * proveedores que lo reportan ya lo tienen dentro de la salida:
+ *
+ *   - OpenAI: "reasoning tokens ... are billed as output tokens";
+ *     `completion_tokens_details.reasoning_tokens` es un desglose de
+ *     `completion_tokens`, no un extra.
+ *   - Google: `thoughtsTokenCount` va aparte de `candidatesTokenCount` en el
+ *     JSON, así que quien emite tiene que sumarlos ANTES de mandar
+ *     `outputTokens` — es lo que hace HostWebhook desde el arreglo del conteo
+ *     de Gemini.
+ *
+ * Antes se sumaba `reasoningTokens * precio_de_salida` ENCIMA de
+ * `outputTokens` para openai y google: eso cobraba dos veces el mismo
+ * pensamiento. El parámetro se conserva para no romper a quien ya lo pasa.
+ */
+export declare function calculateCost(model: string, inputTokens: number, outputTokens: number, cacheReadInputTokens?: number, cacheCreationInputTokens?: number, _reasoningTokens?: number): number;
+/** Los modelos que la tabla sabe poner en precio, en orden de declaración. */
+export declare function getKnownModels(): string[];
+/**
+ * De un modelo caro a otro más barato de capacidad parecida.
+ *
+ * ⚠️ Es un mapa a mano y NO cubre toda la tabla: un modelo que no está aquí
+ * simplemente no tiene sugerencia. No es la lista de modelos válidos —esa es
+ * `MODEL_PRICING`—.
+ */
+export declare const MODEL_ALTERNATIVES: Record<string, string>;
+/**
+ * La alternativa más barata sugerida para este modelo y lo que se ahorraría,
+ * o `null` cuando no hay sugerencia.
+ *
+ * ⚠️ Busca por el nombre EXACTO en `MODEL_ALTERNATIVES` —no usa
+ * `findPricingKey`—, así que un snapshot con fecha no encuentra sugerencia
+ * aunque su modelo base sí la tenga. Se conserva tal cual: cambiarlo alteraría
+ * qué se le sugiere hoy a la gente.
+ */
+export declare function getSuggestedAlternative(model: string, inputTokens: number, outputTokens: number): {
+    alternativeModel: string;
+    currentCost: number;
+    alternativeCost: number;
+    savingsUsd: number;
+    savingsPercent: number;
+} | null;

package/dist/precios/tabla-de-precios.js

@@ -0,0 +1,363 @@
+"use strict";
+/**
+ * Cuánto cuesta un millón de tokens, por modelo y en USD.
+ *
+ * ## 🔴 Ésta es la FUENTE DE VERDAD desde el 2026-08-31
+ *
+ * La tabla nació en `hw-llm-traces/src/common/utils/pricing.ts`. Esa copia
+ * **hay que retirarla**: mientras siga ahí existen dos tablas, y dos tablas de
+ * lo mismo divergen —es literalmente el fallo que este paquete existe para
+ * evitar—. El PR que hace que `hw-llm-traces` importe de aquí y borre su
+ * fichero va en ESE repo y todavía no está hecho.
+ *
+ * Hasta que lo esté: **cualquier cambio de tarifa se hace aquí y se copia
+ * allí**, no al revés.
+ *
+ * ## Por qué esto vive en un paquete y no en la api
+ *
+ * Porque la api va a poner topes de gasto en dólares al Chat Trigger, y eso
+ * ocurre en el camino caliente del chat, una vez por turno. Preguntárselo por
+ * red a `hw-llm-traces` metería latencia en cada turno, y peor: si el servicio
+ * de trazas está caído o sin configurar, el tope se caería ABIERTO. Un tope de
+ * gasto que falla abierto no es un tope.
+ *
+ * Es el mismo motivo por el que las listas de operadores están en este
+ * paquete y no pegadas a su evaluador: lo necesitan los dos lados y no puede
+ * escribirse dos veces.
+ *
+ * ⚠️ Ojo con la regla de al lado, que se parece y NO es ésta: los precios de
+ * VENTA y los ids de Stripe —lo que HostWebhook le cobra a un cliente— siguen
+ * fuera, en la configuración de la api. Esto de aquí es lo que los proveedores
+ * de LLM nos cobran a nosotros: es un dato de entrada para un cálculo, no una
+ * palanca comercial que haya que poder mover sin publicar.
+ *
+ * ## (!) ESTA TABLA CADUCA
+ *
+ * Última verificación: 2026-08-26, contra las páginas oficiales:
+ *   OpenAI     https://developers.openai.com/api/docs/pricing
+ *   Anthropic  https://platform.claude.com/docs/en/about-claude/pricing
+ *   Google     https://ai.google.dev/gemini-api/docs/pricing
+ *
+ * La versión anterior llevaba parada desde el 2026-04-18 —y el servicio sin
+ * redesplegar desde entonces—, así que para agosto le faltaban familias
+ * enteras: gpt-5.5, gpt-5.6, Opus 5, Sonnet 5, Gemini 3.5/3.6/3.7. Un modelo
+ * ausente ya no se cobra con la tarifa de un vecino —`findPricingKey` se niega
+ * a adivinar— pero sale a coste CERO y con clave `null`: revisa esta tabla
+ * cuando veas trazas sin precio.
+ *
+ * Se conservan modelos retirados a propósito: las trazas históricas siguen
+ * consultándose y tienen que seguir cuadrando.
+ *
+ * ## Lo que esta tabla NO modela (aceptable para estimar coste)
+ *
+ *   - Contexto largo: `gemini-3.1-pro` y `gemini-2.5-pro` casi doblan tarifa
+ *     por encima de 200k tokens de entrada. Se usa siempre la base, así que
+ *     INFRAVALORA los prompts muy largos.
+ *   - Audio: `gemini-2.5-flash` y `3.1-flash-lite` cobran más el audio que el
+ *     texto. Aquí todo va a tarifa de texto.
+ *   - Anthropic: `inference_geo` "us" multiplica por 1,1, y el modo rápido de
+ *     Opus 5 / 4.8 cuesta $10/$50. No se modelan: HostWebhook no los usa.
+ *   - Descuento del 50% de las APIs por lotes. Nadie lo usa todavía.
+ *   - (!) Claude 4.7 en adelante usa un tokenizador nuevo que produce ~30% MÁS
+ *     tokens para el mismo texto. El precio por token no cambia, pero la
+ *     factura por la misma conversación sí.
+ *
+ * ⚠️ Quien ponga un tope de gasto sobre esto tiene que saber que INFRAVALORA
+ * en los casos de arriba. El tope real queda por encima del nominal.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODEL_ALTERNATIVES = exports.MODEL_PRICING = void 0;
+exports.findPricingKey = findPricingKey;
+exports.isModelPriced = isModelPriced;
+exports.calculateCost = calculateCost;
+exports.getKnownModels = getKnownModels;
+exports.getSuggestedAlternative = getSuggestedAlternative;
+exports.MODEL_PRICING = {
+    // OpenAI — GPT series
+    'gpt-5.6-sol': { input: 4.00, output: 20.00 },
+    'gpt-5.6-terra': { input: 2.00, output: 12.00 },
+    'gpt-5.6-luna': { input: 0.20, output: 1.20 },
+    'gpt-5.5-pro': { input: 30.00, output: 180.00 },
+    'gpt-5.5': { input: 5.00, output: 30.00 },
+    'gpt-5.4-pro': { input: 30.00, output: 180.00 },
+    'gpt-5.4': { input: 2.50, output: 15.00 },
+    'gpt-5.4-mini': { input: 0.75, output: 4.50 },
+    'gpt-5.4-nano': { input: 0.20, output: 1.25 },
+    'gpt-5.2-pro': { input: 21.00, output: 168.00 },
+    'gpt-5.2': { input: 1.75, output: 14.00 },
+    'gpt-5.1': { input: 1.25, output: 10.00 },
+    'gpt-5-pro': { input: 15.00, output: 120.00 },
+    'gpt-5': { input: 1.25, output: 10.00 },
+    'gpt-5-mini': { input: 0.25, output: 2.00 },
+    'gpt-5-nano': { input: 0.05, output: 0.40 },
+    'gpt-4.1': { input: 2.00, output: 8.00 },
+    'gpt-4.1-mini': { input: 0.40, output: 1.60 },
+    'gpt-4.1-nano': { input: 0.10, output: 0.40 },
+    'gpt-4o': { input: 2.50, output: 10.00 },
+    'gpt-4o-mini': { input: 0.15, output: 0.60 },
+    'gpt-4-turbo': { input: 10.00, output: 30.00 },
+    'gpt-4': { input: 30.00, output: 60.00 },
+    'gpt-3.5-turbo': { input: 0.50, output: 1.50 },
+    'gpt-4o-2024-05-13': { input: 5.00, output: 15.00 },
+    'chat-latest': { input: 5.00, output: 30.00 },
+    // OpenAI — reasoning series
+    'o1-pro': { input: 150.00, output: 600.00 },
+    'o1': { input: 15.00, output: 60.00 },
+    'o1-mini': { input: 1.10, output: 4.40 },
+    'o3-pro': { input: 20.00, output: 80.00 },
+    'o3': { input: 2.00, output: 8.00 },
+    'o3-mini': { input: 1.10, output: 4.40 },
+    'o4-mini': { input: 1.10, output: 4.40 },
+    // Anthropic
+    'claude-fable-5': { input: 10.00, output: 50.00 },
+    'claude-mythos-5': { input: 10.00, output: 50.00 },
+    'claude-opus-5': { input: 5.00, output: 25.00 },
+    'claude-opus-4-8': { input: 5.00, output: 25.00 },
+    'claude-opus-4-7': { input: 5.00, output: 25.00 },
+    'claude-opus-4-6': { input: 5.00, output: 25.00 },
+    'claude-opus-4-5': { input: 5.00, output: 25.00 },
+    /* (!) `claude-opus-4-20250514` ES Claude Opus 4, y Opus 4 cuesta $15/$75.
+       Estaba a $5/$25 —la tarifa de la generación 4.5 en adelante—, o sea
+       cobrando un TERCIO de lo real. Se quitó además `claude-opus-4-5-20250514`,
+       un id que mezclaba la versión 4.5 con la fecha de lanzamiento de la 4; si
+       alguna vez llega, `findPricingKey` lo resuelve solo contra
+       `claude-opus-4-5`. */
+    'claude-opus-4-20250514': { input: 15.00, output: 75.00 },
+    'claude-opus-4': { input: 15.00, output: 75.00 },
+    'claude-opus-4-1': { input: 15.00, output: 75.00 },
+    'claude-sonnet-5': { input: 2.00, output: 10.00 },
+    'claude-sonnet-4-6': { input: 3.00, output: 15.00 },
+    'claude-sonnet-4-5': { input: 3.00, output: 15.00 },
+    'claude-sonnet-4-5-20250514': { input: 3.00, output: 15.00 },
+    'claude-sonnet-4': { input: 3.00, output: 15.00 },
+    'claude-sonnet-4-20250514': { input: 3.00, output: 15.00 },
+    'claude-haiku-4-5-20251001': { input: 1.00, output: 5.00 },
+    'claude-3-7-sonnet-20250219': { input: 3.00, output: 15.00 },
+    'claude-3-5-sonnet-20241022': { input: 3.00, output: 15.00 },
+    'claude-3-5-haiku-20241022': { input: 0.80, output: 4.00 },
+    'claude-3-opus-20240229': { input: 15.00, output: 75.00 },
+    'claude-haiku-3': { input: 0.25, output: 1.25 },
+    // Google
+    'gemini-3.7-flash': { input: 0.75, output: 3.75 },
+    'gemini-3.6-flash': { input: 0.75, output: 3.75 },
+    'gemini-3.5-flash-lite': { input: 0.30, output: 2.50 },
+    'gemini-3.5-flash': { input: 1.50, output: 9.00 },
+    'gemini-3.1-pro': { input: 2.00, output: 12.00 },
+    'gemini-3.1-flash-lite': { input: 0.25, output: 1.50 },
+    'gemini-3-flash': { input: 0.50, output: 3.00 },
+    'gemini-2.5-pro': { input: 1.25, output: 10.00 },
+    'gemini-2.5-flash': { input: 0.30, output: 2.50 },
+    'gemini-2.5-flash-lite': { input: 0.10, output: 0.40 },
+    'gemini-2.0-flash': { input: 0.10, output: 0.40 },
+    'gemini-1.5-pro': { input: 1.25, output: 5.00 },
+    'gemini-1.5-flash': { input: 0.075, output: 0.30 },
+    // Mistral
+    'mistral-large-latest': { input: 2.00, output: 6.00 },
+    'mistral-small-latest': { input: 0.20, output: 0.60 },
+    'codestral-latest': { input: 0.30, output: 0.90 },
+    // Cohere
+    'command-r-plus': { input: 2.50, output: 10.00 },
+    'command-r': { input: 0.15, output: 0.60 },
+};
+/* ── Caché ───────────────────────────────────────────────────────── */
+/** Multiplicadores de lectura de caché, sobre el precio de ENTRADA. */
+const CACHE_READ_MULTIPLIERS = {
+    anthropic: 0.1, // 10% del precio de entrada
+    openai: 0.5, // 50% del precio de entrada
+    google: 0.1, // 10% del precio de entrada ($0.125/$1.25)
+};
+/** Multiplicadores de creación de caché, sobre el precio de ENTRADA. */
+const CACHE_CREATION_MULTIPLIERS = {
+    anthropic: 1.25, // 125% del precio de entrada
+    // OpenAI y Google: la creación no se cobra (cacheado automático)
+};
+function detectProvider(model) {
+    if (model.startsWith('gpt-') ||
+        model.startsWith('o1') ||
+        model.startsWith('o3') ||
+        model.startsWith('o4'))
+        return 'openai';
+    if (model.includes('claude'))
+        return 'anthropic';
+    if (model.includes('gemini'))
+        return 'google';
+    if (model.includes('mistral') || model.includes('mixtral'))
+        return 'mistral';
+    if (model.includes('command'))
+        return 'cohere';
+    return 'custom';
+}
+/* ── Resolución del modelo ───────────────────────────────────────── */
+/**
+ * Qué entrada de la tabla pone precio a este modelo, o `null` cuando de verdad
+ * no lo sabemos.
+ *
+ * ## Por qué la regla es «la clave conocida es PREFIJO del modelo pedido»
+ *
+ * La versión anterior iba al revés: recortaba el modelo pedido y buscaba la
+ * primera clave que empezara por ese trozo. Dos fallos, los dos MEDIDOS
+ * ejecutando la función con 1M de entrada y 1M de salida:
+ *
+ *   - `gpt-5.4-turbo-2026` recortaba a `gpt-5.4` y `find()` devolvía la PRIMERA
+ *     clave declarada que empieza así —`gpt-5.4-pro`, a $30/$180—. Cobraba $210
+ *     donde la base `gpt-5.4` cuesta $17.50. Doce veces de más, y el ORDEN DE
+ *     DECLARACIÓN del objeto decidía la factura.
+ *   - `claude-opus-5` recortaba a `claude-opus` y cobraba $30 con la tarifa de
+ *     `claude-opus-4-7`. Un modelo ausente salía con un precio inventado y de
+ *     aspecto plausible.
+ *
+ * La dirección correcta es la contraria: sólo vale una clave que sea prefijo
+ * DEL MODELO PEDIDO, y gana la más larga. Eso cubre el caso real —un snapshot
+ * con fecha, `claude-sonnet-4-6-20260101`— y se niega a adivinar cuando de
+ * verdad es un modelo nuevo. Mejor decir «no lo sé» que cobrar la tarifa de
+ * otro.
+ *
+ * La frontera importa: `gpt-4` NO puede prestar su precio a `gpt-45-turbo`,
+ * así que el carácter siguiente tiene que ser un separador.
+ *
+ * ⚠️ Ese `null` es INFORMACIÓN, no un hueco que rellenar. Hay código aguas
+ * abajo que necesita distinguir «gratis» de «no sé cuánto vale» —un tope de
+ * gasto, sin ir más lejos—. Quien lo «mejore» adivinando le devuelve al
+ * llamante un número inventado con pinta de bueno.
+ */
+function findPricingKey(model) {
+    if (!model)
+        return null;
+    if (exports.MODEL_PRICING[model])
+        return model;
+    const SEPARADORES = new Set(['-', '_', '.', ':', '@', '/']);
+    let mejor = null;
+    for (const key of Object.keys(exports.MODEL_PRICING)) {
+        if (!model.startsWith(key))
+            continue;
+        if (!SEPARADORES.has(model.charAt(key.length)))
+            continue;
+        if (!mejor || key.length > mejor.length)
+            mejor = key;
+    }
+    return mejor;
+}
+/** True cuando la tabla sabe de verdad cuánto vale este modelo. */
+function isModelPriced(model) {
+    return findPricingKey(model) !== null;
+}
+/* ── Coste ───────────────────────────────────────────────────────── */
+/**
+ * Coste en USD, redondeado a 6 decimales (precisión de micro-dólar).
+ *
+ * ⚠️ Devuelve 0 para modelos que no sabemos poner en precio: usa
+ * `isModelPriced()` o `findPricingKey()` para distinguir «gratis» de «no lo
+ * sé» ANTES de enseñarle un 0 a una persona —o de dejar pasar un turno de chat
+ * porque su coste «no llega al tope»—.
+ *
+ * ⚠️ Entrada y salida se tarifan POR SEPARADO, con precios distintos y a
+ * menudo con un factor de 5x entre ellos. Sumar tokens y multiplicar por un
+ * precio único da un número que no es el de nadie.
+ *
+ * ## (!) `outputTokens` YA incluye el razonamiento
+ *
+ * `reasoningTokens` es INFORMATIVO y no se cobra aparte, porque los dos
+ * proveedores que lo reportan ya lo tienen dentro de la salida:
+ *
+ *   - OpenAI: "reasoning tokens ... are billed as output tokens";
+ *     `completion_tokens_details.reasoning_tokens` es un desglose de
+ *     `completion_tokens`, no un extra.
+ *   - Google: `thoughtsTokenCount` va aparte de `candidatesTokenCount` en el
+ *     JSON, así que quien emite tiene que sumarlos ANTES de mandar
+ *     `outputTokens` — es lo que hace HostWebhook desde el arreglo del conteo
+ *     de Gemini.
+ *
+ * Antes se sumaba `reasoningTokens * precio_de_salida` ENCIMA de
+ * `outputTokens` para openai y google: eso cobraba dos veces el mismo
+ * pensamiento. El parámetro se conserva para no romper a quien ya lo pasa.
+ */
+function calculateCost(model, inputTokens, outputTokens, cacheReadInputTokens = 0, cacheCreationInputTokens = 0, _reasoningTokens = 0) {
+    const key = findPricingKey(model);
+    if (!key)
+        return 0;
+    const pricing = exports.MODEL_PRICING[key];
+    const provider = detectProvider(key);
+    const inputCost = (inputTokens / 1000000) * pricing.input;
+    const outputCost = (outputTokens / 1000000) * pricing.output;
+    // Caché: multiplicadores por proveedor
+    const cacheReadMul = CACHE_READ_MULTIPLIERS[provider] ?? 0.1;
+    const cacheCreationMul = CACHE_CREATION_MULTIPLIERS[provider] ?? 0;
+    const cacheReadCost = (cacheReadInputTokens / 1000000) * pricing.input * cacheReadMul;
+    const cacheCreationCost = (cacheCreationInputTokens / 1000000) * pricing.input * cacheCreationMul;
+    return (Math.round((inputCost + outputCost + cacheReadCost + cacheCreationCost) * 1000000) / 1000000);
+}
+/** Los modelos que la tabla sabe poner en precio, en orden de declaración. */
+function getKnownModels() {
+    return Object.keys(exports.MODEL_PRICING);
+}
+/* ── Alternativas más baratas ────────────────────────────────────── */
+/**
+ * De un modelo caro a otro más barato de capacidad parecida.
+ *
+ * ⚠️ Es un mapa a mano y NO cubre toda la tabla: un modelo que no está aquí
+ * simplemente no tiene sugerencia. No es la lista de modelos válidos —esa es
+ * `MODEL_PRICING`—.
+ */
+exports.MODEL_ALTERNATIVES = {
+    // OpenAI — GPT series
+    'gpt-5.4': 'gpt-5.2',
+    'gpt-5.2': 'gpt-5',
+    'gpt-5.1': 'gpt-5-mini',
+    'gpt-5': 'gpt-5-mini',
+    'gpt-5-mini': 'gpt-5-nano',
+    'gpt-4.1': 'gpt-4.1-mini',
+    'gpt-4.1-mini': 'gpt-4.1-nano',
+    'gpt-4o': 'gpt-4o-mini',
+    'gpt-4-turbo': 'gpt-4.1',
+    'gpt-4': 'gpt-4.1',
+    // OpenAI — reasoning series
+    'o1': 'o3',
+    'o3': 'o4-mini',
+    'o1-mini': 'o4-mini',
+    'o3-mini': 'o4-mini',
+    // Anthropic
+    'claude-opus-4-6': 'claude-sonnet-4-6',
+    'claude-opus-4-20250514': 'claude-sonnet-4-20250514',
+    'claude-sonnet-4-6': 'claude-haiku-4-5-20251001',
+    'claude-sonnet-4-20250514': 'claude-haiku-4-5-20251001',
+    'claude-3-7-sonnet-20250219': 'claude-haiku-4-5-20251001',
+    'claude-3-5-sonnet-20241022': 'claude-3-5-haiku-20241022',
+    'claude-3-opus-20240229': 'claude-sonnet-4-6',
+    // Google
+    'gemini-3.1-pro': 'gemini-3-flash',
+    'gemini-3-flash': 'gemini-2.5-flash',
+    'gemini-2.5-pro': 'gemini-2.5-flash',
+    'gemini-2.5-flash': 'gemini-2.5-flash-lite',
+    'gemini-1.5-pro': 'gemini-2.5-flash',
+    // Mistral
+    'mistral-large-latest': 'mistral-small-latest',
+    // Cohere
+    'command-r-plus': 'command-r',
+};
+/**
+ * La alternativa más barata sugerida para este modelo y lo que se ahorraría,
+ * o `null` cuando no hay sugerencia.
+ *
+ * ⚠️ Busca por el nombre EXACTO en `MODEL_ALTERNATIVES` —no usa
+ * `findPricingKey`—, así que un snapshot con fecha no encuentra sugerencia
+ * aunque su modelo base sí la tenga. Se conserva tal cual: cambiarlo alteraría
+ * qué se le sugiere hoy a la gente.
+ */
+function getSuggestedAlternative(model, inputTokens, outputTokens) {
+    const alt = exports.MODEL_ALTERNATIVES[model];
+    if (!alt)
+        return null;
+    const currentCost = calculateCost(model, inputTokens, outputTokens);
+    const alternativeCost = calculateCost(alt, inputTokens, outputTokens);
+    if (currentCost <= 0)
+        return null;
+    const savingsUsd = currentCost - alternativeCost;
+    const savingsPercent = Math.round((savingsUsd / currentCost) * 10000) / 100;
+    return {
+        alternativeModel: alt,
+        currentCost: Math.round(currentCost * 1000000) / 1000000,
+        alternativeCost: Math.round(alternativeCost * 1000000) / 1000000,
+        savingsUsd: Math.round(savingsUsd * 1000000) / 1000000,
+        savingsPercent,
+    };
+}

package/dist/servicios/historial-de-corridas.d.ts

@@ -68,6 +68,38 @@ export interface GrabadorDeHistorial {
      * tiene que garantizarlo también.
      */
     cerrar(correlationId: string): void;
+    /**
+     * Sella la versión del flujo y devuelve su huella, o `null` si no hay flujo
+     * que sellar.
+     *
+     * ## 🔥 Por qué está en el contrato y no se calcula donde se graba
+     *
+     * La huella ES la forma del flujo, y la forma se lee del LIENZO, que hoy
+     * vive en el gateway. Sin lienzo no hay huella, y no se puede inventar.
+     *
+     * Cuando hw-nodes empezó a grabar el historial por su cuenta, esta llamada
+     * se quedó fuera — y el efecto no era «esta corrida pierde su foto»:
+     * `asegurarVersion` no CONSULTA la versión, la **CREA**. El que graba el paso
+     * es el único que la llama, así que sin ella **deja de haber fotos** y el
+     * historial de versiones del flujo se congela en la última que selló el
+     * gateway.
+     *
+     * ## ⚠️ Es `Promise`, a diferencia de los otros dos
+     *
+     * `registrarPaso` y `cerrar` son `void` porque corren en el camino caliente
+     * de cada paso. Éste no: se llama **una vez por corrida** —quien lo
+     * implemente debe recordar el resultado por `correlationId`— y el que graba
+     * necesita la huella para escribirla en la fila. Un `void` aquí obligaría a
+     * escribir la corrida sin huella y volver a por ella después.
+     *
+     * ⚠️ Y devuelve `null` de verdad cuando no hay nada que sellar (sin
+     * `workspaceId`, o si el lienzo falla). `null` NO es «reusa la última»:
+     * escribir una huella que no es la de esa corrida se lee peor que no tener
+     * ninguna, porque nadie sospecha de ella.
+     */
+    sellarVersion(orgId: string, workspaceId?: string, 
+    /** De qué nodo salió la corrida. Decide QUÉ flujo se sella. */
+    sourceId?: string): Promise<string | null>;
 }
 /**
  * ⚠️ Cadena y no `Symbol`, igual que el resto de tokens de la Fase 2.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/platform-contracts",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Contratos compartidos entre los servicios de HostWebhook: addons del plan, identidad interna, y las formas que cruzan una frontera de red",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",