create-pi-extension

Criando uma Extensão Pi

Extensões são módulos TypeScript que se registram no ciclo de vida do pi. Use quando skills não são suficientes.

Estrutura Mínima

extensions/minha-extension.ts

Ou como pacote:

packages/minha-extension/
├── package.json
├── index.ts
└── README.md

Template Base

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  // Registrar tools, commands, eventos, etc.
}

Registrando uma Tool

import { Type } from "@sinclair/typebox";

pi.registerTool({
  name: "minha_tool",
  label: "Minha Tool",
  description: "O que esta tool faz (visível ao LLM)",
  parameters: Type.Object({
    input: Type.String(),
  }),
  async execute(toolCallId, params, signal, onUpdate, ctx) {
    return {
      content: [{ type: "text", text: `Resultado: ${params.input}` }],
      details: {},
    };
  },
});

Registrando um Comando

pi.registerCommand("meu-comando", {
  description: "O que o /meu-comando faz",
  handler: async (args, ctx) => {
    ctx.ui.notify("Executado!", "info");
  },
});

Eventos Comuns

// Quando a sessão inicia ou recarrega
pi.on("session_start", async (event, ctx) => {
  // Reconstruir estado, configurar UI
});

// Antes de cada chamada ao LLM
pi.on("before_agent_start", async (event, ctx) => {
  // Modificar system prompt, injetar contexto
});

// A cada tool call
pi.on("tool_call", async (event, ctx) => {
  // Gate: retornar { cancelled: true, reason: "..." } para bloquear
});

// Quando a sessão encerra
pi.on("session_shutdown", async (event, ctx) => {
  // Cleanup, salvar estado
});

Empacotando como npm

{
  "name": "@aretw0/minha-extension",
  "keywords": ["pi-package"],
  "type": "module",
  "pi": {
    "extensions": ["./index.ts"]
  },
  "peerDependencies": {
    "@earendil-works/pi-coding-agent": "*",
    "@earendil-works/pi-ai": "*",
    "@earendil-works/pi-tui": "*",
    "@sinclair/typebox": "*"
  }
}