Système d'événements de Pi Agent

Le système d'événements est le mécanisme central des extensions.

En écoutant les événements du cycle de vie, vous pouvez insérer une logique personnalisée à différentes étapes du travail de l'IA.


Aperçu du cycle de vie

Voici tous les événements déclenchés pendant le cycle de vie de Pi Agent, du démarrage à la sortie :

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

Dans chaque tour, les événements context, provider et tool se déclenchent en séquence, en bouclant sur plusieurs tours lorsque des appels d'outils sont effectués.

Les parties en pointillés indiquent que l'étape peut être déclenchée plusieurs fois par plusieurs événements.

Pour le moment de déclenchement d'autres événements tels que input, before_agent_start, resources_discover et agent_settled, voir la référence rapide complète des événements ci-dessous.


Événements principaux expliqués

Cette section sélectionne les 5 événements les plus fréquemment utilisés et explique leur moment de déclenchement ainsi que les conventions de valeur de retour.

input — Interception de l'entrée

Déclenché avant que l'entrée utilisateur ne soit traitée ; vous pouvez transformer, intercepter ou traiter directement l'entrée :

Exemple

// Chemin du fichier : ~/.pi/agent/extensions/quick-input.ts
// L'extrait suivant se trouve dans le corps de la fonction de fabrique de l'extension
pi.on("input", async (event, ctx) => {
  // event.text - texte d'entrée brut
  // event.images - images jointes
  // event.source - "interactive" | "rpc" | "extension"

  // Transformer l'entrée : ajouter une instruction au début de l'entrée
  if (event.text.startsWith("?quick ")) {
    return {
      action: "transform",
      text:`Réponse brève : ${event.text.slice(7)}`
    };
  }

  // Traiter directement : répondre sans passer par le LLM
  if (event.text === "ping") {
    ctx.ui.notify("pong", "info");
    return { action: "handled" };
  }

  // Ignorer les messages injectés par l'extension
  if (event.source === "extension") {
    return { action: "continue" };
  }

  return { action: "continue" };  // Par défaut : traiter normalement
});
valeur de l'actionEffet
"continue"Ne modifie pas l'entrée ; poursuit le flux de traitement normal
"transform"Poursuit le traitement après avoir modifié l'entrée ; les transformations de plusieurs gestionnaires s'enchaînent
"handled"Prend complètement le contrôle, en sautant l'appel au LLM (le premier gestionnaire qui renvoie cette valeur prend effet)

Les effets réels de deux implémentations typiques sont les suivants.

Lorsque l'entrée est?quick hello world, le texte réellement envoyé au LLM a été réécrit :

简短回复:hello world

Lorsque l'entrée estping, le LLM n'est pas appelé ; seule une notification s'affiche dans le terminal :

pong

L'événement d'entrée se déclenche avant l'expansion des Skill et templateavant, donc ce que vous voyez est l'entrée brute.

/skill:foo et /template ne sont pas encore étendus à ce stade.


tool_call — Interception des appels d'outils

Déclenché avant l'exécution de l'outil ; vous pouvez modifier les arguments ou bloquer l'exécution :

Exemple

// Chemin du fichier : ~/.pi/agent/extensions/guard-bash.ts
// les instructions import se placent en haut du module ; l'extrait pi.on ci-dessous se trouve dans le corps de la fonction factory de l'extension
// isToolCallEventType est un garde de type et doit être importé depuis le paquet officiel
import { isToolCallEventType } from "@earendil-works/pi-coding-agent";

pi.on("tool_call", async (event, ctx) => {
  // Bloquer les commandes bash dangereuses
  if (isToolCallEventType("bash", event)) {
    // event.input est { command: string; timeout?: number }
    const dangerous = ["rm -rf /", "mkfs.", "dd if=", "> /dev/sda"];
    // Vérifier d'abord si c'est dangereux, puis décider s'il faut l'autoriser
    if (dangerous.some(cmd =>
        event.input.command.includes(cmd))) {
      return { block: true, reason: "La commande dangereuse a été bloquée" };
    }
    // Ajouter le chargement des variables d'environnement uniquement après que la vérification a réussi
    event.input.command = `source ~/.profile\n${event.input.command}`;
  }

  // Journaliser toutes les opérations de lecture de fichiers
  if (isToolCallEventType("read", event)) {
    // event.input est { path: string; offset?: number; limit?: number }
    ctx.ui.notify(`Lecture du fichier: ${event.input.path}`, "info");
  }
});

Si l’IA tente d’exécuterrm -rf /, l’outil ne s’exécutera pas, et le terminal affichera la raison du blocage :

Dangerous command has been blocked.

event.inputest modifiable — le modifier directement affecte l’exécution de l’outil.


tool_result — Modification des résultats d’outil

Déclenché après la fin de l’exécution de l’outil ; vous pouvez modifier le résultat retourné au LLM :

Exemple

// Chemin du fichier : ~/.pi/agent/extensions/read-linenum.ts
// L'extrait suivant se trouve dans le corps de la fonction de fabrique de l'extension
pi.on("tool_result", async (event, ctx) => {
  // event.toolName - nom de l’outil
  // event.content - contenu renvoyé au LLM
  // event.details - données de détail
  // event.isError - indique s’il s’agit d’une erreur

  // Exemple : ajouter des numéros de ligne aux résultats 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 }],
    };
  }
});

Le contenu d'origine du fichier de deux lignes devient une forme numérotée par ligne lorsqu'il est transmis au LLM :

1: import { readFile } from "node:fs/promises";
2: export async function load() {

context — Modification du contexte LLM

Déclenché avant chaque appel LLM ; vous pouvez filtrer ou modifier les messages :

Exemple

// Chemin du fichier : ~/.pi/agent/extensions/context-filter.ts
// L'extrait suivant se trouve dans le corps de la fonction de fabrique de l'extension
pi.on("context", async (event, ctx) => {
  // event.messages - copie profonde des messages de contexte actuels ; modifiable sans risque

  // Filtrer les messages d'un type spécifique
  const filtered = event.messages.filter(m => {
    // Supprimer les messages avec le type personnalisé "debug"
    if (m.type === "custom" && m.customType === "debug") {
      return false;
    }
    return true;
  });

  return { messages: filtered };
});

before_agent_start — Injection de messages

Déclenché avant que l'IA ne commence à traiter l'entrée utilisateur ; vous pouvez injecter des messages supplémentaires ou modifier le prompt système :

Exemple

// Chemin du fichier : ~/.pi/agent/extensions/context-inject.ts
// L'extrait suivant se trouve dans le corps de la fonction de fabrique de l'extension
pi.on("before_agent_start", async (event, ctx) => {
  // event.prompt - le texte du prompt de l'utilisateur
  // event.systemPrompt - le prompt système actuellement configuré

  return {
    // Injecter un message persistant (stocké dans la session et envoyé au LLM)
    message: {
      customType: "my-context",
      content:`L'heure actuelle est ${new Date().toISOString()}`,
      display: true,
    },
    // Ajouter au prompt système
    systemPrompt: event.systemPrompt
      + "\n\nVeuillez utiliser le chinois dans toutes les réponses.",
  };
});

Référence rapide complète des événements

Plusieurs événements apparaissaient également dans le diagramme ASCII de la section précédente ; ils sont ici listés ensemble par ordre de déclenchement pour faciliter la consultation.

ÉvénementMoment de déclenchementModifiableBloquable
project_trustAvant de charger les ressources du projet ; confirmer s'il faut faire confiance au projet actuelnonOui (les extensions du projet ne sont pas chargées en cas de refus)
session_startLorsque la session démarre ou reprendnonnon
resources_discoverDéclenché après session_start (au démarrage/rechargement)Oui (peut uniquement ajouter des Skills, des modèles de prompt et des chemins de thème ; ne peut pas ajouter ou supprimer des extensions)non
inputAvant que l'entrée utilisateur ne soit traitéeOui (peut transformer l'entrée)Oui (le gestionnaire prend le relais)
before_agent_startAvant que l'IA ne commence à traiter l'entrée utilisateurOui (peut injecter des messages, modifier le prompt système)non
agent_startLorsque la boucle de l'agent démarrenonnon
message_start / message_updatePendant la génération de message (message_update est le delta de streaming de l'assistant)nonnon
message_endLorsque les messages user, assistant et toolResult sont finalisésOui (peut retourner { message } pour remplacer le message final ; role doit correspondre)non
turn_startAu début de chaque tournonnon
contextAvant chaque appel LLMOui (peut filtrer les messages)non
before_provider_headersAvant l'envoi des en-têtes de requête HTTPOui (peut ajouter ou modifier les en-têtes de requête)non
before_provider_requestAvant que le corps de la requête ne soit envoyé au modèleOui (retourner une valeur non undefined remplace l'intégralité de la charge utile de la requête, plutôt que d'abandonner la requête)non
after_provider_responseAprès réception de la réponse HTTP, avant que le corps en streaming soit consomméNon (peut seulement lire le statut/les en-têtes pour observation)non
tool_execution_startLorsque l'outil commence à s'exécuternonnon
tool_callAvant l'exécution de l'outilOui (event.input est modifiable)Oui (block: true)
tool_execution_updateLorsqu'une progression est générée pendant l'exécution de l'outilnonnon
tool_resultAprès la fin de l'exécution de l'outilOui (le contenu retourné peut être modifié)non
tool_execution_endLorsque l'exécution de l'outil se terminenonnon
turn_endÀ la fin de chaque tournonnon
agent_endLorsque la boucle de l'agent se terminenonnon
agent_settledAprès qu'un cycle d'interaction soit entièrement stabilisénonnon
session_before_switchAvant que /new ou /resume soit exécuténonOui (return { cancel: true })
session_before_forkAvant l'exécution de /fork ou /clonenonOui (return { cancel: true })
session_before_compactAvant l'exécution de la compression (manuelle /compact, seuil, dépassement du contexte)Oui (résumé de compression personnalisable)Oui (return { cancel: true })
session_shutdownDéclenché avant la destruction de la session ; quit, /new, /resume, /fork, /reload le déclenchent tous (la raison est quit/reload/new/resume/fork)nonnon

Points clés de la gestion des événements

Lors de l'écriture de gestionnaires d'événements, les points suivants déterminent si le code est robuste.

MéthodeObjectif
Plusieurs extensions écoutent le même événementExécutés en séquence selon l'ordre de chargement des extensions ; la valeur de retour précédente affecte les gestionnaires suivants
Retourner{ block: true, reason: "..." }Bloquer l'opération ; la raison sera affichée à l'utilisateur et à l'IA
Retourner{ cancel: true }Annuler les opérations telles que le changement de session
Utiliserctx.signalRépondre aux signaux d'annulation dans les opérations asynchrones ; abandonner lorsque l'utilisateur appuie sur Échap
Utiliserctx.uiSérie de méthodesInteragir avec l'utilisateur, comme notify, confirm, select, etc.
utiliserctx.hasUIProtéger les appels de dialogueEn modes Print/JSON/RPC, les méthodes de type dialogue ne sont pas disponibles ou sans effet ; vérifier avant d'appeler
utiliserctx.mode === "tui"Protéger les API spécifiques à TUIcustom(), les fabriques de composants, l'entrée terminal, etc. ne sont valides qu'en mode interactif

Ne démarrez pas de ressources en arrière-plan (processus, sockets, timers, etc.) dans la fonction factory de l'extension.

Différez le démarrage des ressources jusqu'à l'événementsession_start, et nettoyez danssession_shutdown.

Autres extensions