Costos y consumo

Theus estima el costo y el consumo de tokens de tu sesión de forma local, a partir del uso real de cada modelo. Sin proveedor remoto obligatorio: cuando trabajas con tu propia clave (BYOK) o con un modelo local, el costo real lo define tu proveedor.

El comando /cost

Escribe /cost en la sesión para ver un resumen del costo total y la duración acumulada. El comando muestra el costo total y la duración de la sesión actual y también funciona en modo no interactivo.

El resumen incluye estos campos:

• Total cost — costo estimado acumulado en USD.
• Total duration (API) — tiempo total consumido en llamadas al proveedor.
• Total duration (wall) — tiempo total transcurrido de la sesión.
• Total code changes — líneas añadidas y eliminadas por las herramientas.
• Usage by model — desglose por modelo: tokens de entrada, de salida, de lectura de caché, de escritura de caché y, si aplica, búsquedas web, con el costo parcial de cada modelo.

Cómo se calcula el consumo

Cada respuesta del modelo reporta su uso de tokens. Theus toma esos valores y los multiplica por la tarifa del modelo para obtener un costo en USD, acumulándolo en el estado de la sesión. El cálculo cubre cinco componentes:

• Tokens de entrada (input).
• Tokens de salida (output).
• Tokens de lectura de caché de prompt (cache read), mucho más baratos que la entrada normal.
• Tokens de escritura de caché de prompt (cache write).
• Búsquedas web, tarifadas por solicitud.

Las tarifas se expresan por millón de tokens (Mtok). A modo de referencia, Theus mantiene varios niveles de precio internos, por ejemplo:

Las búsquedas web se tarifan a $0.01 por solicitud. Algunos modelos tienen una tarifa distinta bajo modo rápido.

Cómo Theus reduce tu consumo

Además de contar tokens, Theus trabaja activamente para que gastes menos. Tres mecanismos operan de forma automática:

• Prompt caching nativo. Cuando el gateway enruta a un modelo de la familia Claude, usa el adaptador nativo (API /v1/messages) y marca puntos de caché explícitos (cache_control) en el system prompt, las herramientas y el último mensaje. El contexto repetido entre turnos se sirve como lectura de caché, que cuesta ~10% de la tarifa de entrada normal — un descuento de ~90% en la parte del prompt que no cambia. En el desglose de /cost lo ves como tokens de lectura y escritura de caché.
• Microcompact. Theus limpia automáticamente del contexto los resultados antiguos de herramientas (lecturas de archivos, comandos de shell, búsquedas) que ya no aportan al turno actual. Menos contexto enviado = menos tokens de entrada, sin que pierdas el hilo de la conversación.
• Memoria y recall. El índice local y el recall híbrido devuelven símbolos con archivo:línea, memorias del proyecto y el subgrafo de relaciones, de modo que el agente no relee archivos completos para reencontrar lo que ya conoce. Los episodios de sesiones anteriores también se recuperan sin reconstruir contexto. Ver Memoria.

Cuotas por plan (suscripción Theus)

Con la suscripción Theus no pagas por token: cada plan incluye una cuota de tokens y un límite de solicitudes por minuto. La cuota se renueva por ciclo: en el plan Free por mes calendario, y en los planes pagados anclada al periodo de facturación de tu suscripción.

Al agotar la cuota del ciclo, el gateway rechaza las peticiones con HTTP 429 y código quota_exceeded, indicando la fecha de renovación y la cabecera Retry-After:

HTTP 429  quota_exceeded
"Alcanzaste el límite de tokens incluidos en tu plan para este periodo.
 Tu cuota se renueva el <fecha>."

Si superas el límite de solicitudes por minuto (sin agotar la cuota), recibes el mismo HTTP 429 pero con código rate_limit_exceeded y un Retry-After de segundos. Puedes mejorar tu plan en theus.pe/#planes.

Modelos desconocidos y estimaciones

Theus solo conoce las tarifas de sus propios modelos de primera parte. Si usas un modelo cuyo precio no está registrado, Theus lo estima aplicando una tarifa por defecto y marca el resumen con una advertencia:

Total cost:            $0.1234 (costs may be inaccurate due to usage of unknown models)

Modelo local-first: el costo depende del proveedor

Theus es local-first: ningún servicio remoto es obligatorio para arrancar. Esto tiene consecuencias directas sobre el costo:

• Modelo local — si ejecutas el modelo en tu propia máquina o infraestructura, no hay cargo por token: el "costo" es tu propio cómputo. La estimación de /cost puede seguir apareciendo, pero no representa un gasto facturable.
• BYOK (tu propia clave) — al conectar tu clave a un proveedor compatible, el consumo y la tarifa reales los define ese proveedor, según su propia política de precios. La estimación de Theus solo coincidirá con tu factura si el modelo y sus tarifas coinciden con los niveles conocidos.
• Suscripción Theus — el uso se cubre con la cuota de tokens de tu plan (ver Cuotas por plan); /cost lo refleja como cobertura de suscripción en lugar de gasto por token.

La selección de proveedor sigue el orden documentado (variables THEUS_BASE_URL / THEUS_OPENAI_BASE_URL, luego el primer proveedor con capacidad de texto en ~/.theus/providers.json, y por último el motor compatible). El costo depende de cuál de estos atiende tus solicitudes.

Persistencia y resumen de sesión

El costo acumulado se guarda junto con la configuración del proyecto y se asocia a la sesión actual. Al reanudar la misma sesión, Theus restaura el costo, la duración y el uso por modelo, de modo que el total sigue creciendo desde donde lo dejaste en lugar de reiniciarse.

Cuando la sesión termina, si tu cuenta tiene acceso a facturación en consola, Theus imprime automáticamente el mismo resumen de /cost al salir, para que quede un registro del consumo de la sesión.