Meta Agent Evolution

Observador local de fallos recurrentes y generación de propuestas revisables por humanos. Local observer for recurrent agent failures with human-reviewed improvement proposals.

---

Resumen Ejecutivo / Executive Summary

• ES: Repositorio en ESM puro (Node.js 22+, sin dependencias en el núcleo analítico) que implementa un flujo determinista para registrar fallos sintéticos, detectar patrones recurrentes entre sesiones independientes y generar propuestas estructuradas en estado pending. Prohíbe la autoaprobación: ningún cambio sobre agentes, prompts o skills se aplica sin revisión humana explícita.
• EN: Pure ESM repository (Node.js 22+, zero dependencies in the analytical core) providing a deterministic pipeline to record synthetic failures, detect recurrent patterns across independent sessions, and generate structured proposals in pending status. Self-approval is strictly prohibited: no modifications to agents, prompts, or skills occur without explicit human review.

---

Arquitectura del Sistema / System Architecture

[ Evidencias Sintéticas / Synthetic Records ]
                      │
                      ▼
┌────────────────────────────────────────────────────────┐
│ 1. Ingesta / Ingestion (`src/evidence.mjs`)           │
│    - Contrato estricto de 6 campos (exact schema)      │
│    - Normalización de fechas UTC ISO 8601              │
│    - Saneamiento JSON acíclico y límites de nodos      │
└─────────────────────┬──────────────────────────────────┘
                      │
                      ▼
┌────────────────────────────────────────────────────────┐
│ 2. Detección / Detection (`src/patterns.mjs`)         │
│    - Agrupamiento por arnés, código y tipo             │
│    - Recurrencia requerida: >=2 sesiones distintas     │
│    - Ventana temporal configurable y hashing SHA-256   │
└─────────────────────┬──────────────────────────────────┘
                      │
                      ▼
┌────────────────────────────────────────────────────────┐
│ 3. Propuestas / Proposals (`src/proposals.mjs`)       │
│    - Destinos tipados: agent, prompt, skill            │
│    - Estado inicial inmutable: `pending`               │
│    - Justificación basada en evidencias verificables   │
└─────────────────────┬──────────────────────────────────┘
                      │
                      ▼
┌────────────────────────────────────────────────────────┐
│ 4. Revisión / Review (`src/proposals.mjs`)            │
│    - Control humano exclusivo: approve / reject        │
│    - Prohibición estricta de auto-aplicación           │
│    - Trazabilidad y auditoría determinista             │
└────────────────────────────────────────────────────────┘

---

Especificaciones del Modelo y Configuración / Model Specifications & Configuration

• Modelo Meta Runtime (ADR H6): metab/muse-spark-1.3-contributor
• OmniRoute Local Endpoint: http://127.0.0.1:20129/v1
• Capa H6 Meta-Análisis: Modo OFF por defecto (META_META_ENABLED="true" requerido para habilitar). Verificada exclusivamente mediante mocks; cero llamadas de inferencia LLM real y cero egress de red.
• Runtime: Node.js >=22 (ECMAScript Modules puro / Pure ESM)

---

Servidor MCP (7 Herramientas) / MCP Server (7 Tools)

El repositorio expone un servidor MCP nativo (src/mcp-server.mjs) a través de stdio, con las siguientes 7 herramientas exactas:

1. meta_status: Consulta el estado del observador en memoria (enabled: false por defecto, sin sondeo activo).
2. meta_evidences: Lista o limpia evidencias en memoria (limit, offset, clear).
3. meta_analyze: Analiza patrones recurrentes entre sesiones independientes (minSessions >= 2).
4. meta_propose: Construye propuestas estructuradas con hash SHA-256 en estado pending (targetKind: agent, prompt, skill; enrich). Nunca aplica cambios.
5. meta_review: Registra la decisión humana (approve o reject) con nota de auditoría; prohíbe auto-aplicar modificaciones.
6. meta_synthetic_demo: Ejecuta el pipeline determinista con datos sintéticos autocontenidos.
7. meta_ingest_evidence: Valida y registra una evidencia individual según el esquema estricto de 6 campos.

---

Resultados Verificados (HITO2 y HITO3) / Verified Results

• HITO2 (E2E Test Suite): npm test (node --test) ejecuta la suite con resultado PASS verificable: 250 tests passed, 249 subtests, 0 failures, 1 cancelled, código de salida exit 0.
• HITO3 (Despliegue Plugin OpenCode): 12 módulos verificados por hash SHA-256 desplegados en el directorio de plugins de OpenCode (~/.config/opencode/plugins/meta-agent-evolution/), exponiendo las 7 herramientas MCP con meta_status en estado OFF por defecto (sin consumo de CPU ni polling de fondo sin invocación explícita).

---

Demostraciones Ejecutables / Runnable Demos

Demostraciones deterministas reproducibles sin red, sin credenciales y sin llamadas a LLM:

# 1. Demostración standalone de 3 propuestas (agent, skill-optimize->skill, new-skill->skill)
node examples/h5-three-proposals.mjs

# 2. Demostración sintética básica (1 propuesta prompt)
node examples/meta-synthetic.mjs

# 3. Suite completa de pruebas automatizadas
npm test

---

Trabajo Previo vs. Nuevo / Prior Work vs. New Implementation

• Aislamiento de Legado: El código previo ubicado en el directorio raíz (Task Observer y Skill Prompt Evolution) constituye trabajo antecedente independiente.
• Equivalencia No Demostrada: La equivalencia técnica entre ambos sistemas no ha sido demostrada. En consecuencia, no se desactiva ningún componente legado y se registran los puntos de integración como tareas pendientes.
• Nueva Implementación: meta-agent-evolution es un desarrollo limpio, autónomo y desacoplado, sin importación de código ni dependencias del sistema raíz.

---

Límites Técnicos Honestos / Honest Technical Limitations

1. Cero LLM Real: El sistema opera sin inferencia LLM en vivo. Toda la validación de la capa meta-analítica H6 se ejecuta contra mocks en memoria.
2. Interfaz de Usuario: La integración con las interfaces OpenCode TUI y OpenCode Desktop permanece PENDIENTE.
3. Procesos Huérfanos en OS: El control de ciclo de vida del proceso de vigilancia (watcher) ante terminaciones forzadas del sistema operativo (Windows y POSIX) presenta variabilidad indeterminada y queda catalogado como límite técnico identificado.

---

Estructura del Repositorio / Repository Structure

meta-agent-evolution/
├── README.md
├── package.json
├── docs/
│   ├── architecture.md
│   ├── attributions.md
│   ├── prior-work.md
│   ├── adr-001-recurrent-failure-contract.md
│   ├── adr-003-omniroute-muse-spark-open.md
│   ├── hackathon-attributions.md
│   ├── hackathon-demo.md
│   └── hackathon-video-script.md
├── src/
│   ├── evidence.mjs
│   ├── meta-adapter.mjs
│   ├── meta-batch.mjs
│   ├── patterns.mjs
│   ├── proposals.mjs
│   ├── mcp-server.mjs
│   ├── mcp-service.mjs
│   ├── opencode-observer.mjs
│   ├── plugin.mjs
│   ├── store-path.mjs
│   ├── usage-meter.mjs
│   └── watcher.mjs
├── tests/
│   ├── evidence.test.mjs
│   ├── h5-proposals.test.mjs
│   ├── h5-mcp-stdio.test.mjs
│   ├── h5-concurrency.test.mjs
│   ├── meta-adapter.test.mjs
│   ├── meta-batch.test.mjs
│   ├── patterns.test.mjs
│   ├── proposals.test.mjs
│   └── mcp-server.test.mjs
└── examples/
    ├── h5-three-proposals.mjs
    └── meta-synthetic.mjs

---

Licencia / License

• Dependencia Externa: @modelcontextprotocol/sdk se distribuye bajo licencia MIT (Copyright Anthropic, PBC).
• Proyecto: Estado de licencia PENDIENTE (package.json declara "private": true, sin archivo LICENSE en el repositorio).