IPC agéntico

¿Qué es el IPC de Puruto?

El IPC (Inter-Process Communication) agéntico de Puruto permite que un Puruto delegue tareas a otro Puruto de forma controlada y trazable.

Un Puruto puede decirle a otro: “ejecuta esta acción con este prompt” y recibir una respuesta estructurada.

Cómo generarlo

python3 .claude/skills/puruto-generator/scripts/generate.py \
  --name puruto-reservas \
  --description "Gestión de reservas" \
  --ipc true

Esto genera en el repo:

.claude/skills/call/SKILL.md (skill /call)
.puruto-ipc.json (allowlists y límites de delegación)
ipc.py (scaffold runtime local)
invoker.py (scaffold invocador)

Artefactos que deben mantenerse juntos

Si existe .puruto-ipc.json, el validador (validate.py) espera también:

.claude/skills/call/SKILL.md
ipc.py
invoker.py

Si faltan, puede devolver errores como:

missing-ipc-skill
missing-ipc-runtime

Contratos (MVP)

InvocationRequest

{
  "request_id": "req-20260224-001",
  "correlation_id": "corr-20260224-001",
  "caller": "puruto-reservas",
  "target": "puruto-finanzas",
  "action": "pagar_factura",
  "prompt": "Paga la factura #123 por 50 EUR",
  "timeout_sec": 120,
  "hop": 0
}

Campo	Descripción
`request_id`	Identificador único de esta petición
`correlation_id`	Traza compartida para llamadas encadenadas
`caller`	Puruto que inicia la invocación
`target`	Puruto destino
`action`	Nombre lógico de la acción
`prompt`	Prompt operativo a ejecutar por el target
`timeout_sec`	Timeout en segundos
`hop`	Profundidad de delegación (0 = primera llamada)

InvocationResult

Respuesta exitosa:

{
  "request_id": "req-20260224-001",
  "correlation_id": "corr-20260224-001",
  "status": "ok",
  "duration_ms": 824,
  "result": {
    "summary": "Factura #123 pagada"
  }
}

Respuesta con error:

{
  "request_id": "req-20260224-001",
  "correlation_id": "corr-20260224-001",
  "status": "error",
  "duration_ms": 15,
  "error": {
    "code": "DENIED",
    "message": "Target no está en la allowlist",
    "details": null
  }
}

Códigos de error (MVP, ejemplo de contrato)

Código	Descripción
`TARGET_NOT_FOUND`	El Puruto target no existe o no está disponible
`DENIED`	El target no está en la allowlist
`TIMEOUT`	La ejecución superó `timeout_sec`
`INVALID_RESPONSE`	El target no devolvió un `InvocationResult` válido

Configuración: `.puruto-ipc.json`

Plantilla generada por defecto (scaffold)

El generador crea esta base (template real):

{
  "enabled": true,
  "owner": "puruto-demo",
  "max_hops": 2,
  "default_timeout_sec": 120,
  "allowed_targets": [],
  "allowed_actions": {}
}

Notas:

owner se rellena con el nombre del repo
max_hops por defecto en la plantilla actual es 2
allowed_targets empieza vacío

Ejemplo operativo con allowlists

{
  "enabled": true,
  "owner": "puruto-reservas",
  "allowed_targets": ["puruto-finanzas", "puruto-data"],
  "allowed_actions": {
    "puruto-finanzas": ["pagar_factura", "consultar_saldo"],
    "puruto-data": ["leer", "escribir"]
  },
  "max_hops": 2,
  "default_timeout_sec": 120
}

Campo	Descripción
`enabled`	Activa/desactiva IPC en el repo
`owner`	Nombre del Puruto propietario de la configuración
`allowed_targets`	Lista de Purutos a los que se puede delegar
`allowed_actions`	Mapa opcional `target -> acciones permitidas`
`max_hops`	Profundidad máxima de delegación (evita bucles)
`default_timeout_sec`	Timeout por defecto para invocaciones

Qué valida `validate.py` sobre `.puruto-ipc.json`

El validador actual comprueba:

que el JSON se pueda parsear (invalid-ipc-config)
presencia recomendada de claves:
- enabled
- owner
- max_hops
- default_timeout_sec
- allowed_targets
- allowed_actions
tipos:
- allowed_targets debe ser lista
- allowed_actions debe ser objeto JSON

Ejemplos válidos e inválidos

Válido (mínimo razonable)

{
  "enabled": true,
  "owner": "puruto-financial",
  "max_hops": 2,
  "default_timeout_sec": 120,
  "allowed_targets": ["puruto-data"],
  "allowed_actions": {
    "puruto-data": ["read", "write"]
  }
}

Inválido (tipos incorrectos)

{
  "enabled": true,
  "owner": "puruto-financial",
  "max_hops": 2,
  "default_timeout_sec": 120,
  "allowed_targets": "puruto-data",
  "allowed_actions": ["read", "write"]
}

Esto dispara ipc-config-invalid-type.

La skill `/call`

Ejemplo de uso (documentado por el scaffold):

/call puruto-finanzas pagar_factura "Paga la factura #123 por 50 EUR"

La skill scaffold /call (visible en snapshots del generador) recuerda:

leer .puruto-ipc.json
comprobar allowed_targets
respetar max_hops
incluir request_id y correlation_id

CLI del scaffold (`invoker.py` e `ipc.py`)

`invoker.py` (scaffold común local)

CLI disponible en el scaffold (según snapshot generado):

python3 invoker.py \
  --target puruto-data \
  --action read \
  --prompt "Lee registro" \
  --caller puruto-ipc \
  --timeout 120

La salida incluye:

request con campos extra del scaffold (payload, requested_at)
response con resultado stub (stub: true, echo, prompt_preview)

`ipc.py` (cliente IPC local scaffold)

CLI disponible:

python3 ipc.py \
  --target puruto-data \
  --action read \
  --prompt "Lee registro" \
  --timeout 120 \
  --hop 0

Comportamiento:

carga .puruto-ipc.json
valida allowlists
delega al invoker.py scaffold
imprime JSON (request + response) o error estructurado

Ejemplo real (scaffold, éxito)

{
  "response": {
    "status": "ok",
    "result": {
      "stub": true,
      "echo": {
        "target": "puruto-data",
        "action": "read"
      }
    }
  }
}

Ejemplo real (scaffold, `DENIED`)

Con allowed_targets que no incluye el target:

{
  "response": {
    "status": "error",
    "error": {
      "code": "DENIED",
      "message": "DENIED: target `puruto-data` no está en allowed_targets"
    }
  }
}

Otro error scaffold: `IPC_ERROR`

Si ipc.py falla por cualquier excepción no controlada (por ejemplo falta .puruto-ipc.json), el scaffold devuelve:

error.code = "IPC_ERROR"

Seguridad y límites

Nunca delegues a un Puruto fuera de allowed_targets
Usa allowed_actions para limitar superficie por target
max_hops previene bucles y cadenas largas difíciles de auditar
No pongas secretos en InvocationRequest; usa puruto-data para compartir datos sensibles

Estado actual (MVP)

El IPC agéntico en Puruto está en modo scaffold MVP:

ipc.py e invoker.py se generan y sirven de base
hay contrato recomendado y validación estructural
la integración completa con runtimes/agentes depende del caso de uso

Comandos de verificación recomendados

# Validar estructura IPC + tipos JSON
python3 .claude/skills/validate/scripts/validate.py /ruta/a/tu-puruto --json

# Probar invoker scaffold
python3 invoker.py --target puruto-data --action read --prompt "Lee registro"

# Probar cliente IPC scaffold (usa .puruto-ipc.json)
python3 ipc.py --target puruto-data --action read --prompt "Lee el registro"

Siguientes pasos

Última verificación

Contenido contrastado con /Users/pepetox/Documents/01-code/puruto/.claude/skills/puruto-generator/templates/common/.puruto-ipc.json.tpl, validate.py y snapshots IPC del generador el 25 de febrero de 2026.