pi-subagent

Convierte la Pi CLI (@earendil-works/pi-coding-agent) en un subagente de codificación programable al que cualquier host MCP (ZCode, Claude Code, Cursor, …) pueda delegar tareas, hacer seguimiento de sesiones y matar procesos.

pi-subagent es un servidor MCP ligero que envuelve pi -p --mode json en 7 herramientas estructuradas: delegar tareas, recoger resultados, tomar decisiones de planificación, gestionar sesiones con nombre y abortar ejecuciones. Aislamiento de procesos, totalmente basado en sesiones, modo síncrono/asíncrono dual.

Por qué

Pi es un agente de codificación minimalista de terminal. En lugar de enseñar a Pi metodología, este proyecto trata a Pi como un trabajador delegable: un agente host (ZCode / Claude Code) decide cuándo delegar, lanza una tarea autocontenida y recoge el resultado. Un proceso Pi = una ejecución de subagente aislada.

• Aislamiento de procesos — cada delegación genera un proceso hijo pi -p. Un fallo de Pi solo afecta a esa ejecución.

• Totalmente basado en sesiones — cada tarea se vincula a una sesión con nombre (p. ej. feat-auth); las llamadas posteriores continúan automáticamente.

• Síncrono / asíncrono — por defecto async (evita timeouts en las llamadas de herramientas del host); recoge con pi_status de sondeo largo.

• Planificable — pi_plan es una función de decisión pura de 5 etapas (rechazar / capacidad / reutilizar / modificar / modo), totalmente probada por unit tests.

• MCP universal — cualquier cliente MCP estándar puede cargarlo.

Related MCP server: cursor-agent-bridge

Arquitectura

┌─────────────────────────────────────────────────────────────┐
│  MCP Host (ZCode / Claude Code / Pi / Cursor …)              │
└───────────────────────────┬─────────────────────────────────┘
                            │ MCP (JSON-RPC over stdio)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  pi-subagent-server  (Node/TS)                                │
│  ┌────────────┐  ┌──────────────┐  ┌────────────────────┐   │
│  │ Tool layer │  │ Session      │  │ Pi runner          │   │
│  │ (7 tools)  │─▶│ registry     │─▶│ (spawn pi -p)      │   │
│  │ + plan()   │  │ + persist    │  │ parse agent_end    │   │
│  └─────┬──────┘  │ + _snapshot  │  │ + tool_execution   │   │
│        │         └──────────────┘  └─────────┬──────────┘   │
│        │                           ┌────────▼─────────┐     │
│        └───────────────────────────│ Run registry     │     │
│           (kill)                   │ + process-table  │     │
│                                   └──────────────────┘     │
└─────────────────────────────────────────────────────────────┘
                            │ child_process.spawn({ cwd })
                            ▼
                   ┌─────────────────────┐
                   │  pi CLI (0.77+)     │
                   └─────────────────────┘

Tres capas con límites claros: Capa de herramientas (esquema MCP + función pura plan()) / Registro de sesiones (estado + persistencia + redacción) / Ejecutor (spawn de pi, parseo de NDJSON, tabla de procesos).

Herramientas

Bucle de revisión: después de pi_task_plan, recoge con pi_status(runId). Cuando la ejecución termina, el servidor detecta que es una ejecución de revisión, parsea _plan-reviewed.md y almacena planVerdict / planReviewedPath en la tarea. Los prompts de etapa incluyen automáticamente el plan revisado y los archivos de salida de las etapas de dependencia superadas.

Etapas asíncronas: pasa mode: "async" a pi_task_stage_run para evitar bloquear una llamada de herramienta durante toda la ejecución (recomendado cuando el host MCP impone un timeout corto de herramienta). Recoge con pi_task_stage_collect(taskId, stageId). Los intentos fallidos se re-despachan bajo un nombre de sesión nuevo para evitar contaminación del historial; después de 3 fallos la etapa pasa a manual con un panel de decisión (retry_with_new_hint se soporta vía promptHintOverride).

Recuperación tras reinicio: volver a ejecutar pi_task_create con el mismo taskId fusiona en lugar de entrar en conflicto. Las etapas cuyo archivo de salida ya existe y pasa la validación se marcan como passed automáticamente, de modo que las tareas interrumpidas se reanudan sin editar manualmente tasks.json.

Modelo de sesión

• Cada sesión tiene un nombre legible + el UUID de Pi + cwd + goal.

• El primer pi_delegate crea la sesión (goal es obligatorio); las llamadas posteriores continúan automáticamente.

• El registro persiste en ~/.pi-subagent/registry.json (escritura atómica; al reiniciar, los registros running interrumpidos se corrigen a error).

• Límite de concurrencia: 4 ejecuciones en curso; una sesión nunca se ejecuta concurrentemente.

• Las tareas persisten en ~/.pi-subagent/tasks.json (escritura atómica; las etapas en ejecución se corrigen a failed(interrupted_by_restart) al reiniciar).

Instalación

git clone <this-repo> && cd pi-subagent
npm install

Requisito previo: la CLI pi está instalada (npm i -g @earendil-works/pi-coding-agent) y en PATH.

Configurar un host MCP

Añade a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "pi-subagent": {
      "command": "npx",
      "args": ["tsx", "/abs/path/to/pi-subagent/src/server.ts"]
    }
  }
}

Variables de entorno opcionales:

• PI_SUBAGENT_REGISTRY — ruta del registro (por defecto ~/.pi-subagent/registry.json)

• PI_BIN — anula el ejecutable de pi (usado por los tests)

Test

npm test           # full suite (140 tests)
npm run test:fast  # dot reporter

Los tests usan un pi falso (test/fixtures/fake-pi.sh) y cubren: asíncrono/síncrono, timeout, kill, fallo de creación de sesión, multi-espera, límite de progreso, reglas de planificación (tabla-driven + tests de propiedad de 100 iteraciones), persistencia del registro, redacción, etc.

Estructura del proyecto

src/
├── types.ts                 # all shared types + error codes
├── errors.ts                # ToolError helpers
├── runner/                  # parse.ts, argv.ts, spawn.ts, process-table.ts
├── registry/                # session.ts, run.ts, persist.ts, redact.ts
├── scheduler/               # keywords.ts, plan.ts (5-stage pure function)
├── tools/                   # delegate, status, plan-tool, session, kill
└── server.ts                # MCP entry (stdio)
skills/pi-subagent/          # SKILL.md + delegation-patterns (strategy layer)
test/                        # fixtures/ + *.test.ts
docs/                        # design.md (spec) + implementation-plan.md

Diseño y proceso

Este proyecto pasó por diseño colaborativo + 4 rondas de revisión externa antes de la implementación. La especificación y el plan están en docs/:

• docs/design.md — especificación de diseño completa (arquitectura, contratos de herramientas, manejo de errores, reglas del planificador, estrategia de pruebas). Cada contrato es trazable a una nota de revisión (R1–R4).

• docs/implementation-plan.md — 19 tareas TDD (escribir test que falla → implementar → pasar → commit).

Decisiones de diseño clave, todas respaldadas por pruebas reales de la salida de pi -p y revisión externa:

• cwd ≠ almacenamiento de sesión — spawn({ cwd }) controla el directorio de trabajo; los archivos de sesión de Pi usan su ubicación por defecto (no contamina el proyecto).

• async por defecto + handshake — las nuevas sesiones esperan el evento session de Pi antes de devolver (con un sessionStartTimeoutMs), de modo que el host siempre recibe un piSessionId real.

• Planificador multi-etapa — plan() es rechazar → capacidad → reutilizar → modificar → modo, donde los modificadores se apilan en lugar de coincidir con el primero (una lección de la ronda de revisión 1).

• Redacción de progreso — los resultados de las herramientas se truncan y se limpian de tokens/claves antes de almacenarse.

Estado

Implementación funcional, 140 tests pasando. Aún no publicado en npm — ejecutar desde el código fuente vía tsx.

Licencia

MIT