Pi Agent イベントシステム

イベントシステムは拡張機能の中核メカニズムです。

ライフサイクルイベントを監視することで、AIが動作する各段階にカスタムロジックを挿入できます。


ライフサイクル全体図

以下は、Pi Agent が起動から終了までの間にトリガーされるすべてのイベントです:

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

各ターン内では、context、provider、tool の3種類のイベントが順番にトリガーされ、ツール呼び出しがある場合は複数ラウンドループします。

破線部分は、その段階が複数のイベントによって複数回トリガーされ得ることを示します。

input、before_agent_start、resources_discover、agent_settled など、その他のイベントのトリガータイミングは、下の全イベント早見表を参照してください。


コアイベントの詳細

このセクションでは、使用頻度が最も高い5つのイベントを取り上げ、それらのトリガータイミングと戻り値の規約を説明します。

input — 入力インターセプト

ユーザー入力が処理される前にトリガーされ、入力を変換、インターセプト、または直接処理できます:

例

// ファイルパス:~/.pi/agent/extensions/quick-input.ts
// 以下の断片は拡張ファクトリ関数の本体内にあります
pi.on("input", async (event, ctx) => {
  // event.text - 元の入力テキスト
  // event.images - 付随する画像
  // event.source - "interactive" | "rpc" | "extension"

  // 入力を変換:入力の前に指示を追加
  if (event.text.startsWith("?quick ")) {
    return {
      action: "transform",
      text:`簡潔な返信:${event.text.slice(7)}`
    };
  }

  // 直接処理:LLMを経由せずに直接応答
  if (event.text === "ping") {
    ctx.ui.notify("pong", "info");
    return { action: "handled" };
  }

  // 拡張機能によって注入されたメッセージをスキップ
  if (event.source === "extension") {
    return { action: "continue" };
  }

  return { action: "continue" };  // デフォルト:通常の処理
});
action の値効果
"continue"入力を変更せず、通常の処理フローを続行
"transform"入力を変更して処理を続行。複数のハンドラの変換はチェーン状に累積される
"handled"完全に引き継ぎ、LLM呼び出しをスキップ(この値を最初に返したハンドラが有効)

2つの典型的な書き方の実際の効果は次のとおりです。

入力?quick hello worldの場合、実際にLLMに送信されるテキストは書き換えられています:

简短回复:hello world

入力pingの場合、LLMは呼び出されず、ターミナルに通知が1つ表示されるだけです:

pong

inputイベントはSkillとテンプレートの展開の前にトリガーされるため、表示されるのは元の入力です。

/skill:foo と /template はこの時点ではまだ展開されていません。


tool_call — ツール呼び出しのインターセプト

ツール実行の前にトリガーされ、パラメータを変更したり実行をブロックしたりできます:

例

// ファイルパス:~/.pi/agent/extensions/guard-bash.ts
// import はモジュールの最上位に記述し、以下の pi.on の断片は拡張ファクトリ関数の本体内にあります
// isToolCallEventType は型ガードであり、公式パッケージからインポートする必要があります
import { isToolCallEventType } from "@earendil-works/pi-coding-agent";

pi.on("tool_call", async (event, ctx) => {
  // 危険なbashコマンドをインターセプト
  if (isToolCallEventType("bash", event)) {
    // event.input は { command: string; timeout?: number }
    const dangerous = ["rm -rf /", "mkfs.", "dd if=", "> /dev/sda"];
    // まず危険かどうかを判断し、それから通過させるかどうかを決定
    if (dangerous.some(cmd =>
        event.input.command.includes(cmd))) {
      return { block: true, reason: "危険なコマンドはブロックされました" };
    }
    // 判断を通過した後にのみ環境変数のロードを追加
    event.input.command = `source ~/.profile\n${event.input.command}`;
  }

  // すべてのファイル読み取り操作を記録
  if (isToolCallEventType("read", event)) {
    // event.input は { path: string; offset?: number; limit?: number }
    ctx.ui.notify(`ファイルを読み取り: ${event.input.path}`, "info");
  }
});

AIが以下を実行しようとした場合rm -rf /、ツールは実行されず、ターミナルにブロック理由が表示されます:

危険なコマンドはブロックされました

event.inputは変更可能です——これを変更するとツールの実行に直接影響します。


tool_result — ツール結果の変更

ツール実行の完了後にトリガーされ、LLMに戻す結果を変更できます:

例

// ファイルパス:~/.pi/agent/extensions/read-linenum.ts
// 以下の断片は拡張ファクトリ関数の本体内にあります
pi.on("tool_result", async (event, ctx) => {
  // event.toolName - ツール名
  // event.content - LLMに返す内容
  // event.details - 詳細データ
  // event.isError - エラーかどうか

  // 例: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 }],
    };
  }
});

元々2行のファイル内容は、LLMに渡されると行番号付きの形式になります:

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

context — LLMコンテキストの変更

毎回のLLM呼び出しの前にトリガーされ、メッセージをフィルタリングまたは変更できます:

例

// ファイルパス:~/.pi/agent/extensions/context-filter.ts
// 以下の断片は拡張ファクトリ関数の本体内にあります
pi.on("context", async (event, ctx) => {
  // event.messages - 現在のコンテキストメッセージのディープコピーであり、安全に変更可能

  // 特定のタイプのメッセージをフィルタリング
  const filtered = event.messages.filter(m => {
    // カスタムタイプが "debug" のメッセージを削除
    if (m.type === "custom" && m.customType === "debug") {
      return false;
    }
    return true;
  });

  return { messages: filtered };
});

before_agent_start — メッセージの注入

AIがユーザー入力の処理を開始する前にトリガーされ、追加のメッセージを注入したりシステムプロンプトを変更したりできます:

例

// ファイルパス:~/.pi/agent/extensions/context-inject.ts
// 以下の断片は拡張ファクトリ関数の本体内にあります
pi.on("before_agent_start", async (event, ctx) => {
  // event.prompt - ユーザーのプロンプトテキスト
  // event.systemPrompt - 現在設定されているシステムプロンプト

  return {
    // 永続化メッセージを1件注入(セッションに保存され、LLMに送信)
    message: {
      customType: "my-context",
      content:`現在の時刻は ${new Date().toISOString()}`,
      display: true,
    },
    // システムプロンプトに追加
    systemPrompt: event.systemPrompt
      + "\n\nすべての返信で中国語を使用してください。",
  };
});

全イベント早見表

前のセクションのASCII図には他にも多くのイベントが登場しました。ここではトリガー順にまとめて記載しているので、参照しやすくなっています。

イベントトリガータイミング変更可能かブロック可能か
project_trustプロジェクトリソースをロードする前に、現在のプロジェクトを信頼するかどうかを確認否はい(拒否した場合はプロジェクト拡張機能をロードしない)
session_startセッションの起動または復元時否否
resources_discoversession_start の後にトリガー(startup/reload 時)はい(Skill、プロンプトテンプレート、テーマパスの追加のみ可能。拡張機能の追加・削除は不可)否
inputユーザー入力が処理される前はい(入力を変換可能)はい(handled で引き継ぎ)
before_agent_startAIがユーザー入力の処理を開始する前はい(メッセージの注入、システムプロンプトの変更が可能)否
agent_startagentループ開始時否否
message_start / message_updateメッセージ生成中(message_update はアシスタントのストリーミング増分)否否
message_endユーザー、アシスタント、toolResult メッセージが確定したときはい({ message } を返して最終メッセージを置き換え可能。role は一致している必要があります)否
turn_start各ターンの開始時否否
context毎回のLLM呼び出しの前はい(メッセージをフィルタリング可能)否
before_provider_headersHTTPリクエストヘッダーを送信する前はい(リクエストヘッダーを追加・変更可能)否
before_provider_requestリクエストボディをモデルに送信する前はい(undefined 以外の値を返すとリクエスト全体のpayloadを置き換える。リクエストを中止するわけではない)否
after_provider_responseHTTPレスポンスを受信した後、ストリーミングbodyがまだ消費されていない時点いいえ(status/headers を読み取って観測することのみ可能)否
tool_execution_startツールの実行開始時否否
tool_callツール実行前はい(event.input は変更可能)はい(block: true)
tool_execution_updateツール実行中に進捗が発生したとき否否
tool_resultツール実行完了後はい(戻り内容を変更可能)否
tool_execution_endツール実行終了時否否
turn_end各ターン終了時否否
agent_endエージェントループ終了時否否
agent_settled1ラウンドの対話が完全に落ち着いた後否否
session_before_switch/new または /resume の実行前否はい({ cancel: true } を返します)
session_before_fork/fork または /clone の実行前否はい({ cancel: true } を返します)
session_before_compact圧縮実行前(手動 /compact、しきい値、コンテキストオーバーフロー)はい(圧縮サマリーをカスタマイズ可能)はい({ cancel: true } を返します)
session_shutdownセッション破棄前に発火します。終了、/new、/resume、/fork、/reload でも発火します(reason は quit/reload/new/resume/fork)否否

イベント処理のポイント

イベントハンドラーを書く際、以下の点がコードの堅牢性を左右します。

メソッド機能
複数の拡張機能が同じイベントを監視する場合拡張機能の読み込み順に順次実行され、前の戻り値が後続のハンドラーに影響します
戻り値{ block: true, reason: "..." }その操作をブロックし、reason はユーザーと AI に表示されます
戻り値{ cancel: true }セッション切り替えなどの操作をキャンセルします
使用ctx.signal非同期操作でキャンセル信号に応答し、ユーザーが Escape キーを押すと中止します
使用ctx.ui一連のメソッドユーザーとの対話(notify、confirm、select など)
用 ctx.hasUIダイアログ呼び出しのガードPrint/JSON/RPC モードではダイアログ系メソッドは利用不可または空操作のため、先に判定してから呼び出します
用 ctx.mode === "tui"TUI 専用 API のガードcustom()、コンポーネントファクトリ、端末入力などは対話モードでのみ有効です

拡張機能のファクトリー関数内でバックグラウンドリソース(プロセス、ソケット、タイマーなど)を起動しないでください。

リソースの起動をsession_startイベント内に延期し、session_shutdownでクリーンアップします。

他の拡張機能