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:

Pi Agent 扩展事件生命周期:启动、项目信任、会话启动、turn 循环与会话关闭

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

// Ruta del archivo: ~/.pi/agent/extensions/quick-input.ts
// 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 actionEfecto
"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

// Ruta del archivo: ~/.pi/agent/extensions/guard-bash.ts
// 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

// Ruta del archivo: ~/.pi/agent/extensions/read-linenum.ts
// 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

// Ruta del archivo: ~/.pi/agent/extensions/context-filter.ts
// 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

// Ruta del archivo: ~/.pi/agent/extensions/context-inject.ts
// 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.

EventoMomento de activación¿Modificable?¿Bloqueable?
project_trustAntes de cargar los recursos del proyecto, se confirma si se confía en el proyecto actualnoSí (si se rechaza, no se cargan las extensiones del proyecto)
session_startAl iniciar o reanudar la sesiónnono
resources_discoverSe 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
inputAntes de que se procese la entrada del usuarioSí (puede transformar la entrada)Sí (handled se hace cargo)
before_agent_startAntes de que la IA comience a procesar la entrada del usuarioSí (puede inyectar mensajes y modificar el prompt del sistema)no
agent_startAl comienzo del bucle del agentenono
message_start / message_updateDurante la generación de mensajes (message_update es el incremento de streaming del asistente)nono
message_endCuando se finalizan los mensajes de usuario, asistente y toolResultSí (puede devolver { message } para reemplazar el mensaje final; role debe ser el mismo)no
turn_startAl comienzo de cada turnonono
contextAntes de cada llamada al LLMSí (puede filtrar mensajes)no
before_provider_headersAntes de enviar los encabezados HTTPSí (puede añadir o modificar encabezados de solicitud)no
before_provider_requestAntes de enviar el cuerpo de la solicitud al modeloSí (devolver un valor distinto de undefined reemplaza todo el payload de la solicitud; no la aborta)no
after_provider_responseDespués de recibir la respuesta HTTP, el body de streaming aún no se ha consumidoNo (solo se pueden leer status/headers para observación)no
tool_execution_startCuando la herramienta comienza a ejecutarsenono
tool_callAntes de la ejecución de la herramientaSí (event.input es modificable)Sí (block: true)
tool_execution_updateCuando se genera progreso durante la ejecución de la herramientanono
tool_resultDespués de que se complete la ejecución de la herramientaSí (el contenido de retorno se puede modificar)no
tool_execution_endCuando finaliza la ejecución de la herramientanono
turn_endAl final de cada rondanono
agent_endCuando finaliza el bucle del agentenono
agent_settledDespués de que una ronda de interacción se asiente por completonono
session_before_switchAntes de que se ejecute /new o /resumenoSí (devuelve { cancel: true })
session_before_forkAntes de que se ejecute /fork o /clonenoSí (devuelve { cancel: true })
session_before_compactAntes 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_shutdownSe 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)nono

Puntos clave del manejo de eventos

Al escribir manejadores de eventos, los siguientes puntos determinan si el código es robusto.

MétodoFunción
Múltiples extensiones escuchan el mismo eventoSe 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.signalResponde a señales de cancelación en operaciones asíncronas; se aborta cuando el usuario presiona Escape
Usoctx.uiMétodos de la serieInteractúa con el usuario, como notify, confirm, select, etc.
usarctx.hasUIProtege las llamadas de diálogoEn 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 TUIcustom(), las fábricas de componentes, la entrada de terminal, etc. solo son válidos en modo interactivo

No 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.

Otras extensiones