Sistema de eventos de Pi Agent
El sistema de eventos es el mecanismo central de las extensiones.
Al escuchar los eventos del ciclo de vida, puedes insertar lógica personalizada en las distintas etapas del trabajo de la IA.
Panorama del ciclo de vida
A continuación se enumeran todos los eventos que se activan durante el proceso de Pi Agent desde el inicio hasta la salida:
Dentro de cada turno, los tres tipos de eventos —context, provider y tool— se activan en orden; cuando hay llamadas a herramientas, se repiten durante varias rondas.
La parte de línea discontinua indica que esa etapa puede ser activada varias veces por múltiples eventos.
El momento de activación de los demás eventos, como input, before_agent_start, resources_discover y agent_settled, se puede consultar en la tabla de referencia rápida de todos los eventos, más abajo.
Detalle de los eventos centrales
Esta sección selecciona los 5 eventos de uso más frecuente y explica su momento de activación y las convenciones de valor de retorno.
input — Intercepción de entrada
Se activa antes de que se procese la entrada del usuario; puede transformar, interceptar o procesar directamente la entrada:
Ejemplo
// El siguiente fragmento se encuentra dentro del cuerpo de la función de fábrica de la extensión
pi.on("input", async (event, ctx) => {
// event.text - Texto de entrada original
// event.images - Imágenes adjuntas
// event.source - "interactive" | "rpc" | "extension"
// Transformar la entrada: añadir una instrucción antes de la entrada
if (event.text.startsWith("?quick ")) {
return {
action: "transform",
text:`Respuesta breve: ${event.text.slice(7)}`
};
}
// Procesamiento directo: responder sin pasar por el LLM
if (event.text === "ping") {
ctx.ui.notify("pong", "info");
return { action: "handled" };
}
// Omitir los mensajes inyectados por la extensión
if (event.source === "extension") {
return { action: "continue" };
}
return { action: "continue" }; // Predeterminado: procesamiento normal
});
| Valores de action | Efecto |
|---|---|
| "continue" | No cambia la entrada; continúa con el flujo de procesamiento normal |
| "transform" | Modifica la entrada y continúa el procesamiento; las transformaciones de varios handlers se acumulan en cadena |
| "handled" | Toma el control total y omite la llamada al LLM (el primer handler que devuelva este valor tiene efecto) |
El efecto real de las dos formas típicas es el siguiente.
Entrada?quick hello worldCuando la entrada es ..., el texto realmente enviado al LLM ha sido reescrito:
简短回复:hello world
EntradapingCuando la entrada es ..., no se llama al LLM; solo aparece una notificación en la terminal:
pong
El evento input se activa antes de la expansión de Skills y plantillasantesSe dispara, por lo que ves la entrada original.
/skill:foo y /template aún no se han expandido en este momento.
tool_call — Intercepción de llamadas a herramientas
Se activa antes de la ejecución de la herramienta; puede modificar los parámetros o impedir la ejecución:
Ejemplo
// El import se escribe en la parte superior del módulo; el siguiente fragmento de pi.on se encuentra dentro del cuerpo de la función de fábrica de la extensión
// isToolCallEventType es un type guard (guardia de tipo); debe importarse desde el paquete oficial
import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
pi.on("tool_call", async (event, ctx) => {
// Interceptar comandos bash peligrosos
if (isToolCallEventType("bash", event)) {
// event.input es { command: string; timeout?: number }
const dangerous = ["rm -rf /", "mkfs.", "dd if=", "> /dev/sda"];
// Primero se determina si es peligroso y luego se decide si se permite
if (dangerous.some(cmd =>
event.input.command.includes(cmd))) {
return { block: true, reason: "El comando peligroso ha sido bloqueado" };
}
// Solo después de que la verificación sea exitosa se añade la carga de variables de entorno
event.input.command = `source ~/.profile\n${event.input.command}`;
}
// Registrar todas las operaciones de lectura de archivos
if (isToolCallEventType("read", event)) {
// event.input es { path: string; offset?: number; limit?: number }
ctx.ui.notify(`Leer archivo: ${event.input.path}`, "info");
}
});
Si la IA intenta ejecutarrm -rf /, la herramienta no se ejecutará y en la terminal se mostrará el motivo del bloqueo:
El comando peligroso ha sido bloqueado.
event.inputes modificable: si lo modificas, afectará directamente a la ejecución de la herramienta.
tool_result — Modificación de resultados de la herramienta
Se activa después de que la herramienta completa su ejecución; puede modificar el resultado devuelto al LLM:
Ejemplo
// El siguiente fragmento se encuentra dentro del cuerpo de la función de fábrica de la extensión
pi.on("tool_result", async (event, ctx) => {
// event.toolName - Nombre de la herramienta
// event.content - Contenido devuelto al LLM
// event.details - Datos de detalle
// event.isError - Indica si es un error
// Ejemplo: añadir números de línea al resultado de read
if (event.toolName === "read" && !event.isError) {
const lines = event.content
.filter(c => c.type === "text")
.map(c => c.text)
.join("\n")
.split("\n")
.map((line, i) => `${i + 1}: ${line}`)
.join("\n");
return {
content: [{ type: "text", text: lines }],
};
}
});
El contenido del archivo, que originalmente tenía dos líneas, se convierte en un formato con números de línea cuando se entrega al LLM:
1: import { readFile } from "node:fs/promises";
2: export async function load() {
context — Modificación del contexto del LLM
Se activa antes de cada llamada al LLM; puede filtrar o modificar mensajes:
Ejemplo
// El siguiente fragmento se encuentra dentro del cuerpo de la función de fábrica de la extensión
pi.on("context", async (event, ctx) => {
// event.messages - Copia profunda de los mensajes del contexto actual; se puede modificar de forma segura
// Filtrar mensajes de tipos específicos
const filtered = event.messages.filter(m => {
// Eliminar los mensajes cuyo tipo personalizado sea "debug"
if (m.type === "custom" && m.customType === "debug") {
return false;
}
return true;
});
return { messages: filtered };
});
before_agent_start — Inyección de mensajes
Se activa antes de que la IA comience a procesar la entrada del usuario; puede inyectar mensajes adicionales o modificar el prompt del sistema:
Ejemplo
// El siguiente fragmento se encuentra dentro del cuerpo de la función de fábrica de la extensión
pi.on("before_agent_start", async (event, ctx) => {
// event.prompt - Texto del prompt del usuario
// event.systemPrompt - Prompt del sistema configurado actualmente
return {
// Inyectar un mensaje persistente (se guarda en la sesión y se envía al LLM)
message: {
customType: "my-context",
content:`La hora actual es ${new Date().toISOString()}`,
display: true,
},
// Añadir al prompt del sistema
systemPrompt: event.systemPrompt
+ "\n\n"Por favor, usa chino en todas las respuestas.",
};
});
Tabla de referencia rápida de todos los eventos
En el diagrama ASCII de la sección anterior también aparecen muchos eventos; aquí se enumeran de forma consolidada según el orden de activación para facilitar su consulta.
| Evento | Momento de activación | ¿Modificable? | ¿Bloqueable? |
|---|---|---|---|
| project_trust | Antes de cargar los recursos del proyecto, se confirma si se confía en el proyecto actual | no | Sí (si se rechaza, no se cargan las extensiones del proyecto) |
| session_start | Al iniciar o reanudar la sesión | no | no |
| resources_discover | Se activa después de session_start (durante startup/reload) | Sí (solo se pueden añadir Skills, plantillas de prompts y rutas de temas; no se pueden añadir ni eliminar extensiones) | no |
| input | Antes de que se procese la entrada del usuario | Sí (puede transformar la entrada) | Sí (handled se hace cargo) |
| before_agent_start | Antes de que la IA comience a procesar la entrada del usuario | Sí (puede inyectar mensajes y modificar el prompt del sistema) | no |
| agent_start | Al comienzo del bucle del agente | no | no |
| message_start / message_update | Durante la generación de mensajes (message_update es el incremento de streaming del asistente) | no | no |
| message_end | Cuando se finalizan los mensajes de usuario, asistente y toolResult | Sí (puede devolver { message } para reemplazar el mensaje final; role debe ser el mismo) | no |
| turn_start | Al comienzo de cada turno | no | no |
| context | Antes de cada llamada al LLM | Sí (puede filtrar mensajes) | no |
| before_provider_headers | Antes de enviar los encabezados HTTP | Sí (puede añadir o modificar encabezados de solicitud) | no |
| before_provider_request | Antes de enviar el cuerpo de la solicitud al modelo | Sí (devolver un valor distinto de undefined reemplaza todo el payload de la solicitud; no la aborta) | no |
| after_provider_response | Después de recibir la respuesta HTTP, el body de streaming aún no se ha consumido | No (solo se pueden leer status/headers para observación) | no |
| tool_execution_start | Cuando la herramienta comienza a ejecutarse | no | no |
| tool_call | Antes de la ejecución de la herramienta | Sí (event.input es modificable) | Sí (block: true) |
| tool_execution_update | Cuando se genera progreso durante la ejecución de la herramienta | no | no |
| tool_result | Después de que se complete la ejecución de la herramienta | Sí (el contenido de retorno se puede modificar) | no |
| tool_execution_end | Cuando finaliza la ejecución de la herramienta | no | no |
| turn_end | Al final de cada ronda | no | no |
| agent_end | Cuando finaliza el bucle del agente | no | no |
| agent_settled | Después de que una ronda de interacción se asiente por completo | no | no |
| session_before_switch | Antes de que se ejecute /new o /resume | no | Sí (devuelve { cancel: true }) |
| session_before_fork | Antes de que se ejecute /fork o /clone | no | Sí (devuelve { cancel: true }) |
| session_before_compact | Antes de que se ejecute la compactación (/compact manual, umbral, desbordamiento de contexto) | Sí (el resumen de compactación se puede personalizar) | Sí (devuelve { cancel: true }) |
| session_shutdown | Se activa antes de la destrucción de la sesión; salir, /new, /resume, /fork y /reload lo activan (reason es quit/reload/new/resume/fork) | no | no |
Puntos clave del manejo de eventos
Al escribir manejadores de eventos, los siguientes puntos determinan si el código es robusto.
| Método | Función |
|---|---|
| Múltiples extensiones escuchan el mismo evento | Se ejecutan en orden de carga de la extensión; el valor de retorno del anterior afecta a los manejadores posteriores |
| Devuelve{ block: true, reason: "..." } | Bloquea la operación; el motivo se mostrará al usuario y a la IA |
| Devuelve{ cancel: true } | Cancela operaciones como el cambio de sesión |
| Usoctx.signal | Responde a señales de cancelación en operaciones asíncronas; se aborta cuando el usuario presiona Escape |
| Usoctx.uiMétodos de la serie | Interactúa con el usuario, como notify, confirm, select, etc. |
| usarctx.hasUIProtege las llamadas de diálogo | En modo Print/JSON/RPC, los métodos de diálogo no están disponibles o son operaciones vacías; verifica antes de llamarlos |
| usarctx.mode === "tui"Protege las API exclusivas de TUI | custom(), las fábricas de componentes, la entrada de terminal, etc. solo son válidos en modo interactivo |
Otras extensionesNo inicies recursos en segundo plano (procesos, sockets, temporizadores, etc.) en la función de fábrica de la extensión.
Retrasa el inicio de recursos hasta elsession_startevento, ysession_shutdownlimpia en él.