No se encontró conocimiento previo. Procedo a generar el plan de investigación completo basado en el contexto detallado que has proporcionado. --- ## Plan de Investigación: Proyectos Open Source para Trackear Consumo de Tokens en Agentes de IA --- ### 1. Objetivo de la documentación **Título del documento:** *Sistemas de Monitoreo y Trazabilidad de Tokens para Agentes de IA: Evaluación de Proyectos Open Source* **Qué cubre:** El documento evaluará, comparará y recomendará proyectos open source que permitan: - **Trackear el consumo de tokens** enviados y recibidos por agentes de IA (Claude Code CLI, Codex CLI, OpenCode CLI). - **Actuar como middleware** entre el agente y el upstream (API), capturando los *prompts completos* (system prompts + contexto + herramientas + respuesta del modelo). - **Detectar fugas de contexto o textos inesperados** enviados al agente. - **Visualizar en una UI** el historial de conversaciones, tokens consumidos por tipo (input/output/cache), y contenido de cada request. - **Coexistir sin conflictos** con infraestructura de optimización existente (Headroom Proxy, codebase-memory-mcp, reglas de gobernanza Caveman Lite/Ponytail). - **Funcionar en modo no invasivo** (no interceptar tool-calls ni romper flujos existentes). **Para quién:** Desarrolladores avanzados y arquitectos de IA que ya operan un ecosistema multi-agente (Claude Code, Codex, OpenCode) con múltiples upstreams (OpenAI, Anthropic, DeepSeek) y desean auditoría, transparencia y depuración del tráfico de tokens sin degradar el rendimiento. --- ### 2. Audiencia y nivel técnico | Aspecto | Detalle | |---|---| | **Perfil principal** | Ingeniero de software senior / Arquitecto de IA / DevOps de agentes | | **Conocimientos previos esperados** | CLI de agentes (Claude Code, Codex, OpenCode), proxies HTTP/WebSocket, conceptos de contexto LLM (system prompt, tool-calls, cache), JSON, APIs REST | | **Familiaridad con** | Headroom Proxy, codebase-memory-mcp, gestión de procesos con launchd, configuración de upstreams múltiples | | **No requiere** | Conocimientos de frontend o UI, ni de administración de redes complejas | | **Lectura complementaria** | Documentación oficial de Claude Code, Codex CLI, OpenCode CLI, Headroom Proxy | --- ### 3. Alcance y versiones **Versiones / contextos cubiertos:** | Herramienta / Componente | Versión / Contexto | |---|---| | **Claude Code CLI** | Versión actual (CLI oficial de Anthropic) | | **Codex CLI** | Versión actual (modo `auth_mode = chatgpt`, WebSocket Relay) | | **OpenCode CLI** | Versión actual (configuración con DeepSeek como upstream) | | **Headroom Proxy** | v0.28.0, modo `--mode cache`, puerto `127.0.0.1:8787`, multi-upstream (OpenAI/Anthropic) | | **codebase-memory-mcp** | Servicio en puerto 9749 | | **IDE integration** | Zed, JetBrains (vía ACP - Agent Communication Protocol) | | **Sistema operativo** | macOS (gestión con launchd) | | **Proyectos a evaluar** | Mínimo 5-7 proyectos open source candidatos | **Qué queda fuera:** - Proyectos comerciales / SaaS de pago (solo open source). - Soluciones que requieran Docker o contenedores pesados (se prefiere binario nativo o instalación vía Homebrew). - Herramientas que modifiquen los prompts (solo observación/auditoría, no alteración). - Plataformas de monitoreo completo de infraestructura (Datadog, Grafana) — solo el middleware específico para tokens de LLM. **Criterios de exclusión explícitos:** - Proyectos que consuman >500 MB de RAM en reposo. - Proyectos que requieran Node.js con dependencias pesadas (>50 MB de `node_modules`). - Proyectos que no tengan mantenimiento activo (último commit >6 meses). - Proyectos que intercepten o modifiquen tool-calls de forma predeterminada. --- ### 4. Estructura del documento (plan de secciones) ``` DOCUMENTACIÓN TÉCNICA: SISTEMAS DE MONITOREO DE TOKENS PARA AGENTES ==================================================================== 1. INTRODUCCIÓN - Contexto del ecosistema actual (Headroom Proxy, multi-upstream, gobernanza) - Problema a resolver: trazabilidad del tráfico de agentes sin afectar rendimiento - Requisitos funcionales y no funcionales 2. ARQUITECTURA DE REFERENCIA DEL ECOSISTEMA EXISTENTE - Diagrama Mermaid de flujo actual (Agentes → Headroom Proxy → Upstreams) - Punto de inserción del middleware de monitoreo - Restricciones de integración (no romper tool-calls, no afectar cache) 3. CATÁLOGO DE PROYECTOS OPEN SOURCE EVALUADOS (Por cada proyecto:) 3.1. Nombre, repositorio, licencia, linguaje/stack 3.2. Funcionalidad principal 3.3. Modo de despliegue (binario, pip, npm, brew) 3.4. Consumo de recursos (RAM, CPU, almacenamiento) 3.5. Compatibilidad con el ecosistema existente 3.6. Pros y contras específicos para este caso de uso 3.7. Capturas de UI (si aplica, descripción textual) 4. COMPARATIVA DETALLADA - Tabla comparativa con ejes: * Tipo de middleware (proxy HTTP, SDK, MCP server) * Compatibilidad con multi-upstream * Capacidad de ver prompts completos * UI disponible (web, TUI, CLI) * Consumo de recursos (medido) * Mantenimiento activo * Compatibilidad con ACP (Agent Communication Protocol) 5. RECOMENDACIONES - Proyecto primario recomendado - Alternativas según perfil (ligero, feature-rich, etc.) - Guía de integración paso a paso con el ecosistema actual 6. GUÍA DE INTEGRACIÓN PASO A PASO - Instalación (Homebrew / binario / pip) - Configuración como middleware en Headroom Proxy (o reemplazo parcial) - Verificación de no interferencia con tool-calls - Configuración de upstreams (OpenAI, Anthropic, DeepSeek) - Habilitación de UI - Pruebas con Claude Code, Codex, OpenCode - Verificación con Zed / JetBrains (ACP) 7. LIMITACIONES Y ADVERTENCIAS - Impacto en latencia - Almacenamiento de logs (gestión de disco) - Compatibilidad con WebSocket (Codex) - Modificaciones futuras del protocolo ACP 8. ANEXOS - Configuraciones de ejemplo (JSON/YAML/TOML) - Comandos de instalación y verificación - Enlaces a repositorios y documentación oficial - Glosario de términos ``` --- ### 5. Aspectos técnicos a investigar Cada uno requiere **búsqueda web** activa (no síntesis de conocimiento interno): #### 5.1. Proyectos candidatos a evaluar (lista preliminar) | Proyecto | Por qué es candidato | Lo que necesitamos verificar | |---|---|---| | **Lilypad** | Proxy LLM con caché y monitoreo | ¿Tiene UI de trazabilidad? ¿Consumo ligero? | | **LiteLLM Proxy** | Proxy multi-proveedor con logging | ¿Demasiado pesado? ¿Soporta WebSocket? | | **OpenLLMetry** | Trazabilidad estilo OpenTelemetry para LLMs | ¿Requiere infraestructura externa? | | **Helicone** (self-host) | Plataforma de observabilidad LLM | ¿Es mantenible self-hosted? ¿Consumo? | | **Langfuse** | Open source observability + tracing | ¿Pesado para estar en local? | | **Phoenix (Arize)** | Tracing y evaluación de LLMs | ¿Requiere mucho overhead? | | **Ollama** (no aplica) | No es middleware de monitoreo | Descartado, pero confirmar | | **AgentOps** | Monitoreo de agentes | ¿Open source real? ¿Licencia? | | **Portkey** (self-host) | Gateway + observabilidad | ¿Versión open source completa? | | **Braintrust** | Evaluación y logging | ¿Open source? | #### 5.2. Aspectos específicos a investigar por proyecto Para cada proyecto, investigar: 1. **Stack tecnológico** - Lenguaje de implementación - Dependencias runtime - Modo de instalación (brew, pip, npm, binario, docker) 2. **Modo de operación como middleware** - ¿Actúa como proxy HTTP reverse? - ¿Requiere modificar la URL del endpoint? - ¿Soporta múltiples upstreams? - ¿Maneja WebSockets (necesario para Codex)? 3. **Capacidad de captura de tráfico** - ¿Captura el prompt completo (system + user + tools + response)? - ¿Almacena el historial de requests? - ¿Permite buscar/filtrar por contenido? 4. **Métrica de consumo de recursos** - RAM en idle - RAM en pico - CPU promedio - Almacenamiento en disco (por request) 5. **UI / visualización** - Tipo de UI (web, TUI, dashboard local, API-only) - ¿Requiere base de datos externa (Postgres, SQLite)? - ¿Requiere servidor web separado? 6. **Compatibilidad con el ecosistema** - ¿Interfiere con context caching de Headroom? - ¿Rompe tool-calls? - ¿Soporta formato de API Anthropic, OpenAI, DeepSeek? - ¿Soporta ACP (Agent Communication Protocol)? 7. **Mantenimiento y comunidad** - Último commit - Número de estrellas/contribuidores - Licencia - Roadmap público #### 5.3. Investigación técnica complementaria - **ACP (Agent Communication Protocol):** Estado actual del protocolo, cómo Zed y JetBrains lo implementan, si un proxy HTTP puede interceptarlo sin romperlo. - **WebSocket Relay (Codex):** Cómo capturar tráfico WebSocket para logging sin afectar la conexión. - **Headroom Proxy internals:** Si tiene hooks o plugins para logging externo (verificar en docs de headroom v0.28.0). - **Compatibilidad con herramientas de quality gates (ruff, biome, semgrep, gitleaks):** Si el middleware puede ejecutar hooks de validación sobre los prompts antes de enviarlos. #### 5.4. Lo que NO requiere investigación (síntesis directa) - Descripción general del ecosistema actual (el usuario ya lo detalló). - Configuración de Headroom Proxy (ya documentado por el usuario). - Reglas de gobernanza Caveman Lite y Ponytail (ya definidas por el usuario). - codebase-memory-mcp (ya operativo en puerto 9749). --- ### 6. Convenciones | Aspecto | Convención | |---|---| | **Formato del documento** | Markdown (.md) con estructura jerárquica (##, ###, ####) | | **Código** | Bloques con sintaxis resaltada: `bash`, `json`, `yaml`, `python`, `typescript` | | **Diagramas** | Mermaid (```mermaid) para diagramas de arquitectura y flujo | | **Tablas** | Formato pipe (`\|`) con alineación consistente | | **Notas importantes** | `> **Nota:**` en bloque de cita | | **Advertencias** | `> ⚠️ **Advertencia:**` para riesgos o limitaciones | | **Ejemplos de éxito** | `> ✅` para configuraciones verificadas | | **Ejemplos de error** | `> ❌` para configuraciones no recomendadas | | **Nombres de proyectos** | En **negrita** la primera vez que aparecen | | **Comandos** | En `código inline` | | **Unidades** | MB, GB, ms (con espacio: `500 MB`, `120 ms`) | | **Versiones** | vX.Y.Z (ej: `v0.28.0`) | | **Idioma** | Español para prosa, inglés para nombres técnicos y código | | **Tono** | Objetivo, técnico, sin opiniones personales ni adjetivos subjetivos | --- ### 7. Entregable esperado | Aspecto | Detalle | |---|---| | **Formato** | Archivo Markdown (.md) | | **Extensión estimada** | 15-25 páginas en renderizado (~3000-5000 palabras) | | **Estructura** | 8 secciones principales + anexos (según punto 4) | | **Diagramas** | Mínimo 2 diagramas Mermaid (arquitectura actual + punto de inserción del middleware) | | **Tablas comparativas** | Mínimo 2 tablas (proyectos evaluados + comparativa detallada) | | **Ejemplos de código** | Bloques de configuración para cada proyecto evaluado | | **Recomendación final** | Una recomendación primaria + 2 alternativas con justificación técnica | | **Guía de integración** | Paso a paso verificable (se puede ejecutar sin ambigüedad) | | **Fecha límite** | A determinar por el equipo | **Criterios de calidad del entregable:** - Cada proyecto evaluado debe tener al menos 3 fuentes verificables (repo, docs, benchmark). - Las mediciones de recursos deben ser específicas, no genéricas (ej: "~150 MB RSS en idle medido en macOS M4"). - Cualquier advertencia de compatibilidad debe estar respaldada por evidencia técnica. - El documento debe ser autónomo: un lector con los prerequisitos indicados puede implementar la solución sin necesidad de consultar fuentes externas. --- **Fin del plan.** ¿Procedo con la investigación web de los proyectos candidatos para redactar el documento técnico completo?