🧬 TUNIX Blueprint

1 Arquitectura general

TUNIX es un solo agente con 3 modos:

• TUNIX Talk (Gemini 2.5 Flash Live) — voz por celular/PWA con audífonos
• TUNIX Búnker (Claude Sonnet/Haiku/Opus via OAuth Max) — container VPS always-on
• TUNIX Code (Claude Code en VS Code) — sesiones largas de ingeniería

2 Instant Layer — respuestas <2s

Capa de tools agregadoras pre-cocinadas que Gemini llama directo sin delegar. Permiten respuestas instantáneas a preguntas frecuentes.

3 etapas de evolución (de lo simple a lo brutal)

Tools Instant Layer activas hoy

Candidatas próximas (cuando data telemetría lo justifique)

• briefing_today_snapshot — agenda + reuniones + reminders + clima + estado emocional en 1 frase
• holdings_health_snapshot — KPIs Emabel + TensorMed (clientes activos, propuestas, MRR)
• daily_focus_snapshot — top 3 prioridades del día con contexto reciente
• wsp_pulse_snapshot — actividad WSP 24h por brand (in/out/urgentes)

3 Whitelist Gemini directo (21 tools)

Tools que Gemini puede invocar SIN delegar a Haiku/Sonnet/Opus. Definidas en api/gemini-live-config.js constante GEMINI_DIRECT_WHITELIST.

4 Bypass pre-execute (15 patterns)

Cuando Gemini delega a quick_via_haiku o quick_via_sonnet, el backend intercepta primero con regex matching y ejecuta la tool Forge ANTES de llamar al modelo. El resultado va cocinado en el prompt. Modelo solo verbaliza.

Cómo funciona internamente

Patrones activos

• Drive: drive_search, drive_list_folder, drive_read
• Gmail: gmail_search, gmail_read
• Memoria: recall, memory_librarian, deep_search, forge_global_search, search_entities, search_talk_history
• Queries: query_reminders, query_meetings_today, query_tasks

5 Memoria conversacional — 3 capas

Estática (canon documental):

• read_memory(slug) — lee memoria específica de forge_memory
• list_memories() — lista todas disponibles
• recall_lessons(query) — lecciones consolidadas por REM agent nocturno
• forge_global_search(query) — full-text 30+ tablas con embeddings

6 MCP forge en Búnker (30 tools)

Catálogo consolidado de tools que Sonnet/Haiku/Opus pueden invocar nativo via MCP server stdio (scripts/tunix-claude-agent/forge-tools-mcp.mjs). Refactorizado 64→30 tras análisis Opus 26-may.

Familias consolidadas

7 Cuándo delega Gemini (framework 7 criterios)

Para que una tool nueva entre al whitelist directo Gemini, debe cumplir TODOS los 7 criterios:

1. Determinístico — cero-args o args triviales
2. Read-only — nunca escribir/borrar/enviar a terceros
3. Fail-safe — error claro y recuperable
4. Latencia <2s típica
5. Verbalizable directo — sin razonamiento extra
6. Alta frecuencia — ≥5 calls/sem proyectadas
7. NO requiere creatividad — no es redactar/analizar/sintetizar

Si una tool falla un criterio → delegar a Sonnet/Opus/Haiku.

Documentado en _core/feedback_gemini_delegate_framework.md.

8 Cheatsheet — Cómo preguntarle a TUNIX por voz

🚀 Respuestas instantáneas (1-2s, Instant Layer)

⚡ Respuestas rápidas (~200ms, cero-args)

🧠 Memoria conversacional (1.5-6s)

🟡 Delegación a Haiku/Sonnet (3-15s)

🔴 Análisis profundo (30-90s, Opus)

🤝 Modo Reunión (3 capas progresivas)

9 Sistema de aprobaciones (panel rojo)

Decisión 25-may: aprobaciones destructivas NUNCA por voz (riesgo "sí" accidental). Siempre por botón manual rojo en pantalla.

• Tabla tunix_approval_requests (UUID, action, why, plan, status, TTL 5min)
• RPCs tunix_approval_decide(token, approved)
• Endpoint /api/tunix-approval
• Bridge poller detecta metadata.kind=approval_request → muestra panel rojo en /talk
• Tool respond_to_approval(request_token, approved) en whitelist Gemini

Flujo típico:

Búnker: bunker_request_approval.sh "git push --force" "fix bug" "plan"
        ↓ insert en tunix_bridge_queue
TUNIX Talk: voz Aoede lee el pedido informativo + muestra panel rojo
        ↓ Patricio tap APROBAR
respond_to_approval → tunix_approval_decide → script Búnker exit 0
Búnker hace el push.

10 Telemetría path

Tabla forge_tunix_tool_audit + columna path registra cómo se ejecutó cada tool:

Query útil para análisis:

SELECT path, count(*) AS calls, ROUND(AVG(duration_ms)::numeric, 0) AS avg_ms
FROM forge_tunix_tool_audit
WHERE created_at > now() - interval '7 days'
GROUP BY path ORDER BY calls DESC;

11 Sistema IDEAL vs estado ACTUAL

Comparación brutal honesta por área. Objetivo: que TUNIX trabaje en cada dimensión al estándar "espectacular" sin latencia. Verde = en el ideal · Amarillo = aceptable, mejorable · Rojo = gap importante.

A. Latencias objetivo

B. Catálogo de tools

C. Telemetría y observabilidad

D. Memoria y embeddings

E. Modo Reunión

F. APK Android (Capacitor)

G. Voice identity

H. Búnker MCP (post-fix 26-may)

12 Roadmap de evolución (por prioridad)

🔴 P0 — esta semana (alto impacto, esfuerzo bajo)

1. Entrenar voice profile Patricio (60s) → diarización por nombre activa en próxima reunión. acción tuya
2. Brief profundo Sebastián con Opus para reunión 7 PM. esperando OK
3. Validar fixes en uso real: reunión Seba hoy + identidad directa + Instant Layer.
4. Entrenar voice profile Sebastián cuando llegue (1 min).

🟡 P1 — próximas 2 semanas

1. APK rebuild WakeLock nativo cuando GitHub Actions vuelva (refuerzo bonus, frontend ya cubre).
2. Crear primer materialized snapshot (Etapa 2 Instant Layer):
   • Tabla forge_instant_snapshots(slug, data, refreshed_at, ttl_min)
   • Cron 5min: holdings_health_snapshot (KPIs Emabel + TensorMed)
3. Tool retrieval con Haiku classifier — clasificador rápido decide qué grupo cargar al MCP → catálogo efectivo Sonnet/Opus baja de 30 a 8-10 tools por turno. Reduce 3-4s primer token.
4. Telemetría P50/P95 por tool + per-path: agregar columna p50_ms, p95_ms a tablas o vista materializada.
5. Aumentar bypass patterns: agregar 5-10 nuevos basados en datos de delegate frecuentes.

🟢 P2 — 1-2 meses

1. Pre-cocción narrativa Sonnet (Etapa 3 Instant Layer): cron cada hora genera narrativas listas (briefing matutino, estado holdings, focus diario). Gemini solo lee.
2. Hook auto-grabación memoria: TUNIX detecta lección/preferencia importante → auto-save a forge_memory sin pedir.
3. Outbox queue terceros approval batch: agrupar mensajes WSP/email pendientes en una revisión visual.
4. Briefing matutino con narrativa pre-cocinada: cron Sonnet 06:25 genera texto, Gemini lo lee 06:28.
5. Voice profiles 3-5 contactos clave: Sebastián, Nicolás Luna, otros frecuentes.

🔵 P3 — 3-6 meses (estratégico)

1. TUNIX Búnker 90% paridad con Code: Opus profundo always-on en VPS con todas las capacidades de Claude Code (memoria viva, sub-agentes, etc).
2. Voice Lab dashboard: A/B testing voces, sliders calidad, cloning Patricio mejor.
3. Diarización avanzada Picovoice Eagle: alternativa más robusta a WeSpeaker on-device.
4. Tool composition workflows reales: DAGs predefinidos para flows recurrentes (ej. "preparar reunión cliente X").
5. Agents-as-tools selectivos: research_agent, code_review_agent, content_writer_agent — solo para casos complejos puntuales.

13 Métricas clave a monitorear

Queries SQL útiles para revisar el pulso del sistema. Correlas semanalmente en Supabase SQL Editor.

Salud general (1 vista panorámica)

SELECT
  path,
  count(*) AS calls,
  ROUND(AVG(duration_ms)::numeric, 0) AS avg_ms,
  ROUND(percentile_cont(0.5) WITHIN GROUP (ORDER BY duration_ms)::numeric, 0) AS p50_ms,
  ROUND(percentile_cont(0.95) WITHIN GROUP (ORDER BY duration_ms)::numeric, 0) AS p95_ms,
  ROUND(100.0 * count(*) FILTER (WHERE success=false) / count(*), 1) AS fail_pct
FROM forge_tunix_tool_audit
WHERE created_at > now() - interval '7 days'
GROUP BY path
ORDER BY calls DESC;

Top tools más usadas (detecta candidatos a bypass/instant)

SELECT tool_name, count(*) AS calls,
  ROUND(AVG(duration_ms)::numeric, 0) AS avg_ms,
  count(*) FILTER (WHERE path='direct') AS direct,
  count(*) FILTER (WHERE path='bypass') AS bypass,
  count(*) FILTER (WHERE path='mcp') AS mcp,
  count(*) FILTER (WHERE path='cache') AS cache
FROM forge_tunix_tool_audit
WHERE created_at > now() - interval '7 days'
GROUP BY tool_name
ORDER BY calls DESC LIMIT 20;

Tools con fail rate alto (intervenir)

SELECT tool_name, count(*) AS calls,
  count(*) FILTER (WHERE success=false) AS fails,
  ROUND(100.0 * count(*) FILTER (WHERE success=false) / count(*), 1) AS fail_pct
FROM forge_tunix_tool_audit
WHERE created_at > now() - interval '7 days'
GROUP BY tool_name
HAVING count(*) FILTER (WHERE success=false) > 0
   AND count(*) >= 3
ORDER BY fail_pct DESC;

Cache hit rate por tool (subir hits = bajar latencia)

SELECT tool_name,
  count(*) FILTER (WHERE path='cache') AS hits,
  count(*) FILTER (WHERE path!='cache') AS misses,
  ROUND(100.0 * count(*) FILTER (WHERE path='cache') / count(*), 1) AS hit_pct
FROM forge_tunix_tool_audit
WHERE created_at > now() - interval '7 days'
GROUP BY tool_name
HAVING count(*) > 5
ORDER BY hit_pct DESC;

Latencia por modelo brain delegate

SELECT
  CASE
    WHEN tool_name = 'quick_via_haiku' THEN 'Haiku'
    WHEN tool_name = 'quick_via_sonnet' THEN 'Sonnet'
    WHEN tool_name = 'delegate_to_claude_max' THEN 'Opus'
    ELSE 'Other'
  END AS model,
  count(*) AS calls,
  ROUND(AVG(duration_ms)::numeric, 0) AS avg_ms,
  ROUND(percentile_cont(0.95) WITHIN GROUP (ORDER BY duration_ms)::numeric, 0) AS p95_ms
FROM forge_tunix_tool_audit
WHERE created_at > now() - interval '7 days'
  AND tool_name IN ('quick_via_haiku','quick_via_sonnet','delegate_to_claude_max')
GROUP BY model ORDER BY calls DESC;

14 Anti-patrones a evitar

Cosas que romperían la eficiencia del sistema. Revisar antes de cualquier cambio estructural.

15 💰 Costos en vivo + ahorros vs OpenAI

Cálculo automático con tu data real de forge_tunix_talk_sessions + forge_tunix_tool_audit. Pricing 2026 verificable.

💡 Análisis: por qué Gemini Live es la mejor decisión

OpenAI cobra audio nativo a precio premium (procesa speech-to-speech end-to-end). Gemini Live Native Audio es misma arquitectura speech-to-speech pero ~20x más barato porque Google está agresivo capturando market share contra OpenAI.

📋 Pricing 2026 comparado

🧱 Stack TUNIX completo · costos mensuales

💎 Ahorro real con tu uso ACTUAL

📈 Proyecciones si escalás Talk

⚖️ Claude Pro $100 break-even

🔔 Alertas automáticas activadas

• Resumen mensual: día 1 de cada mes a las 9 AM Chile → push notif con costos del mes anterior.
• Alert OAuth Max subutilizado: cada lunes 10 AM → si utilización < 70%, push notif sugiriendo ajustar.

🛠️ SQL útil para auditar manualmente

-- Costo Gemini Live aproximado últimos 30d
SELECT
  count(*) AS sessions,
  ROUND(SUM(duration_sec)/60.0, 1) AS minutos_voz,
  ROUND(SUM(duration_sec) * 100 * 0.50 / 1e6, 2) AS cost_input_audio_usd,
  ROUND(SUM(duration_sec) * 70 * 2.00 / 1e6, 2) AS cost_output_audio_usd
FROM forge_tunix_talk_sessions
WHERE started_at > now() - interval '30 days' AND duration_sec > 30;

-- Anthropic equivalent sin Max
SELECT
  count(*) FILTER (WHERE tool_name='quick_via_haiku') * 0.10 AS haiku_usd,
  count(*) FILTER (WHERE tool_name='quick_via_sonnet') * 0.30 AS sonnet_usd,
  count(*) FILTER (WHERE tool_name='delegate_to_claude_max') * 1.50 AS opus_usd
FROM forge_tunix_tool_audit
WHERE created_at > now() - interval '30 days';

16 🚀 Plan para llenar Claude Pro $100/mes con agentes paralelos

Patricio: "necesito crear más proyectos paralelos para llegar al tope del Pro, que vaya orquestando y dirigiendo".

Objetivo: pasar de **~30-50% utilización** a **80-100%**, generando valor real con cada llamada Opus/Sonnet en background. Si llenás el Pro consistentemente 3 meses seguidos, conviene migrar a plan Team $200.

📋 10 proyectos paralelos automatizables

Cada uno suma ~$8-20/mes equivalente. Eligiendo 5-7 llegás al tope del Pro.

🎯 Implementación por prioridad

🎛️ Cómo controlar la utilización

• Toggle en cada proyecto para activar/pausar individualmente (ej. "pausar code review esta semana porque no toco código")
• Push notif resumen diario de qué generaron los agentes y cuánto equivalente $$ consumieron
• Si el plan se está llenando muy rápido (riesgo overage Anthropic) → auto-throttle a Sonnet en vez de Opus
• Alert si llegás al 90% del Pro antes del día 25 del mes