Arquitectura de Integración de Pi

Este documento describe cómo Mayros se integra con pi-coding-agent y sus paquetes hermanos (pi-ai, pi-agent-core, pi-tui) para potenciar sus capacidades de agente de IA.

Descripción General

Mayros usa el SDK de pi para incorporar un agente de codificación de IA en su arquitectura de gateway de mensajería. En lugar de generar pi como un subproceso o usar modo RPC, Mayros importa directamente e instancia el AgentSession de pi vía createAgentSession(). Este enfoque embebido proporciona:

• Control completo sobre el ciclo de vida de la sesión y manejo de eventos
• Inyección de herramientas personalizadas (mensajería, sandbox, acciones específicas de canal)
• Personalización del prompt del sistema por canal/contexto
• Persistencia de sesión con soporte para ramificación/compactación
• Rotación de perfiles de autenticación multicuenta con failover
• Cambio de modelo agnóstico al proveedor

Dependencias de Paquetes

jsonCopy
{
  "@mariozechner/pi-agent-core": "0.49.3",
  "@mariozechner/pi-ai": "0.49.3",
  "@mariozechner/pi-coding-agent": "0.49.3",
  "@mariozechner/pi-tui": "0.49.3"
}

Estructura de Archivos

Consulta el código fuente en src/agents/ para la estructura de archivos completa incluyendo:

• pi-embedded-runner/ - Runner principal y lógica de intentos
• pi-tools.ts - Herramientas personalizadas de Mayros
• pi-extensions/ - Extensiones personalizadas de pi
• Sistema de autenticación y resolución de modelos
• Gestión de sesiones y compactación

Flujo de Integración Principal

1. Ejecutar un Agente Embebido

El punto de entrada principal es runEmbeddedPiAgent() que configura y ejecuta una sesión de agente con herramientas personalizadas, configuración del sistema y manejo de eventos.

2. Creación de Sesión

Internamente, el SDK de pi se usa para crear sesiones de agente con SessionManager, AuthStorage, y ModelRegistry personalizados.

3. Suscripción a Eventos

El sistema se suscribe a eventos de sesión de pi incluyendo:

• Inicio/fin/actualización de mensaje (streaming de texto/pensamiento)
• Inicio/actualización/fin de ejecución de herramienta
• Inicio/fin de turno y agente
• Eventos de auto-compactación

4. Prompting

Después de la configuración, la sesión se solicita con el prompt del usuario. El SDK maneja el bucle completo del agente: enviar al LLM, ejecutar llamadas de herramientas, transmitir respuestas.

Arquitectura de Herramientas

Pipeline de Herramientas

1. Herramientas Base: codingTools de pi (read, bash, edit, write)
2. Reemplazos Personalizados: Mayros reemplaza bash con exec/process, personaliza read/edit/write para sandbox
3. Herramientas de Mayros: mensajería, navegador, canvas, sesiones, cron, gateway, etc.
4. Herramientas de Canal: herramientas de acción específicas de Discord/Telegram/Slack/WhatsApp
5. Filtrado de Política: herramientas filtradas por perfil, proveedor, agente, grupo, políticas de sandbox
6. Normalización de Esquema: esquemas limpiados para peculiaridades de Gemini/OpenAI
7. Envolvimiento AbortSignal: herramientas envueltas para respetar señales de abortar

Adaptador de Definición de Herramienta

pi-tool-definition-adapter.ts cierra la brecha entre AgentTool de pi-agent-core y ToolDefinition de pi-coding-agent.

Construcción del Prompt del Sistema

El prompt del sistema se construye en buildAgentSystemPrompt() ensamblando secciones completas incluyendo Tooling, Tool Call Style, protecciones de Seguridad, referencia CLI de Mayros, Skills, Docs, Workspace, Sandbox, Messaging, Reply Tags, Voice, Silent Replies, Heartbeats, metadatos de Runtime, más Memory y Reactions cuando están habilitados.

Gestión de Sesiones

Archivos de Sesión

Las sesiones son archivos JSONL con estructura de árbol (enlace id/parentId). El SessionManager de Pi maneja la persistencia.

Caché de Sesión

session-manager-cache.ts cachea instancias de SessionManager para evitar parseo repetido de archivos.

Limitación de Historial

limitHistoryTurns() recorta el historial de conversación basado en el tipo de canal (DM vs grupo).

Compactación

La auto-compactación se activa en desbordamiento de contexto. compactEmbeddedPiSessionDirect() maneja la compactación manual.

Autenticación y Resolución de Modelo

Perfiles de Autenticación

Mayros mantiene un almacén de perfiles de autenticación con múltiples claves API por proveedor. Los perfiles rotan en fallos con seguimiento de cooldown.

Resolución de Modelo

resolveModel() resuelve modelos usando el ModelRegistry de pi y AuthStorage, estableciendo claves API de runtime.

Failover

FailoverError activa el fallback de modelo cuando está configurado.

Extensiones de Pi

Protección de Compactación

pi-extensions/compaction-safeguard.ts añade barandas a la compactación, incluyendo presupuesto adaptativo de tokens más resúmenes de fallo de herramienta y operaciones de archivo.

Poda de Contexto

pi-extensions/context-pruning.ts implementa poda de contexto basada en cache-TTL.

Herramientas Personalizadas de Mayros

Mayros inyecta herramientas personalizadas incluyendo:

• Herramientas de mensajería (enviar, reaccionar)
• Herramientas de navegador
• Herramientas de canvas
• Herramientas de sesión (spawn, list, switch)
• Herramientas de cron
• Herramientas de gateway
• Herramientas de acciones de canal
• Herramientas web

Configuración

Consulta ~/.mayros/mayros.json para configuración de:

• Proveedores y modelos
• Perfiles de autenticación
• Políticas de herramientas
• Configuración de sandbox
• Prompts del sistema
• Configuración de compactación

Para documentación completa de implementación, consulta el código fuente en src/agents/.