AgentTape

Convierte una ejecución fallida de Codex en una prueba de regresión portátil.

AgentTape es un plugin de Codex de código abierto y local-first que registra fallos de herramientas compatibles como evidencia .tape redactada y versionada. Inspecciona qué falló, bifurca la ejecución capturada en un límite controlado y guarda el resultado como una prueba de regresión sin conexión que puede ejecutarse en CI sin otra llamada al modelo.

La mayoría de las herramientas de rastreo te ayudan a observar un fallo. AgentTape está diseñado para convertir ese fallo en un artefacto pequeño y revisable que evita que el mismo error vuelva a aparecer.

Codex tool failure
        ↓
redacted .tape evidence
        ↓
inspect → inject one condition → compare branches
        ↓
save assertions → run offline in CI

Por qué AgentTape

• Artefacto de fallo, no otro panel de control. Un .tape es evidencia portátil que puedes inspeccionar, revisar, compartir y confirmar con una corrección de errores.

• Captura nativa de Codex. Los hooks incluidos registran eventos de ciclo de vida, permisos y herramientas compatibles después de que el usuario los revise y confíe en ellos; no se requiere instrumentación de la aplicación.

• Local y respetuoso con la privacidad. Las capturas en tiempo de ejecución permanecen dentro del proyecto activo, y los campos comunes que contienen secretos se redactan recursivamente antes de la exportación.

• Inyección controlada de fallos. Bifurca la evidencia registrada con resultados de permiso denegado, tiempo de espera agotado, JSON malformado o respuesta truncada.

• Pruebas de regresión sin conexión. La reproducción estructural y las aserciones utilizan evidencia capturada con cero llamadas al modelo y cero llamadas a herramientas en vivo.

• Confianza honesta en la reproducción. AgentTape informa la cobertura y las limitaciones en lugar de afirmar que cada sistema externo puede reproducirse bit a bit.

Related MCP server: MCP QA Lab

Instalación desde GitHub

Requisitos previos: Codex y Node.js 20 o superior.

codex plugin marketplace add jiangkoumo/agenttape
codex plugin add agenttape@agenttape

Inicia una nueva tarea de Codex después de la instalación y revisa los hooks incluidos antes de confiar en ellos. Las capturas se almacenan entonces en el directorio .agent-tape/ del proyecto activo.

Flujo de trabajo de dos minutos

Primero, usa Codex con normalidad hasta que falle una llamada a una herramienta local compatible. Luego pregunta:

Use tool search to find AgentTape. List captured runs, inspect the latest
failed run, and explain the first recorded failure and replay confidence.

AgentTape expone cuatro herramientas MCP:

Ejecuta una regresión guardada localmente o en CI:

node plugins/agenttape/scripts/agenttape.mjs test \
  tests/agenttape/fixture_permission_denied-timeout.tape

Las aserciones que pasan salen con código 0. Los fallos de validación o aserción salen con código distinto de cero, y los valores de comparación capturados se omiten en la salida de fallo.

Qué captura un .tape

La cinta v1 mantiene la evidencia necesaria para la depuración estructural:

• Identidad de ejecución, marcas de tiempo, cobertura de fuente y limitaciones explícitas.

• Eventos ordenados de ciclo de vida, permisos y herramientas locales compatibles.

• Entradas, salidas, fallos explícitos de herramientas y el primer límite de fallo.

• Un manifiesto de redacción que registra dónde se eliminaron los valores.

• Metadatos de bifurcación opcionales, condiciones inyectadas y aserciones estructurales.

• Entradas de confianza de reproducción para que los consumidores puedan distinguir evidencia sólida de trazas solo de reproducción.

El esquema de la cinta es independiente de la interfaz de usuario y de la implementación del grabador. Consulta Tape Schema v1.

Aserciones de regresión

AgentTape admite actualmente comprobaciones deterministas para:

• Un campo es igual a un valor esperado.

• Una herramienta está presente o ausente.

• El recuento de reintentos se mantiene por debajo de un máximo.

• El estado final de la ejecución coincide con el estado esperado.

• La confianza de reproducción cumple un umbral mínimo.

Los artefactos de regresión revisados se escriben en tests/agenttape/ y no se sobrescriben por defecto.

Límites de reproducción

AgentTape proporciona actualmente reproducción estructural, no una re-ejecución completa del agente. Reutiliza el estado capturado, sustituye un resultado de herramienta registrado y se detiene en el límite inyectado. No regenera el razonamiento posterior del modelo.

Las herramientas alojadas, el estado externo no capturado y los cambios en sistemas de terceros pueden estar ausentes. Un marcador de redacción demuestra que el redactor de AgentTape se ejecutó; no puede demostrar que un texto libre arbitrario no contenga secretos. Revisa cada .tape antes de compartirlo.

Consulta Privacy y Security para conocer el límite de confianza completo.

Estructura del repositorio

plugins/agenttape/
  .codex-plugin/plugin.json   # Codex plugin manifest
  hooks/hooks.json            # Recorder lifecycle hooks
  skills/capture-failure/     # Guided capture workflow
  dist/mcp-server.mjs         # Self-contained bundled MCP server
  scripts/                    # Recorder, schema, and assertion CLI
  schemas/                    # Versioned .tape schema

El repositorio también contiene un prototipo opcional de Branch Canvas en src/ y un MCP HTTP sin estado experimental en remote/. Ejercitan los mismos conceptos de cinta y reproducción, pero no son necesarios para instalar o usar el plugin de Codex.

Desarrollo local

git clone https://github.com/jiangkoumo/agenttape.git
cd agenttape
npm ci
npm run test:plugin-release
npm run build:plugin
codex plugin marketplace add .
codex plugin add agenttape@agenttape

El plugins/agenttape/dist/mcp-server.mjs confirmado permite que las instalaciones del marketplace se ejecuten sin compilar el repositorio. Recompílalo y confírmalo cada vez que cambie el código fuente de MCP.

Ejecuta npm test y npm run build al cambiar el Branch Canvas opcional, el adaptador de Sites o las superficies MCP HTTP remotas.

Desinstalación

codex plugin remove agenttape@agenttape
codex plugin marketplace remove agenttape

Contribuciones

Se aceptan problemas y solicitudes de extracción. Consulta Contributing, Code of Conduct y Changelog.

Licencia

MIT. Consulta LICENSE.