Pi Extension Capabilities

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

export default function (pi: ExtensionAPI) {
  // React to events
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify("Extension loaded!", "info");
  });

  pi.on("tool_call", async (event, ctx) => {
    if (event.toolName === "bash" &&
        event.input.command?.includes("rm -rf")) {
      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
      if (!ok) return { block: true, reason: "Blocked by user" };
    }
  });

  // Register a custom tool
  pi.registerTool({
    name: "greet",
    label: "Greet",
    description: "Greet someone by name",
    parameters: Type.Object({
      name: Type.String({ description: "Name to greet" }),
    }),
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      return {
        content: [{ type: "text", text: `Hello, ${params.name}!` }],
        details: {},
      };
    },
  });

  // Register a command
  pi.registerCommand("hello", {
    description: "Say hello",
    handler: async (args, ctx) => {
      ctx.ui.notify(`Hello ${args ?? "world"}!`, "info");
    },
  });
}

{
  "extensions": [
    "/path/to/local/extension.ts",
    "/path/to/local/extension/dir"
  ]
}

// Dialogs
const choice = await ctx.ui.select("Pick one:", ["A", "B", "C"]);
const ok = await ctx.ui.confirm("Delete?", "This cannot be undone");
const name = await ctx.ui.input("Name:", "placeholder");
const text = await ctx.ui.editor("Edit:", "prefilled text");

// Notifications
ctx.ui.notify("Done!", "info");  // "info" | "warning" | "error"

// Status in footer
ctx.ui.setStatus("my-ext", "Processing...");
ctx.ui.setStatus("my-ext", undefined);  // Clear

// Widget above/below editor
ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"]);
ctx.ui.setWidget("my-widget", ["Line 1"], { placement: "belowEditor" });

// Custom footer
ctx.ui.setFooter((tui, theme) => ({ render(w) { return [theme.fg("dim", "Custom")]; } }));

// Working indicator during streaming
ctx.ui.setWorkingMessage("Thinking deeply...");
ctx.ui.setWorkingIndicator({ frames: [ctx.ui.theme.fg("accent", "●")] });

// Theme management
const themes = ctx.ui.getAllThemes();
ctx.ui.setTheme("light");

// Custom autocomplete
ctx.ui.addAutocompleteProvider((current) => ({
  async getSuggestions(lines, line, col, options) {
    return current.getSuggestions(lines, line, col, options);
  },
}));

// Read session state
ctx.sessionManager.getEntries()       // All entries
ctx.sessionManager.getBranch()        // Current branch
ctx.sessionManager.getLeafId()        // Current leaf entry ID
ctx.sessionManager.getSessionFile()    // Session file path
ctx.sessionManager.getLabel(entryId)   // Get label for entry

// Persist extension state (does NOT participate in LLM context)
pi.appendEntry("my-state", { count: 42 });

// Set session name
pi.setSessionName("Refactor auth module");

// Set/clear labels on entries
pi.setLabel(entryId, "checkpoint-before-refactor");
pi.setLabel(entryId, undefined);  // Clear

// Trigger compaction
ctx.compact({
  customInstructions: "Focus on recent changes",
  onComplete: (result) => ctx.ui.notify("Done!", "info"),
});

// Get context usage
const usage = ctx.getContextUsage();

// Get system prompt string
const prompt = ctx.getSystemPrompt();

// Abort signal for nested async work
const response = await fetch("https://api.example.com", {
  signal: ctx.signal,  // Respects Esc cancellation
});

// Check idle state
const idle = ctx.isIdle();
const hasPending = ctx.hasPendingMessages();

// Request graceful shutdown
ctx.shutdown();

// Check if UI is available (false in print/JSON mode)
if (ctx.hasUI) { /* safe to use ctx.ui */ }

pi.registerCommand("my-cmd", {
  handler: async (args, ctx) => {
    // Wait for agent to finish streaming
    await ctx.waitForIdle();

    // Create a new session
    const result = await ctx.newSession({
      withSession: async (ctx) => {
        await ctx.sendUserMessage("Continue in replacement session");
      },
    });

    // Fork from a specific entry
    await ctx.fork("entry-id-123");

    // Navigate tree
    await ctx.navigateTree("entry-id-456", { summarize: true });

    // Switch sessions
    await ctx.switchSession("/path/to/session.jsonl");

    // Reload extensions
    await ctx.reload();
    return;  // Treat reload as terminal
  },
});

pi.on("event_name", async (event, ctx) => {
  // handler
});

import { Type } from "typebox";
import { StringEnum } from "@earendil-works/pi-ai";

pi.registerTool({
  name: "my_tool",
  label: "My Tool",
  description: "What this tool does",
  promptSnippet: "Summarize or transform text",
  promptGuidelines: [
    "Use my_tool when the user asks to summarize text.",
  ],
  parameters: Type.Object({
    action: StringEnum(["list", "add"] as const),
    text: Type.Optional(Type.String()),
  }),
  prepareArguments(args) {
    // Compatibility shim — runs before schema validation
    return args;
  },
  async execute(toolCallId, params, signal, onUpdate, ctx) {
    // Stream progress
    onUpdate?({ content: [{ type: "text", text: "Working..." }] });

    if (signal?.aborted) {
      return { content: [{ type: "text", text: "Cancelled" }] };
    }

    return {
      content: [{ type: "text", text: "Done" }],
      details: { result: "..." },
      // Optional: skip follow-up LLM call
      terminate: true,
    };
  },
  // Optional: custom rendering
  renderCall(args, theme, context) { ... },
  renderResult(result, options, theme, context) { ... },
});

import type { AutocompleteItem } from "@earendil-works/pi-tui";

pi.registerCommand("deploy", {
  description: "Deploy to an environment",
  getArgumentCompletions: (prefix: string) => {
    const envs = ["dev", "staging", "prod"];
    return envs
      .filter(e => e.startsWith(prefix))
      .map(e => ({ value: e, label: e }));
  },
  handler: async (args, ctx) => {
    ctx.ui.notify(`Deploying: ${args}`, "info");
  },
});

pi.registerShortcut("ctrl+shift+p", {
  description: "Toggle plan mode",
  handler: async (ctx) => {
    ctx.ui.notify("Toggled!");
  },
});

pi.registerFlag("plan", {
  description: "Start in plan mode",
  type: "boolean",
  default: false,
});

if (pi.getFlag("plan")) {
  // Plan mode enabled
}

import { Text } from "@earendil-works/pi-tui";

pi.registerMessageRenderer("my-extension", (message, options, theme) => {
  const { expanded } = options;
  let text = theme.fg("accent", `[${message.customType}] `);
  text += message.content;
  if (expanded && message.details) {
    text += "\n" + theme.fg("dim", JSON.stringify(message.details, null, 2));
  }
  return new Text(text, 0, 0);
});

// Send messages with matching customType
pi.sendMessage({
  customType: "my-extension",
  content: "Status update",
  display: true,
  details: { ... },
});

// Register a new provider
pi.registerProvider("my-proxy", {
  name: "My Proxy",
  baseUrl: "https://proxy.example.com",
  apiKey: "$PROXY_API_KEY",  // env var reference
  api: "anthropic-messages",
  models: [{
    id: "claude-sonnet-4-20250514",
    name: "Claude 4 Sonnet (proxy)",
    reasoning: false,
    input: ["text", "image"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 200000,
    maxTokens: 16384,
  }],
});

// Override baseUrl for an existing provider
pi.registerProvider("anthropic", {
  baseUrl: "https://proxy.example.com",
});

// With OAuth
pi.registerProvider("corporate-ai", {
  baseUrl: "https://ai.corp.com",
  api: "openai-responses",
  models: [...],
  oauth: {
    name: "Corporate AI (SSO)",
    async login(callbacks) {
      callbacks.onAuth({ url: "https://sso.corp.com/..." });
      const code = await callbacks.onPrompt({ message: "Enter code:" });
      return { refresh: code, access: code, expires: Date.now() + 3600000 };
    },
    async refreshToken(credentials) { return credentials; },
    getApiKey(credentials) { return credentials.access; },
  },
});

// Unregister
pi.unregisterProvider("my-proxy");

// Set model
const model = ctx.modelRegistry.find("anthropic", "claude-sonnet-4-5");
if (model) {
  const success = await pi.setModel(model);
}

// Thinking level
const current = pi.getThinkingLevel();  // "off" | "minimal" | "low" | "medium" | "high" | "xhigh"
pi.setThinkingLevel("high");

const active = pi.getActiveTools();
const all = pi.getAllTools();

// Filter by source
const builtin = all.filter(t => t.sourceInfo.source === "builtin");
const extTools = all.filter(t => t.sourceInfo.source !== "builtin" && t.sourceInfo.source !== "sdk");

// Switch active tools
pi.setActiveTools(["read", "bash"]);  // Read-only mode

// Extension A
pi.events.emit("my:event", { data: "hello" });

// Extension B
pi.events.on("my:event", (data) => {
  console.log(data);  // { data: "hello" }
});

// Send a message into the session
pi.sendMessage({
  customType: "my-extension",
  content: "Message text",
  display: true,
}, {
  deliverAs: "steer",       // "steer" | "followUp" | "nextTurn"
  triggerTurn: true,
});

// Send a user message (triggers a turn)
pi.sendUserMessage("What is 2+2?");
pi.sendUserMessage("Focus on error handling", { deliverAs: "steer" });

// Execute a shell command
const result = await pi.exec("git", ["status"], { signal, timeout: 5000 });
// result.stdout, result.stderr, result.code, result.killed

// Append persistent state
pi.appendEntry("my-state", { count: 42 });

// Override built-in read with logging
import { createReadTool } from "@earendil-works/pi-coding-agent";

const localRead = createReadTool(cwd);

pi.registerTool({
  ...localRead,
  async execute(id, params, signal, onUpdate, ctx) {
    console.log(`Read called: ${params.path}`);
    return localRead.execute(id, params, signal, onUpdate, ctx);
  },
});

import { createReadTool, type ReadOperations } from "@earendil-works/pi-coding-agent";

const remoteRead = createReadTool(cwd, {
  operations: {
    readFile: (path) => sshExec(remote, `cat ${path}`),
    access: (path) => sshExec(remote, `test -r ${path}`).then(() => {}),
  }
});

import {
  truncateHead,
  truncateTail,
  truncateLine,
  formatSize,
  DEFAULT_MAX_BYTES,  // 50KB
  DEFAULT_MAX_LINES,  // 2000
} from "@earendil-works/pi-coding-agent";

const truncation = truncateHead(output, {
  maxLines: DEFAULT_MAX_LINES,
  maxBytes: DEFAULT_MAX_BYTES,
});

if (truncation.truncated) {
  const tempFile = writeTempFile(output);
  result += `[Output truncated: ${truncation.outputLines} of ${truncation.totalLines} lines]`;
}

import { Text } from "@earendil-works/pi-tui";
import { keyHint } from "@earendil-works/pi-coding-agent";

renderCall(args, theme, context) {
  const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
  let content = theme.fg("toolTitle", theme.bold("my_tool "));
  content += theme.fg("muted", args.action);
  text.setText(content);
  return text;
},

renderResult(result, { expanded, isPartial }, theme, context) {
  if (isPartial) {
    return new Text(theme.fg("warning", "Processing..."), 0, 0);
  }
  let text = theme.fg("success", "✓ Done");
  if (!expanded) {
    text += ` (${keyHint("app.tools.expand", "to expand")} to expand)`;
  }
  return new Text(text, 0, 0);
},

export default function (pi: ExtensionAPI) {
  let items: string[] = [];

  // Reconstruct state from session
  pi.on("session_start", async (_event, ctx) => {
    items = [];
    for (const entry of ctx.sessionManager.getBranch()) {
      if (entry.type === "message" && entry.message.role === "toolResult") {
        if (entry.message.toolName === "my_tool") {
          items = entry.message.details?.items ?? [];
        }
      }
    }
  });

  pi.registerTool({
    name: "my_tool",
    async execute(toolCallId, params, signal, onUpdate, ctx) {
      items.push("new item");
      return {
        content: [{ type: "text", text: "Added" }],
        details: { items: [...items] },  // Store for reconstruction
      };
    },
  });
}

// Select from options
const choice = await ctx.ui.select("Pick one:", ["A", "B", "C"]);

// Confirm dialog
const ok = await ctx.ui.confirm("Delete?", "This cannot be undone");

// Text input
const name = await ctx.ui.input("Name:", "placeholder");

// Multi-line editor
const text = await ctx.ui.editor("Edit:", "prefilled text");

// Timed dialog with countdown
const confirmed = await ctx.ui.confirm(
  "Timed Confirmation",
  "Auto-cancels in 5 seconds",
  { timeout: 5000 }
);

// Manual dismissal with AbortSignal
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 5000);
const confirmed2 = await ctx.ui.confirm("Title", "Msg", { signal: controller.signal });
clearTimeout(timeoutId);

// Status in footer
ctx.ui.setStatus("my-ext", "Processing...");
ctx.ui.setStatus("my-ext", undefined);  // Clear

// Working loader during streaming
ctx.ui.setWorkingMessage("Thinking deeply...");
ctx.ui.setWorkingVisible(false);  // Hide built-in working row

// Custom working indicator
ctx.ui.setWorkingIndicator({
  frames: [
    ctx.ui.theme.fg("dim", "·"),
    ctx.ui.theme.fg("muted", "•"),
    ctx.ui.theme.fg("accent", "●"),
  ],
  intervalMs: 120,
});

// Widget above editor
ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"]);

// Widget below editor
ctx.ui.setWidget("my-widget", ["Line 1"], { placement: "belowEditor" });

// Custom footer
ctx.ui.setFooter((tui, theme) => ({
  render(width) { return [theme.fg("dim", "Custom footer")]; },
  invalidate() {},
}));

// Terminal title
ctx.ui.setTitle("pi - my-project");

import { Text, Component } from "@earendil-works/pi-tui";

const result = await ctx.ui.custom<boolean>((tui, theme, keybindings, done) => {
  const text = new Text("Press Enter to confirm, Escape to cancel", 1, 1);
  text.onKey = (key) => {
    if (key === "return") done(true);
    if (key === "escape") done(false);
    return true;
  };
  return text;
});

// Overlay mode (floating modal on top of content)
const overlayResult = await ctx.ui.custom(
  (tui, theme, keybindings, done) => new MyOverlayComponent({ onClose: done }),
  {
    overlay: true,
    overlayOptions: { anchor: "top-right", width: "50%", margin: 2 },
  }
);

import { CustomEditor } from "@earendil-works/pi-coding-agent";
import { matchesKey } from "@earendil-works/pi-tui";

class VimEditor extends CustomEditor {
  private mode: "normal" | "insert" = "insert";

  handleInput(data: string): void {
    if (matchesKey(data, "escape") && this.mode === "insert") {
      this.mode = "normal";
      return;
    }
    if (this.mode === "normal" && data === "i") {
      this.mode = "insert";
      return;
    }
    super.handleInput(data);
  }
}

export default function (pi: ExtensionAPI) {
  pi.on("session_start", (_event, ctx) => {
    ctx.ui.setEditorComponent((_tui, theme, keybindings) =>
      new VimEditor(theme, keybindings)
    );
  });
}

pi.on("session_start", (_event, ctx) => {
  ctx.ui.addAutocompleteProvider((current) => ({
    async getSuggestions(lines, cursorLine, cursorCol, options) {
      const line = lines[cursorLine] ?? "";
      const beforeCursor = line.slice(0, cursorCol);
      const match = beforeCursor.match(/(?:^|[ \t])#([^\s#]*)$/);
      if (!match) return current.getSuggestions(lines, cursorLine, cursorCol, options);

      return {
        prefix: `#${match[1] ?? ""}`,
        items: [
          { value: "#2983", label: "#2983", description: "Extension API docs" },
        ],
      };
    },
    applyCompletion(lines, line, col, item, prefix) {
      return current.applyCompletion(lines, line, col, item, prefix);
    },
  }));
});

// Foreground colors
theme.fg("toolTitle", text)   // Tool names
theme.fg("accent", text)      // Highlights
theme.fg("success", text)     // Success (green)
theme.fg("error", text)       // Errors (red)
theme.fg("warning", text)     // Warnings (yellow)
theme.fg("muted", text)       // Secondary text
theme.fg("dim", text)         // Tertiary text

// Text styles
theme.bold(text)
theme.italic(text)
theme.strikethrough(text)

// Syntax highlighting
import { highlightCode, getLanguageFromPath } from "@earendil-works/pi-coding-agent";
const highlighted = highlightCode("const x = 1;", "typescript", theme);
const lang = getLanguageFromPath("/path/to/file.rs");  // "rust"

pi.on("tool_call", async (event, ctx) => {
  if (isToolCallEventType("bash", event)) {
    const dangerous = ["rm -rf", "sudo", "mkfs", "> /dev/"];
    const match = dangerous.find(d => event.input.command.includes(d));
    if (match) {
      const ok = await ctx.ui.confirm("⚠️ Dangerous Command", `Block \`${match}\`?`);
      if (!ok) return { block: true, reason: `Blocked: ${match}` };
    }
  }
});

pi.on("turn_start", async (_event, ctx) => {
  await pi.exec("git", ["stash", "push", "pi-checkpoint"], { cwd: ctx.cwd });
});

pi.on("turn_end", async (_event, ctx) => {
  await pi.exec("git", ["stash", "pop"], { cwd: ctx.cwd });
});

pi.on("session_before_compact", async (event, ctx) => {
  const { preparation } = event;
  return {
    compaction: {
      summary: "Focus on code changes, ignore chit-chat",
      firstKeptEntryId: preparation.firstKeptEntryId,
      tokensBefore: preparation.tokensBefore,
    }
  };
});

pi.registerCommand("handoff", {
  handler: async (_args, ctx) => {
    const kickoff = "Continue from the replacement session";
    await ctx.newSession({
      withSession: async (ctx) => {
        await ctx.sendUserMessage(kickoff);
      },
    });
  },
});

pi.on("session_start", async (event, ctx) => {
  if (event.reason === "startup") {
    pi.registerTool({
      name: "dynamic_tool",
      label: "Dynamic Tool",
      description: "Registered at startup",
      parameters: Type.Object({}),
      async execute() {
        return { content: [{ type: "text", text: "Dynamic!" }], details: {} };
      },
    });
  }
});

// SSH remote execution
pi.registerFlag("ssh", { description: "Use SSH remote", type: "boolean" });

pi.on("user_bash", (event, ctx) => {
  if (pi.getFlag("ssh")) {
    return { operations: createRemoteOps(getSshConfig()) };
  }
  return { operations: createLocalBashOperations() };
});

// Custom Anthropic proxy
pi.registerProvider("my-anthropic", {
  baseUrl: "https://proxy.example.com/v1",
  apiKey: "$ANTHROPIC_API_KEY",
  api: "anthropic-messages",
  models: [{
    id: "claude-sonnet-4-20250514",
    name: "Claude 4 Sonnet",
    reasoning: false,
    input: ["text", "image"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 200000,
    maxTokens: 16384,
  }],
});