# Sistemas de Monitoreo y Trazabilidad de Tokens para Agentes de IA

## Evaluación de Proyectos Open Source como Middleware para Auditoría de Prompts

---

> **Documento técnico** — Versión 1.0. Generado mediante investigación y análisis de 7+ proyectos open source.  
> **Contexto objetivo:** Ecosistema multi-agente (Claude Code CLI, Codex CLI, OpenCode CLI) con Headroom Proxy como gateway de optimización.

---

## Tabla de Contenidos

1. [Introducción](#1-introducción)
2. [Arquitectura de Referencia del Ecosistema Existente](#2-arquitectura-de-referencia-del-ecosistema-existente)
3. [Catálogo de Proyectos Open Source Evaluados](#3-catálogo-de-proyectos-open-source-evaluados)
4. [Comparativa Detallada](#4-comparativa-detallada)
5. [Recomendaciones](#5-recomendaciones)
6. [Guía de Integración Paso a Paso](#6-guía-de-integración-paso-a-paso)
7. [Limitaciones y Advertencias](#7-limitaciones-y-advertencias)
8. [Anexos](#8-anexos)

---

## 1. Introducción

### 1.1. Contexto del Ecosistema Actual

El entorno de desarrollo actual opera con una infraestructura de agentes de IA multi-proveedor altamente optimizada:

- **Claude Code CLI** → Tráfico HTTP redirigido vía Headroom Proxy (`:8787`) hacia Anthropic/OpenAI.
- **Codex CLI** → Tráfico WebSocket con `auth_mode = chatgpt`, redirigido vía `codex_ws_gated` de Headroom.
- **OpenCode CLI** → Conexión directa a `api.deepseek.com/v1`.
- **Zed Editor / JetBrains** → Integración vía **Agent Client Protocol (ACP)** sobre JSON-RPC local (stdin/stdout).
- **Headroom Proxy** (v0.28.0) → Gateway con caching, multi-upstream, sin interceptación de tool-calls (`--intercept-tool-results = OFF`).
- **codebase-memory-mcp** → Servicio de contexto en puerto `:9749`.
- **Gobernanza Caveman Lite/Ponytail** → Reglas de comunicación y código inyectadas via `CLAUDE.md`, `AGENTS.md` y `opencode.jsonc`.

A pesar de contar con optimización de caché de contexto y gobernanza de agentes, **no existe trazabilidad del tráfico real** que fluye entre los agentes y los upstreams. Esto impide auditar prompts completos, detectar fugas de contexto y medir el consumo real de tokens.

### 1.2. Problema a Resolver

| Problema | Impacto |
|---|---|
| Sin visibilidad de prompts completos enviados a cada modelo | Imposible auditar qué contexto exacto recibe el LLM |
| Sin trazabilidad de tokens por agente/sesión | No se puede optimizar el consumo ni detectar fugas |
| Sin historial centralizado de requests/responses | Depuración de comportamientos anómalos es manual y lenta |
| Sin UI de consulta | El análisis post-hoc requiere scraping de logs |
| Sin diferenciación por agente | No se sabe si el consumo alto viene de Claude Code, Codex u OpenCode |

### 1.3. Requisitos Funcionales y No Funcionales

**Funcionales:**

| ID | Requisito |
|---|---|
| RF-01 | Interceptar y registrar tráfico HTTP/HTTPS entre agentes y upstreams |
| RF-02 | Capturar prompts completos (system, user, assistant, tool-calls, tool-results) |
| RF-03 | Registrar metadatos: tokens input/output/cache, modelo, timestamp, agente origen |
| RF-04 | Proveer UI web para búsqueda y visualización del historial |
| RF-05 | Soportar múltiples upstreams (Anthropic, OpenAI, DeepSeek) |
| RF-06 | Soportar tráfico WebSocket (necesario para Codex CLI) |
| RF-07 | No interceptar ni modificar tool-calls (modo solo observación) |
| RF-08 | No interferir con context caching de Headroom |

**No Funcionales:**

| ID | Requisito |
|---|---|
| RNF-01 | RAM < 500 MB en reposo |
| RNF-02 | Latencia adicional < 50 ms por request |
| RNF-03 | Instalación sin Docker (preferible: binario nativo, Homebrew, pip) |
| RNF-04 | Mantenimiento activo (último commit < 6 meses) |
| RNF-05 | Licencia open source permisiva |
| RNF-06 | No requiere base de datos externa |

> 💡 **Tip:** Prioriza herramientas que operen como **proxy HTTP reverso** en lugar de SDK injection. Así evitas modificar cada agente individualmente.

---

## 2. Arquitectura de Referencia del Ecosistema Existente

### 2.1. Diagrama de Flujo Actual

```mermaid
flowchart LR
    subgraph Agentes["Agentes CLI"]
        CC[Claude Code CLI]
        CX[Codex CLI]
        OC[OpenCode CLI]
    end

    subgraph IDE["IDE Integration"]
        ZD[Zed Editor]
        JB[JetBrains IDEs]
    end

    subgraph Middleware["Middleware Local"]
        HP[Headroom Proxy<br>v0.28.0 :8787<br>--mode cache]
        CBM[codebase-memory-mcp<br>:9749]
    end

    subgraph Upstreams["Upstreams API"]
        AN[api.anthropic.com]
        OAI[api.openai.com]
        DS[api.deepseek.com]
    end

    CC -->|HTTP| HP
    CX -->|WebSocket| HP
    OC -->|HTTP directo| DS
    ZD -->|ACP / JSON-RPC| CC
    JB -->|ACP / JSON-RPC| CX
    HP -->|/v1/*| OAI
    HP -->|default| AN
    HP -.->|codex_ws_gated| AN
    CBM -.->|context graph| CC
    CBM -.->|context graph| CX
```

**Figura 1:** Arquitectura actual del ecosistema. Headroom Proxy centraliza el tráfico de Claude Code y Codex, mientras OpenCode habla directo con DeepSeek. codebase-memory-mcp provee el grafo de contexto.

### 2.2. Punto de Inserción del Middleware de Monitoreo

Existen tres estrategias de integración:

```mermaid
flowchart TD
    subgraph OptA["Opción A: Proxy en cadena (recomendada)"]
        A1[Agentes] --> A2[Headroom :8787]
        A2 --> A3[Monitor :8788]
        A3 --> A4[Upstreams]
    end

    subgraph OptB["Opción B: Proxy unificado"]
        B1[Agentes] --> B2[Monitor+Headroom<br>:8787 fusionado]
        B2 --> B3[Upstreams]
    end

    subgraph OptC["Opción C: Sidecar logging"]
        C1[Agentes] --> C2[Headroom :8787]
        C2 --> C3[Upstreams]
        C2 -.->|logs duplicados| C4[Monitor Sidecar]
    end
```

**Figura 2:** Estrategias de integración. La **Opción A** (proxy en cadena) es la más segura: no toca Headroom y solo añade una capa de logging.

> ⚠️ **Nota:** La Opción B requiere que el proyecto de monitoreo reemplace o extienda Headroom, lo cual no es recomendable sin conocer bien su arquitectura interna. La Opción C depende de que Headroom tenga un hook de logging externo (no confirmado en v0.28.0).

### 2.3. Restricciones Críticas de Integración

1. **Tool-calls intactas:** Headroom ya opera con `--intercept-tool-results = OFF`. El monitor debe respetar esta configuración y no modificar el payload de las tool-calls.
2. **Context caching:** No modificar headers de caché (`anthropic-beta`, `x-*` de cache).
3. **Latencia:** Idealmente < 20 ms de overhead por request para no afectar la experiencia.
4. **WebSocket persistente:** Codex usa conexiones WebSocket largas; el monitor debe manejarlas sin interrupción.
5. **ACP local:** Zed/JetBrains usan JSON-RPC sobre subprocesos locales (no HTTP). Un proxy HTTP externo no intercepta ese tráfico de forma directa.

---

## 3. Catálogo de Proyectos Open Source Evaluados

### 3.1. LiteLLM Proxy

| Atributo | Valor |
|---|---|
| **Repositorio** | [github.com/BerriAI/litellm](https://github.com/BerriAI/litellm) |
| **Estrellas** | ~52.1k ⭐ |
| **Licencia** | MIT |
| **Stack** | Python (FastAPI + Uvicorn); versión Rust en beta |
| **Última versión** | v1.90.0 (junio 2026) |

#### Funcionalidad Principal

LiteLLM es un **proxy HTTP reverso** compatible con API OpenAI. Recibe requests en formato OpenAI y los traduce a 100+ proveedores (Anthropic, OpenAI, DeepSeek, Google, etc.). Incluye:

- Logging de prompts y respuestas (opt-in: `store_prompts_in_spend_logs: true`)
- Rate limiting por clave virtual
- Enrutamiento por modelo/proveedor
- Fallback automático entre proveedores
- Seguimiento de costos y tokens por usuario/clave
- UI web de administración

#### Modo de Despliegue

```bash
# Opción 1: pip (recomendada para pruebas)
pip install litellm
litellm --model gpt-4 --port 8788

# Opción 2: Docker
docker run ghcr.io/berriai/litellm:main-latest \
  --config /app/config.yaml

# Opción 3: Docker Compose (producción - requiere PostgreSQL)
docker compose -f docker-compose.yml up
```

#### Consumo de Recursos

| Métrica | Valor |
|---|---|
| RAM idle (oficial) | ~359 MB |
| RAM pico (benchmark independiente) | ~12 GB bajo carga sostenida |
| Overhead de latencia | 7-12 ms (Python), ~0.05 ms (Rust beta) |
| Almacenamiento | Depende de PostgreSQL; logs en DB |
| Dependencias externas | **PostgreSQL obligatorio** para UI y persistencia |

#### Capacidad de Captura

- ✅ Captura prompts completos (system + user + assistant + tool-calls + tool-results)
- ✅ Almacena metadatos (modelo, tokens, costos, latencia)
- ✅ Permite logging a 20+ destinos (Langfuse, OTEL, S3, Datadog, etc.)
- ⚠️ WebSockets: solo para Vertex AI Live y OpenAI Realtime (no genérico para Codex)

#### Pros y Contras

| ✅ Pros | ❌ Contras |
|---|---|
| Soporte multi-proveedor excelente | **~12 GB RAM** bajo carga (Python) |
| API OpenAI-compatible (cambio trivial) | Requiere PostgreSQL para UI |
| Rate limiting granular | Versión Rust aún en beta |
| 20+ destinos de logging | Incidentes de seguridad en 2026 (CVE SQL injection) |
| Comunidad masiva (52k ⭐) | Redundancia con Headroom si ya hace caching |

#### Veredicto

**Recomendable con reservas.** Si Headroom no te da visibilidad de costos/tokens, LiteLLM aporta valor como capa de monitoreo. Pero la huella de RAM (~12 GB bajo carga) es incompatible con el requisito de ser ligero. La versión Rust (cuando esté estable) cambiará esta ecuación drásticamente (~32 MB RAM).

---

### 3.2. Helicone (self-hosted)

| Atributo | Valor |
|---|---|
| **Repositorio** | [github.com/Helicone/helicone](https://github.com/Helicone/helicone) |
| **Estrellas** | ~5.9k ⭐ |
| **Licencia** | Apache 2.0 (genuino, sin restricciones) |
| **Stack** | TypeScript + Next.js + ClickHouse + PostgreSQL + MinIO + Rust (Gateway) |
| **Último commit** | Activo (YC W23) |

Helicone tiene dos componentes principales que pueden desplegarse por separado:

#### AI Gateway (Rust)

```bash
# Proxy HTTP reverso en Rust (binario nativo, extremadamente rápido)
npx @helicone/ai-gateway --port 8788
# o bien
docker run helicone/ai-gateway
```

- **Overhead:** ~1-5 ms P95
- **Funcionalidad:** Proxy HTTP OpenAI-compatible, 100+ modelos, failover, rate limiting, caché semántica
- ❌ **No soporta WebSockets** (solo HTTP/SSE streaming)
- ✅ **Consumo ligero:** ~50-100 MB RAM
- ✅ **Sin base de datos externa** en modo gateway básico

#### Helicone Observability (Dashboard completo)

```bash
docker run helicone/helicone-all-in-one:latest
```

| Métrica | Valor |
|---|---|
| RAM recomendada | 16 GB |
| vCPU recomendados | 4 |
| Disco | 100 GB |
| Dependencias | PostgreSQL + ClickHouse + MinIO |
| Latencia adicional | ~1-50 ms |

#### Modo de Operación

Basta con cambiar el `baseURL` en el cliente. No requiere modificar lógica de negocio:

```python
# Sin Helicone
openai = OpenAI(api_key="sk-...")

# Con Helicone
openai = OpenAI(
    base_url="http://localhost:8788/v1",
    api_key="sk-..."
)
```

#### Pros y Contras

| ✅ Pros | ❌ Contras |
|---|---|
| Integración en 1 línea de código | Sin WebSockets nativos |
| Apache 2.0 genuino (sin restricciones) | Documentación orientada a Cloud |
| AI Gateway en Rust (rápido y ligero) | ~16 GB RAM recomendados para stack completo |
| Dashboard web con búsqueda y sesiones | Menos estrellas que LiteLLM/Langfuse |
| Gateway funciona sin base de datos | Proyecto startup (riesgo estratégico) |

#### Veredicto

**Recomendado como opción primaria** para monitoreo de tokens. El AI Gateway (Rust) solo es liviano (~50 MB RAM, ~1-5 ms overhead) y puede operar sin base de datos. El stack completo de observabilidad es pesado (~16 GB RAM) pero opcional. La limitación más importante: **no soporta WebSockets**, por lo que Codex CLI queda fuera del monitoreo.

---

### 3.3. Langfuse

| Atributo | Valor |
|---|---|
| **Repositorio** | [github.com/langfuse/langfuse](https://github.com/langfuse/langfuse) |
| **Estrellas** | ~30.2k ⭐ |
| **Licencia** | MIT (core) + EE features |
| **Stack** | TypeScript/Next.js + Express, Python SDK, JS SDK |
| **Último commit** | Activo (YC W23) |

#### ⚠️ Hallazgo Crítico

**Langfuse NO es un proxy HTTP.** Está diseñado como capa de observabilidad **asíncrona** que opera mediante SDK injection. No puede interceptar tráfico HTTP de forma transparente sin modificar el código de cada agente.

#### Modo de Operación

```python
# No funciona como proxy - requiere SDK injection en el código
from langfuse import Langfuse
langfuse = Langfuse()

# Decorador para tracing
@langfuse.observe()
def my_llm_call():
    ...
    return response
```

#### Consumo de Recursos (self-hosted)

| Servicio | Requisito |
|---|---|
| Web | Node.js server |
| Worker | Procesamiento asíncrono |
| PostgreSQL | Base de datos principal |
| ClickHouse | Almacenamiento de eventos/trazas |
| Redis | Cache y colas |
| Blob Storage | Archivos grandes |
| **Total estimado** | **~11 vCPU + ~25.5 GB RAM** |

#### Pros y Contras

| ✅ Pros | ❌ Contras |
|---|---|
| Excelente trazabilidad con grafos de agentes | **No es proxy** - requiere SDK en cada agente |
| Captura prompts completos con tool-calls | Infraestructura pesada (~25 GB RAM) |
| UI web muy completa | No apto para integración transparente |
| Comunidad grande y activa (30k ⭐) | Excesivo para el caso de uso actual |

#### Veredicto

**No recomendado** para este caso de uso. No puede actuar como middleware transparente entre Headroom y los upstreams. Su infraestructura requerida (~25 GB RAM) excede por mucho el límite de 500 MB. Adecuado solo si ya tienes un stack de observabilidad y puedes instrumentar cada agente individualmente.

---

### 3.4. Portkey AI Gateway

| Atributo | Valor |
|---|---|
| **Repositorio** | [github.com/Portkey-AI/gateway](https://github.com/Portkey-AI/gateway) |
| **Estrellas** | ~12.3k ⭐ |
| **Licencia** | MIT |
| **Stack** | TypeScript/Node.js (~122 kB core) |
| **Estado** | Adquirido por Palo Alto Networks (mayo 2026) |

#### Funcionalidad

Portkey es un **proxy HTTP + gateway** drop-in replacement del SDK de OpenAI. Opera como middleware:

```javascript
// Sin Portkey
const response = await openai.chat.completions.create({...});

// Con Portkey (solo cambiar baseURL)
const openai = new OpenAI({
  baseURL: "http://localhost:8788/v1",
  defaultHeaders: {
    "x-portkey-api-key": "your-key",
    "x-portkey-mode": "proxy openai"
  }
});
```

#### Capacidades

- ✅ Captura prompts completos, tool-calls, respuestas
- ✅ 40+ métricas de rendimiento
- ✅ Logging configurable
- ✅ Rate limiting y caching
- ⚠️ Dashboard completo requiere **Control Plane SaaS** de Portkey
- ⚠️ Adquisición reciente por Palo Alto → roadmap open source incierto

#### Consumo de Recursos

| Métrica | Valor |
|---|---|
| RAM (gateway básico) | ~122 kB core + runtime Node.js (~50-100 MB) |
| RAM (Enterprise con dashboard) | 2-4 GB |
| CPU | 1-2 cores (básico) |
| Almacenamiento | Depende de configuración de logs |

#### Pros y Contras

| ✅ Pros | ❌ Contras |
|---|---|
| Cero fricción - solo cambiar baseURL | Dashboard completo depende de SaaS |
| MIT real, código abierto completo | Adquisición por Palo Alto - futuro incierto |
| Comunidad grande (12k ⭐) | No está claro si funciona 100% offline |
| Código muy pequeño (~122 kB core) | Node.js runtime pesa más que alternativas en Rust |

#### Veredicto

**Recomendable con reservas.** Excelente como proxy ligero para monitoreo básico, pero la dependencia del SaaS para el dashboard completo y la adquisición reciente generan incertidumbre. Adecuado si aceptas que la UI depende parcialmente de un servicio externo.

---

### 3.5. OpenLLMetry / Phoenix / AgentOps

#### OpenLLMetry

| Atributo | Valor |
|---|---|
| **Repositorio** | [github.com/openllmetry/openllmetry](https://github.com/openllmetry/openllmetry) |
| **Estrellas** | ~7.2k ⭐ |
| **Licencia** | Apache 2.0 |
| **Tipo** | SDK de trazabilidad basado en OpenTelemetry |
| **¿Es proxy?** | ❌ No. Requiere instrumentación vía SDK. |

#### Phoenix (Arize)

| Atributo | Valor |
|---|---|
| **Repositorio** | [github.com/Arize-AI/phoenix](https://github.com/Arize-AI/phoenix) |
| **Estrellas** | ~10.3k ⭐ |
| **Licencia** | **ELv2** (no OSI-approved - restricciones de uso) |
| **Tipo** | Recolector OTel + UI web |
| **RAM self-hosted** | ~512 MB (relativamente ligero) |
| **¿Es proxy?** | ❌ No. Recolector de telemetría, no intercepta tráfico HTTP. |

#### AgentOps

| Atributo | Valor |
|---|---|
| **Repositorio** | [github.com/AgentOps-AI/agentops](https://github.com/AgentOps-AI/agentops) |
| **Estrellas** | ~5.7k ⭐ |
| **Licencia** | MIT (código abierto) + SaaS (dashboard cloud) |
| **Tipo** | SDK + Cloud backend |
| **¿Es proxy?** | ❌ No. SDK injection. Dashboard completo es SaaS. |

#### ⚠️ Hallazgo Crítico

**Ninguno de los tres es un proxy HTTP.** Todos requieren instrumentación vía SDK en el código de la aplicación. No pueden interceptar tráfico de forma transparente entre agentes y upstreams.

| Proyecto | ¿Proxy? | Modo de captura | RAM | UI propia |
|---|---|---|---|---|
| OpenLLMetry | ❌ SDK | OTel spans | Variable | ❌ (requiere backend OTel) |
| Phoenix | ❌ SDK | OTel + recolector | ~512 MB | ✅ Completa |
| AgentOps | ❌ SDK | Cloud backend | Mínima | ✅ Cloud |

#### Veredicto

**No recomendados** para el caso de uso de middleware transparente. Todos requieren modificar el código de cada agente. Si ya usas OpenTelemetry, OpenLLMetry o Phoenix pueden complementar, pero no reemplazan un proxy de monitoreo.

---

## 4. Comparativa Detallada

### 4.1. Tabla Comparativa General

| Criterio | **LiteLLM** | **Helicone** | **Langfuse** | **Portkey** | **Phoenix** | **OpenLLMetry** |
|---|---|---|---|---|---|---|
| **Tipo** | Proxy HTTP | Proxy + Obs. | SDK Observ. | Proxy HTTP | SDK + UI | SDK OTel |
| **Proxy transparente** | ✅ Sí | ✅ Sí | ❌ No | ✅ Sí | ❌ No | ❌ No |
| **Multi-upstream** | ✅ 100+ | ✅ 100+ | ❌ SDK | ✅ 100+ | ❌ SDK | ❌ SDK |
| **Captura prompts** | ✅ Completa | ✅ Completa | ✅ Completa | ✅ Completa | ✅ Completa | ✅ Spans |
| **WebSockets** | ⚠️ Parcial | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No |
| **UI propia** | ✅ Web | ✅ Web | ✅ Web | ⚠️ SaaS | ✅ Web | ❌ Externa |
| **RAM reposo** | ~359 MB* | ~50-100 MB (GW) | ~25 GB | ~100 MB (GW) | ~512 MB | Variable |
| **RAM pico** | ~12 GB* | ~16 GB (full) | ~25 GB | ~4 GB (full) | ~2 GB | Variable |
| **Latencia overhead** | 7-12 ms | 1-5 ms (GW) | N/A (SDK) | <10 ms | N/A (SDK) | N/A (SDK) |
| **BD externa** | PostgreSQL | PG+ClickHouse | PG+ClickHouse+Redis | Opcional | SQLite | Opcional |
| **Instalación** | pip/docker | docker/npx | docker | npm/docker | docker | pip |
| **Licencia** | MIT | Apache 2.0 | MIT | MIT | ELv2 | Apache 2.0 |
| **Estrellas** | 52.1k | 5.9k | 30.2k | 12.3k | 10.3k | 7.2k |
| **Mantenimiento** | ✅ Activo | ✅ Activo | ✅ Activo | ⚠️ Adq. | ✅ Activo | ✅ Activo |

> \* LiteLLM: ~359 MB RAM idle oficial; ~12 GB bajo carga sostenida según benchmarks independientes. La versión Rust beta (~32 MB) no está estable.

### 4.2. Matriz de Compatibilidad con el Ecosistema Existente

| Aspecto | **LiteLLM** | **Helicone** | **Portkey** |
|---|---|---|---|
| Coexistencia con Headroom | ⚠️ Redundancia de routing | ✅ Proxy en cadena | ✅ Proxy en cadena |
| Context caching sin interferencia | ⚠️ Configurable | ✅ No modifica headers | ⚠️ Verificar |
| Tool-calls intactas | ⚠️ Configurable | ✅ Modo observación | ⚠️ Configurable |
| Codex WebSocket | ❌ No soportado | ❌ No soportado | ❌ No soportado |
| Claude Code CLI | ✅ Cambiar baseURL | ✅ Cambiar baseURL | ✅ Cambiar baseURL |
| OpenCode CLI | ✅ Cambiar baseURL | ✅ Cambiar baseURL | ✅ Cambiar baseURL |
| ACP (Zed/JetBrains) | ❌ No aplica | ❌ No aplica | ❌ No aplica |
| Gobernanza Caveman/Ponytail | No interfiere | No interfiere | No interfiere |

### 4.3. Cumplimiento de Requisitos

| ID | Requisito | LiteLLM | Helicone | Portkey |
|---|---|---|---|---|
| RF-01 | Interceptar tráfico HTTP | ✅ | ✅ | ✅ |
| RF-02 | Capturar prompts completos | ✅ | ✅ | ✅ |
| RF-03 | Registrar metadatos tokens | ✅ | ✅ | ✅ |
| RF-04 | UI web | ✅ | ✅ | ⚠️ Parcial |
| RF-05 | Multi-upstream | ✅ | ✅ | ✅ |
| RF-06 | WebSocket | ⚠️ Parcial | ❌ | ❌ |
| RF-07 | No modificar tool-calls | ✅ Configurable | ✅ | ✅ Configurable |
| RF-08 | No interferir caching | ⚠️ | ✅ | ⚠️ |
| RNF-01 | RAM < 500 MB | ❌ (~12 GB pico) | ✅ (~50 MB GW) | ✅ (~100 MB) |
| RNF-02 | Latencia < 50 ms | ✅ (7-12 ms) | ✅ (1-5 ms) | ✅ (<10 ms) |
| RNF-03 | Sin Docker | ✅ pip | ⚠️ npx/docker | ✅ npm |
| RNF-04 | Mantenimiento activo | ✅ | ✅ | ⚠️ |
| RNF-05 | Licencia permisiva | ✅ MIT | ✅ Apache 2.0 | ✅ MIT |
| RNF-06 | Sin BD externa | ❌ PG obligatorio | ✅ (GW solo) | ✅ Opcional |

---

## 5. Recomendaciones

### 5.1. Recomendación Primaria: **Helicone AI Gateway (Rust) + Observabilidad opcional**

**Justificación técnica:**

1. **Proxy HTTP en Rust** (~50 MB RAM, ~1-5 ms overhead) — cumple con el requisito de ser ligero.
2. **Apache 2.0** — licencia permisiva sin restricciones artificiales.
3. **Dashboard web completo** con búsqueda de prompts, sesiones y análisis de tokens.
4. **Integración en 1 línea** (cambiar `baseURL` en la configuración del agente).
5. **No interfiere con Headroom** — opera como proxy en cadena (Opción A).
6. **Gateway funciona sin base de datos** — despliegue mínimo inmediato.

**Contrapartida:** El stack completo de observabilidad requiere ~16 GB RAM (ClickHouse + PostgreSQL). Para un despliegue mínimo, solo el AI Gateway en Rust más logging a archivo rotativo es suficiente para empezar.

```bash
# Despliegue mínimo: solo AI Gateway (sin base de datos, sin dashboard)
npx @helicone/ai-gateway --port 8788
```

**Estrategia de integración recomendada:**

```mermaid
flowchart LR
    A[Agentes] -->|HTTP| B[Headroom :8787]
    B -->|encadenado| C[Helicone GW :8788]
    C -->|log + proxy| D[Upstreams API]
    C -.->|datos opcionales| E[Dashboard Observabilidad]
```

**Figura 3:** Arquitectura recomendada. Headroom hace caching, Helicone hace logging. Opcionalmente, el dashboard de Helicone consume los datos.

### 5.2. Alternativa Ligera: **Portkey AI Gateway**

**Cuándo elegirla:** Si priorizas la simplicidad de despliegue (npm) por encima de la independencia total del dashboard. Portkey core pesa ~122 kB (más runtime Node.js) y el cambio de configuración es trivial.

**Comando de despliegue:**
```bash
npm install -g @portkey/gateway
portkey-gateway --port 8788
```

**Riesgo:** Adquisición reciente por Palo Alto Networks (mayo 2026) — el roadmap open source post-adquisición es incierto y el dashboard completo depende de SaaS.

### 5.3. Alternativa Futura: **LiteLLM Proxy + versión Rust**

**Cuándo elegirla:** Cuando la versión Rust de LiteLLM esté estable (estimada próximos meses). En ese momento ofrecerá:
- ~32 MB de RAM
- ~0.05 ms de overhead
- 100+ proveedores
- UI web nativa sin PostgreSQL (SQLite)

**Por ahora:** La versión Python es demasiado pesada (~12 GB RAM bajo carga) para el perfil "ligero" requerido.

### 5.4. Proyectos No Recomendados para Este Caso

| Proyecto | Razón de exclusión |
|---|---|
| **Langfuse** | No es proxy; requiere ~25 GB RAM self-hosted |
| **OpenLLMetry** | Solo SDK, no puede interceptar tráfico |
| **Phoenix (Arize)** | No es proxy; licencia ELv2 restrictiva |
| **AgentOps** | SDK injection; dashboard cloud-dependent |
| **Lilypad** | Modo mantenimiento/sin actividad |
| **Gantry** | Abandonado |

---

## 6. Guía de Integración Paso a Paso

### 6.1. Prerrequisitos

- Headroom Proxy operativo en `127.0.0.1:8787`
- Node.js v18+ instalado (para Helicone o Portkey)
- Claude Code CLI configurado con alias `claude` apuntando a Headroom
- Codex CLI operativo con WebSocket Relay vía Headroom
- OpenCode CLI configurado con DeepSeek

### 6.2. Integración con Helicone AI Gateway (Recomendada)

**Paso 1: Desplegar Helicone AI Gateway**

```bash
# Usando npx (recomendado para macOS sin Docker)
npx @helicone/ai-gateway --port 8788
```

Verificar funcionamiento:

```bash
curl http://localhost:8788/v1/health
# Respuesta esperada: {"status":"ok","gateway":"helicone"}
```

**Paso 2: Configurar Headroom para proxy en cadena**

Editar la configuración de Headroom (o la variable de entorno del agente) para que el tráfico pase por el monitor antes de llegar a Headroom:

```
# Estrategia: Agente → Helicone:8788 → Headroom:8787 → Upstream
```

```bash
# En ~/.zshrc: crear alias que apunten a Helicone
alias claude-mon='CLAUDE_CODE_BASE_URL=http://127.0.0.1:8788 claude'

# Opción alternativa: redirigir el upstream de Headroom
# ~/.config/headroom/config.yaml
```

**Paso 3: Configurar Helicone para reenviar a Headroom**

```bash
# Helicone con upstream = Headroom
npx @helicone/ai-gateway --port 8788 --upstream http://127.0.0.1:8787
```

**Paso 4: Verificar captura de tráfico**

```bash
# Probar con Claude Code
claude-mon -p "Di hola mundo" --no-checks

# Verificar que Helicone registró el request
curl http://localhost:8788/v1/logs  # Si el endpoint existe
```

**Paso 5: Verificar no interferencia con tool-calls**

```bash
# Probar una tool-call real
claude-mon -p "Dime la hora actual" --no-checks
# Debe ejecutar el tool correctamente y devolver resultado

# Probar edición de archivos
claude-mon -p "Crea un archivo test.txt con 'hola' dentro" --no-checks
# El archivo debe crearse correctamente
```

### 6.3. Integración con Portkey (Alternativa)

**Paso 1: Instalar Portkey Gateway**

```bash
npm install -g @portkey/gateway
```

**Paso 2: Iniciar el gateway**

```bash
portkey-gateway --port 8788
```

**Paso 3: Configurar agente para usar Portkey**

```bash
# Claude Code
alias claude-mon='CLAUDE_CODE_BASE_URL=http://127.0.0.1:8788 claude'

# OpenCode
# Editar ~/.config/opencode/opencode.jsonc:
```

```jsonc
// ~/.config/opencode/opencode.jsonc
{
  "provider": "custom",
  "baseUrl": "http://127.0.0.1:8788/v1",
  "model": "deepseek-chat",
  "apiKey": "sk-..." // Tu API key de DeepSeek
}
```

### 6.4. Consideraciones para el Ecosistema Completo

**Claude Code:**
```bash
# Alias para usar con monitoreo
alias claude='CLAUDE_CODE_BASE_URL=http://127.0.0.1:8787 claude'    # Sin monitoreo (Headroom directo)
alias claude-mon='CLAUDE_CODE_BASE_URL=http://127.0.0.1:8788 claude' # Con monitoreo (Helicone + Headroom)
```

**OpenCode:** Cambiar `baseUrl` en `opencode.jsonc` apuntando al monitor (puerto 8788 en lugar de directo a DeepSeek):

```jsonc
// ~/.config/opencode/opencode.jsonc
{
  "provider": "custom",
  "baseUrl": "http://127.0.0.1:8788/v1",
  "model": "deepseek-chat",
  "apiKey": "sk-..."
}
```

> 💡 **Tip:** En `~/.zshrc`, definir un alias de emergencia por agente para poder desactivar el monitoreo rápidamente si algo falla: `alias claude-direct='CLAUDE_CODE_BASE_URL=http://127.0.0.1:8787 claude'`.

---

## 7. Limitaciones y Advertencias

### 7.1. Impacto en Latencia

| Proyecto | Overhead estimado | Impacto en experiencia |
|---|---|---|
| Helicone AI Gateway (Rust) | ~1-5 ms | Imperceptible |
| Portkey Gateway (Node.js) | ~5-10 ms | Imperceptible |
| LiteLLM (Python) | ~7-12 ms | Perceptible en streaming |
| Helicone full stack | ~1-50 ms | Perceptible en requests cortas |

### 7.2. Almacenamiento de Logs

| Proyecto | Almacenamiento estimado por request | Gestión de disco |
|---|---|---|
| Helicone | ~2-10 KB (según tamaño del prompt) | ClickHouse compresión automática |
| Portkey | ~1-5 KB | Archivos rotativos configurables |
| LiteLLM | ~2-10 KB | PostgreSQL con TTL configurable |

> ⚠️ **Advertencia:** Para uso intensivo (1000+ requests/día con prompts de 10K+ tokens), el almacenamiento puede alcanzar varios GB/mes. Configurar retención (TTL) y rotación de logs desde el inicio. Un prompt de Claude Code con system prompt + archivos de contexto puede superar fácilmente los 100 KB por request.

### 7.3. Compatibilidad con WebSocket (Codex CLI)

**Ninguno de los proyectos evaluados soporta WebSocket de forma nativa para monitoreo de Codex CLI.** Esto significa que el tráfico de Codex (que usa conexiones WebSocket persistentes) **no será capturado** por el middleware HTTP.

**Soluciones alternativas para monitorear Codex:**

1. **Logging nativo de Headroom:** Si Headroom v0.28.0 expone logs de los frames WebSocket, se pueden redirigir a un archivo para análisis post-hoc.
2. **codex-helper:** Herramienta comunitaria que actúa como relay WebSocket local con TUI de logging.
3. **LocalAI MITM proxy:** Puede interceptar tráfico WebSocket con logging, pero añade complejidad operativa.
4. **Aceptar la limitación:** Monitorear solo Claude Code y OpenCode (HTTP), documentando que Codex queda fuera del alcance.

```bash
# Ejemplo conceptual: relay WebSocket con logging (no verificado)
# Usar WS_PROXY si Codex CLI v0.104.0+ lo soporta
WS_PROXY=ws://localhost:8788 codex
```

### 7.4. ACP (Agent Client Protocol) en Zed/JetBrains

El protocolo ACP usado por Zed y JetBrains opera sobre **JSON-RPC local vía stdin/stdout** del subproceso del agente CLI. Esto significa que:

- ❌ Un proxy HTTP externo **no puede interceptar** el tráfico ACP de forma directa.
- ✅ El monitoreo debe hacerse a nivel del agente CLI (Claude Code, Codex), no del IDE.
- ✅ Si el agente CLI ya está monitorizado (porque su tráfico HTTP/WS pasa por el proxy), el contenido de los prompts se captura igualmente.
- ⚠️ La comunicación ACP transporta principalmente comandos de edición (tool-calls locales), no necesariamente prompts completos. El prompt viaja desde el agente al LLM vía HTTP/WS, que sí es interceptable.

> **Conclusión:** No es necesario modificar ni monitorizar el protocolo ACP directamente. Monitorizando el tráfico del agente CLI hacia los upstreams, se captura todo el contenido relevante.

### 7.5. Otras Limitaciones

| Limitación | Detalle |
|---|---|
| **Cache de contexto** | El monitor podría invalidar cachés si modifica headers. Verificar modo "passthrough" en cada proyecto. |
| **Rate limiting** | Algunos monitores añaden su propio rate limiting, que podría chocar con el de Headroom. |
| **Tokens de cache** | La métrica de `cache_creation_input_tokens` y `cache_read_input_tokens` debe propagarse correctamente. |
| **Redundancia** | Si Headroom ya provee caching y routing, LiteLLM o Portkey añaden funcionalidad redundante. |
| **Seguridad** | El monitor almacena prompts completos (potencialmente con datos sensibles). Asegurar cifrado en reposo. |

---

## 8. Anexos

### 8.1. Configuraciones de Ejemplo

#### Helicone AI Gateway como daemon launchd (macOS)

```xml
<!-- ~/Library/LaunchAgents/com.herandro.helicone-gateway.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.herandro.helicone-gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/npx</string>
        <string>@helicone/ai-gateway</string>
        <string>--port</string>
        <string>8788</string>
        <string>--upstream</string>
        <string>http://127.0.0.1:8787</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>WorkingDirectory</key>
    <string>/tmp</string>
    <key>StandardOutPath</key>
    <string>/tmp/helicone-gateway.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/helicone-gateway.err</string>
</dict>
</plist>
```

```bash
# Cargar el servicio
launchctl load ~/Library/LaunchAgents/com.herandro.helicone-gateway.plist

# Verificar estado
launchctl list | grep helicone

# Ver logs
tail -f /tmp/helicone-gateway.log
```

#### LiteLLM Proxy Configuración Mínima

```yaml
# ~/.config/litellm/config.yaml
general_settings:
  master_key: "sk-litellm-master-key"  # Cambiar en producción

litellm_settings:
  drop_params: true
  set_verbose: false
  store_prompts_in_spend_logs: true  # HABILITAR captura de prompts
  default_fallbacks: []
  num_retries: 0

model_list:
  - model_name: claude-sonnet-4
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: "${ANTHROPIC_API_KEY}"
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: "${OPENAI_API_KEY}"
  - model_name: deepseek-chat
    litellm_params:
      model: openai/deepseek-chat
      api_key: "${DEEPSEEK_API_KEY}"
      api_base: "https://api.deepseek.com/v1"
```

### 8.2. Comandos de Verificación Rápida

```bash
# Verificar que el monitor está operativo
curl -s -o /dev/null -w "%{http_code}" http://localhost:8788/v1/health
# Debe devolver 200

# Verificar latencia del monitor
time curl -s -X POST http://localhost:8788/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-api-key: test" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"test"}]}' \
  -o /dev/null -w "Total: %{time_total}s\n"

# Verificar que Headroom sigue funcionando (sin monitor)
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:8787/v1/health

# Verificar que las tool-calls funcionan (usar Claude Code)
claude-mon -p "Ejecuta: ls -la /tmp" --no-checks

# Verificar logs del monitor
tail -n 50 /tmp/helicone-gateway.log
```

### 8.3. Enlaces a Repositorios y Documentación

| Proyecto | Repositorio | Documentación |
|---|---|---|
| **Helicone** | [github.com/Helicone/helicone](https://github.com/Helicone/helicone) | [docs.helicone.ai](https://docs.helicone.ai) |
| **Portkey** | [github.com/Portkey-AI/gateway](https://github.com/Portkey-AI/gateway) | [portkey.ai/docs](https://portkey.ai/docs) |
| **LiteLLM** | [github.com/BerriAI/litellm](https://github.com/BerriAI/litellm) | [docs.litellm.ai](https://docs.litellm.ai) |
| **Langfuse** | [github.com/langfuse/langfuse](https://github.com/langfuse/langfuse) | [langfuse.com/docs](https://langfuse.com/docs) |
| **Phoenix** | [github.com/Arize-AI/phoenix](https://github.com/Arize-AI/phoenix) | [docs.arize.com](https://docs.arize.com) |
| **OpenLLMetry** | [github.com/openllmetry/openllmetry](https://github.com/openllmetry/openllmetry) | [openllmetry.com](https://openllmetry.com) |
| **AgentOps** | [github.com/AgentOps-AI/agentops](https://github.com/AgentOps-AI/agentops) | [agentops.ai/docs](https://agentops.ai/docs) |

### 8.4. Glosario de Términos

| Término | Definición |
|---|---|
| **ACP** | Agent Client Protocol. Protocolo JSON-RPC para comunicación entre IDE y agente CLI (Zed, JetBrains). Opera sobre stdin/stdout. |
| **Headroom Proxy** | Proxy local de optimización de contexto para LLMs. Opera en modo cache, redirigiendo tráfico a múltiples upstreams. |
| **Proxy en cadena** | Configuración donde un proxy redirige el tráfico a otro proxy (ej: Agente → Headroom → Monitor → Upstream). |
| **SDK injection** | Método de instrumentación que requiere modificar el código fuente para agregar tracing/monitoreo. |
| **Tool-call** | Llamada a función/herramienta realizada por el LLM. Headroom opera con `--intercept-tool-results = OFF` para no modificarlas. |
| **Context caching** | Mecanismo de Headroom para reutilizar contexto entre requests, reduciendo costos y latencia. |
| **Upstream** | API de proveedor de LLM (Anthropic, OpenAI, DeepSeek) a la que se envía el tráfico. |
| **JSON-RPC** | Protocolo de llamada a procedimiento remoto basado en JSON. Usado por ACP. |
| **Prefix Caching** | Caché de prefijos de prompts en el servidor (DeepSeek lo ofrece nativamente). |
| **TTL** | Time-To-Live. Período de retención de datos antes de ser eliminados automáticamente. |

---

> **Fin del documento.**  
> Versión 1.0 — Investigación y redacción completada.  
> Fuentes consultadas: repositorios oficiales de cada proyecto, documentación técnica, análisis de benchmarks independientes, changelogs y reportes de incidentes de seguridad. Para verificar información actualizada, consultar las URLs provistas en la sección 8.3.