扩展

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')
    },
  })
}

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

export default function (pi: ExtensionAPI) {
  // Subscribe to events
  pi.on("event_name", async (event, ctx) => {
    // ctx.ui for user interaction
    const ok = await ctx.ui.confirm("Title", "Are you sure?");
    ctx.ui.notify("Done!", "info");
    ctx.ui.setStatus("my-ext", "Processing...");  // Footer status
    ctx.ui.setWidget("my-ext", ["Line 1", "Line 2"]);  // Widget above editor (default)
  });

  // Register tools, commands, shortcuts, flags
  pi.registerTool({ ... });
  pi.registerCommand("name", { ... });
  pi.registerShortcut("ctrl+x", { ... });
  pi.registerFlag("my-flag", { ... });
}

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

export default async function (pi: ExtensionAPI) {
  const response = await fetch('http://localhost:1234/v1/models')
  const payload = (await response.json()) as {
    data: Array<{
      id: string
      name?: string
      context_window?: number
      max_tokens?: number
    }>
  }

  pi.registerProvider('local-openai', {
    baseUrl: 'http://localhost:1234/v1',
    apiKey: '$LOCAL_OPENAI_API_KEY',
    api: 'openai-completions',
    models: payload.data.map((model) => ({
      id: model.id,
      name: model.name ?? model.id,
      reasoning: false,
      input: ['text'],
      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
      contextWindow: model.context_window ?? 128000,
      maxTokens: model.max_tokens ?? 4096,
    })),
  })
}

pi.on('project_trust', async (event, ctx) => {
  // event.cwd - current working directory
  // ctx has a limited trust context: cwd, mode, hasUI, and select/confirm/input/notify UI helpers
  if (await ctx.ui.confirm('Trust project?', event.cwd)) {
    return { trusted: 'yes', remember: true }
  }
  return { trusted: 'undecided' }
})

pi.on('resources_discover', async (event, _ctx) => {
  // event.cwd - current working directory
  // event.reason - "startup" | "reload"
  return {
    skillPaths: ['/path/to/skills'],
    promptPaths: ['/path/to/prompts'],
    themePaths: ['/path/to/themes'],
  }
})

pi.on('session_start', async (event, ctx) => {
  // event.reason - "startup" | "reload" | "new" | "resume" | "fork"
  // event.previousSessionFile - present for "new", "resume", and "fork"
  ctx.ui.notify(`Session: ${ctx.sessionManager.getSessionFile() ?? 'ephemeral'}`, 'info')
})

pi.on('session_info_changed', async (event, ctx) => {
  // event.name - current normalized name, or undefined if cleared
  ctx.ui.notify(`Session renamed: ${event.name ?? '(none)'}`, 'info')
})

pi.on('session_before_switch', async (event, ctx) => {
  // event.reason - "new" or "resume"
  // event.targetSessionFile - session we're switching to (only for "resume")

  if (event.reason === 'new') {
    const ok = await ctx.ui.confirm('Clear?', 'Delete all messages?')
    if (!ok) return { cancel: true }
  }
})

pi.on('session_before_fork', async (event, ctx) => {
  // event.entryId - ID of the selected entry
  // event.position - "before" for /fork, "at" for /clone
  return { cancel: true } // Cancel fork/clone
  // OR
  return { skipConversationRestore: true } // Reserved for future conversation restore control
})

pi.on('session_before_compact', async (event, ctx) => {
  const { preparation, branchEntries, customInstructions, reason, willRetry, signal } = event

  // reason - "manual" (/compact), "threshold", or "overflow"
  // willRetry - whether the aborted turn is retried after compaction (overflow recovery)

  // Cancel:
  return { cancel: true }

  // Custom summary:
  return {
    compaction: {
      summary: '...',
      firstKeptEntryId: preparation.firstKeptEntryId,
      tokensBefore: preparation.tokensBefore,
    },
  }
})

pi.on('session_compact', async (event, ctx) => {
  // event.compactionEntry - the saved compaction
  // event.fromExtension - whether extension provided it
  // event.reason - "manual" (/compact), "threshold", or "overflow"
  // event.willRetry - whether the aborted turn is retried after compaction (overflow recovery)
})

pi.on('session_before_tree', async (event, ctx) => {
  const { preparation, signal } = event
  return { cancel: true }
  // OR provide custom summary:
  return { summary: { summary: '...', details: {} } }
})

pi.on('session_tree', async (event, ctx) => {
  // event.newLeafId, oldLeafId, summaryEntry, fromExtension
})

pi.on('session_shutdown', async (event, ctx) => {
  // event.reason - "quit" | "reload" | "new" | "resume" | "fork"
  // event.targetSessionFile - destination session for session replacement flows
  // Cleanup, save state, etc.
})

pi.on('before_agent_start', async (event, ctx) => {
  // event.prompt - user's prompt text
  // event.images - attached images (if any)
  // event.systemPrompt - current chained system prompt for this handler
  //   (includes changes from earlier before_agent_start handlers)
  // event.systemPromptOptions - structured options used to build the system prompt
  //   .customPrompt - any custom system prompt (from --system-prompt, SYSTEM.md, or custom templates)
  //   .selectedTools - tools currently active in the prompt
  //   .toolSnippets - one-line descriptions for each tool
  //   .promptGuidelines - custom guideline bullets
  //   .appendSystemPrompt - text from --append-system-prompt flags
  //   .cwd - working directory
  //   .contextFiles - AGENTS.md files and other loaded context files
  //   .skills - loaded skills

  return {
    // Inject a persistent message (stored in session, sent to LLM)
    message: {
      customType: 'my-extension',
      content: 'Additional context for the LLM',
      display: true,
    },
    // Replace the system prompt for this turn (chained across extensions)
    systemPrompt: event.systemPrompt + '\n\nExtra instructions for this turn...',
  }
})

pi.on('agent_start', async (_event, ctx) => {})

pi.on('agent_end', async (event, ctx) => {
  // event.messages - messages from this prompt
})

pi.on('turn_start', async (event, ctx) => {
  // event.turnIndex, event.timestamp
})

pi.on('turn_end', async (event, ctx) => {
  // event.turnIndex, event.message, event.toolResults
})

pi.on('message_start', async (event, ctx) => {
  // event.message
})

pi.on('message_update', async (event, ctx) => {
  // event.message
  // event.assistantMessageEvent (token-by-token stream event)
})

pi.on('message_end', async (event, ctx) => {
  if (event.message.role !== 'assistant') return

  return {
    message: {
      ...event.message,
      usage: {
        ...event.message.usage,
        cost: {
          ...event.message.usage.cost,
          total: 0.123,
        },
      },
    },
  }
})

pi.on('tool_execution_start', async (event, ctx) => {
  // event.toolCallId, event.toolName, event.args
})

pi.on('tool_execution_update', async (event, ctx) => {
  // event.toolCallId, event.toolName, event.args, event.partialResult
})

pi.on('tool_execution_end', async (event, ctx) => {
  // event.toolCallId, event.toolName, event.result, event.isError
})

pi.on('context', async (event, ctx) => {
  // event.messages - deep copy, safe to modify
  const filtered = event.messages.filter((m) => !shouldPrune(m))
  return { messages: filtered }
})

pi.on('before_provider_request', (event, ctx) => {
  console.log(JSON.stringify(event.payload, null, 2))

  // Optional: replace payload
  // return { ...event.payload, temperature: 0 };
})

pi.on('after_provider_response', (event, ctx) => {
  // event.status - HTTP status code
  // event.headers - normalized response headers
  if (event.status === 429) {
    console.log('rate limited', event.headers['retry-after'])
  }
})

pi.on('model_select', async (event, ctx) => {
  // event.model - newly selected model
  // event.previousModel - previous model (undefined if first selection)
  // event.source - "set" | "cycle" | "restore"

  const prev = event.previousModel
    ? `${event.previousModel.provider}/${event.previousModel.id}`
    : 'none'
  const next = `${event.model.provider}/${event.model.id}`

  ctx.ui.notify(`Model changed (${event.source}): ${prev} -> ${next}`, 'info')
})

pi.on('thinking_level_select', async (event, ctx) => {
  // event.level - newly selected thinking level
  // event.previousLevel - previous thinking level

  ctx.ui.setStatus('thinking', `thinking: ${event.level}`)
})

import { isToolCallEventType } from '@earendil-works/pi-coding-agent'

pi.on('tool_call', async (event, ctx) => {
  // event.toolName - "bash", "read", "write", "edit", etc.
  // event.toolCallId
  // event.input - tool parameters (mutable)

  // Built-in tools: no type params needed
  if (isToolCallEventType('bash', event)) {
    // event.input is { command: string; timeout?: number }
    event.input.command = `source ~/.profile\n${event.input.command}`

    if (event.input.command.includes('rm -rf')) {
      return { block: true, reason: 'Dangerous command' }
    }
  }

  if (isToolCallEventType('read', event)) {
    // event.input is { path: string; offset?: number; limit?: number }
    console.log(`Reading: ${event.input.path}`)
  }
})

// my-extension.ts
export type MyToolInput = Static<typeof myToolSchema>

import { isToolCallEventType } from '@earendil-works/pi-coding-agent'
import type { MyToolInput } from 'my-extension'

pi.on('tool_call', (event) => {
  if (isToolCallEventType<'my_tool', MyToolInput>('my_tool', event)) {
    event.input.action // typed
  }
})

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

pi.on("tool_result", async (event, ctx) => {
  // event.toolName, event.toolCallId, event.input
  // event.content, event.details, event.isError

  if (isBashToolResult(event)) {
    // event.details is typed as BashToolDetails
  }

  const response = await fetch("https://example.com/summarize", {
    method: "POST",
    body: JSON.stringify({ content: event.content }),
    signal: ctx.signal,
  });

  // Modify result:
  return { content: [...], details: {...}, isError: false };
});

import { createLocalBashOperations } from '@earendil-works/pi-coding-agent'

pi.on('user_bash', (event, ctx) => {
  // event.command - the bash command
  // event.excludeFromContext - true if !! prefix
  // event.cwd - working directory

  // Option 1: Provide custom operations (e.g., SSH)
  return { operations: remoteBashOps }

  // Option 2: Wrap pi's built-in local bash backend
  const local = createLocalBashOperations()
  return {
    operations: {
      exec(command, cwd, options) {
        return local.exec(`source ~/.profile\n${command}`, cwd, options)
      },
    },
  }

  // Option 3: Full replacement - return result directly
  return { result: { output: '...', exitCode: 0, cancelled: false, truncated: false } }
})

pi.on('input', async (event, ctx) => {
  // event.text - raw input (before skill/template expansion)
  // event.images - attached images, if any
  // event.source - "interactive" (typed), "rpc" (API), or "extension" (via sendUserMessage)
  // event.streamingBehavior - "steer" | "followUp" | undefined
  //   undefined when idle, "steer" for mid-stream interrupts,
  //   "followUp" for messages queued until the agent finishes

  // Transform: rewrite input before expansion
  if (event.text.startsWith('?quick '))
    return { action: 'transform', text: `Respond briefly: ${event.text.slice(7)}` }

  // Handle: respond without LLM (extension shows its own feedback)
  if (event.text === 'ping') {
    ctx.ui.notify('pong', 'info')
    return { action: 'handled' }
  }

  // Route by source: skip processing for extension-injected messages
  if (event.source === 'extension') return { action: 'continue' }

  // Intercept skill commands before expansion
  if (event.text.startsWith('/skill:')) {
    // Could transform, block, or let pass through
  }

  return { action: 'continue' } // Default: pass through to expansion
})

import { CONFIG_DIR_NAME, type ExtensionAPI } from '@earendil-works/pi-coding-agent'
import { join } from 'node:path'

export default function (pi: ExtensionAPI) {
  pi.on('session_start', (_event, ctx) => {
    const projectConfigPath = join(ctx.cwd, CONFIG_DIR_NAME, 'my-extension.json')
    // ...
  })
}

ctx.sessionManager.getEntries() // All entries
ctx.sessionManager.getBranch() // Current branch
ctx.sessionManager.buildContextEntries() // Active branch entries with compaction applied
ctx.sessionManager.getLeafId() // Current leaf entry ID

pi.on('tool_result', async (event, ctx) => {
  const response = await fetch('https://example.com/api', {
    method: 'POST',
    body: JSON.stringify(event),
    signal: ctx.signal,
  })

  const data = await response.json()
  return { details: data }
})

pi.on('tool_call', (event, ctx) => {
  if (isFatal(event.input)) {
    ctx.shutdown()
  }
})

const usage = ctx.getContextUsage()
if (usage && usage.tokens > 100_000) {
  // ...
}

ctx.compact({
  customInstructions: 'Focus on recent changes',
  onComplete: (result) => {
    ctx.ui.notify('Compaction completed', 'info')
  },
  onError: (error) => {
    ctx.ui.notify(`Compaction failed: ${error.message}`, 'error')
  },
})

pi.on('before_agent_start', (event, ctx) => {
  const prompt = ctx.getSystemPrompt()
  console.log(`System prompt length: ${prompt.length}`)
})

const options = ctx.getSystemPromptOptions()
const contextPaths = options.contextFiles?.map((file) => file.path) ?? []

pi.registerCommand('my-cmd', {
  handler: async (args, ctx) => {
    await ctx.waitForIdle()
    // Agent is now idle, safe to modify session
  },
})

const parentSession = ctx.sessionManager.getSessionFile()
const kickoff = 'Continue in the replacement session'

const result = await ctx.newSession({
  parentSession,
  setup: async (sm) => {
    sm.appendMessage({
      role: 'user',
      content: [{ type: 'text', text: 'Context from previous session...' }],
      timestamp: Date.now(),
    })
  },
  withSession: async (ctx) => {
    // Use only the replacement-session ctx here.
    await ctx.sendUserMessage(kickoff)
  },
})

if (result.cancelled) {
  // An extension cancelled the new session
}

const result = await ctx.fork('entry-id-123', {
  withSession: async (ctx) => {
    // Use only the replacement-session ctx here.
    ctx.ui.notify('Now in the forked session', 'info')
  },
})
if (result.cancelled) {
  // An extension cancelled the fork
}

const cloneResult = await ctx.fork('entry-id-456', { position: 'at' })
if (cloneResult.cancelled) {
  // An extension cancelled the clone
}

const result = await ctx.navigateTree('entry-id-456', {
  summarize: true,
  customInstructions: 'Focus on error handling changes',
  replaceInstructions: false, // true = replace default prompt entirely
  label: 'review-checkpoint',
})

const result = await ctx.switchSession('/path/to/session.jsonl', {
  withSession: async (ctx) => {
    await ctx.sendUserMessage('Resume work in the replacement session')
  },
})
if (result.cancelled) {
  // An extension cancelled the switch via session_before_switch
}

import { SessionManager } from '@earendil-works/pi-coding-agent'

pi.registerCommand('switch', {
  description: 'Switch to another session',
  handler: async (args, ctx) => {
    const sessions = await SessionManager.list(ctx.cwd)
    if (sessions.length === 0) return
    const choice = await ctx.ui.select(
      'Pick session:',
      sessions.map((s) => s.file),
    )
    if (choice) {
      await ctx.switchSession(choice, {
        withSession: async (ctx) => {
          ctx.ui.notify('Switched session', 'info')
        },
      })
    }
  },
})

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.registerCommand('handoff', {
  handler: async (_args, ctx) => {
    const oldSessionManager = ctx.sessionManager
    await ctx.newSession({
      withSession: async (_ctx) => {
        // stale old objects: do not do this
        oldSessionManager.getSessionFile()
        pi.sendUserMessage('wrong')
      },
    })
  },
})

pi.registerCommand('reload-runtime', {
  description: 'Reload extensions, skills, prompts, and themes',
  handler: async (_args, ctx) => {
    await ctx.reload()
    return
  },
})

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

export default function (pi: ExtensionAPI) {
  pi.registerCommand('reload-runtime', {
    description: 'Reload extensions, skills, prompts, and themes',
    handler: async (_args, ctx) => {
      await ctx.reload()
      return
    },
  })

  pi.registerTool({
    name: 'reload_runtime',
    label: 'Reload Runtime',
    description: 'Reload extensions, skills, prompts, and themes',
    parameters: Type.Object({}),
    async execute() {
      pi.sendUserMessage('/reload-runtime', { deliverAs: 'followUp' })
      return {
        content: [{ type: 'text', text: 'Queued /reload-runtime as a follow-up command.' }],
      }
    },
  })
}

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 according to action",
  promptGuidelines: ["Use my_tool when the user asks to summarize previously generated text."],
  parameters: Type.Object({
    action: StringEnum(["list", "add"] as const),
    text: Type.Optional(Type.String()),
  }),
  prepareArguments(args) {
    // Optional compatibility shim. Runs before schema validation.
    // Return the current schema shape, for example to fold legacy fields
    // into the modern parameter object.
    return args;
  },

  async execute(toolCallId, params, signal, onUpdate, ctx) {
    // Stream progress
    onUpdate?.({ content: [{ type: "text", text: "Working..." }] });

    return {
      content: [{ type: "text", text: "Done" }],
      details: { result: "..." },
    };
  },

  // Optional: Custom rendering
  renderCall(args, theme, context) { ... },
  renderResult(result, options, theme, context) { ... },
});

pi.sendMessage({
  customType: "my-extension",
  content: "Message text",
  display: true,
  details: { ... },
}, {
  triggerTurn: true,
  deliverAs: "steer",
});

// Simple text message
pi.sendUserMessage('What is 2+2?')

// With content array (text + images)
pi.sendUserMessage([
  { type: 'text', text: 'Describe this image:' },
  { type: 'image', source: { type: 'base64', mediaType: 'image/png', data: '...' } },
])

// During streaming - must specify delivery mode
pi.sendUserMessage('Focus on error handling', { deliverAs: 'steer' })
pi.sendUserMessage('And then summarize', { deliverAs: 'followUp' })

pi.appendEntry('my-state', { count: 42 })
pi.appendEntry('status-card', { title: 'Indexed files', count: 17 })

// Restore on reload
pi.on('session_start', async (_event, ctx) => {
  for (const entry of ctx.sessionManager.getEntries()) {
    if (entry.type === 'custom' && entry.customType === 'my-state') {
      // Reconstruct from entry.data
    }
  }
})

pi.setSessionName('Refactor auth module')

const name = pi.getSessionName()
if (name) {
  console.log(`Session: ${name}`)
}

// Set a label
pi.setLabel(entryId, 'checkpoint-before-refactor')

// Clear a label
pi.setLabel(entryId, undefined)

// Read labels via sessionManager
const label = ctx.sessionManager.getLabel(entryId)

pi.registerCommand('stats', {
  description: 'Show session statistics',
  handler: async (args, ctx) => {
    const count = ctx.sessionManager.getEntries().length
    ctx.ui.notify(`${count} entries`, 'info')
  },
})

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

pi.registerCommand('deploy', {
  description: 'Deploy to an environment',
  getArgumentCompletions: (prefix: string): AutocompleteItem[] | null => {
    const envs = ['dev', 'staging', 'prod']
    const items = envs.map((e) => ({ value: e, label: e }))
    const filtered = items.filter((i) => i.value.startsWith(prefix))
    return filtered.length > 0 ? filtered : null
  },
  handler: async (args, ctx) => {
    ctx.ui.notify(`Deploying: ${args}`, 'info')
  },
})

const commands = pi.getCommands()
const bySource = commands.filter((command) => command.source === 'extension')
const userScoped = commands.filter((command) => command.sourceInfo.scope === 'user')

{
  name: string; // Invokable command name without the leading slash. May be suffixed like "review:1"
  description?: string;
  source: "extension" | "prompt" | "skill";
  sourceInfo: {
    path: string;
    source: string;
    scope: "user" | "project" | "temporary";
    origin: "package" | "top-level";
    baseDir?: string;
  };
}

import { Box, Text } from '@earendil-works/pi-tui'

pi.registerEntryRenderer('status-card', (entry, { expanded }, theme) => {
  const data = entry.data as { title: string; count: number }
  const box = new Box(1, 1, (text) => theme.bg('customMessageBg', text))
  box.addChild(new Text(`${theme.bold(data.title)}: ${data.count}`))
  if (expanded) {
    box.addChild(new Text(theme.fg('dim', JSON.stringify(data, null, 2))))
  }
  return box
})

pi.appendEntry('status-card', { title: 'Indexed files', count: 17 })

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,
})

// Check value
if (pi.getFlag('plan')) {
  // Plan mode enabled
}

const result = await pi.exec('git', ['status'], { signal, timeout: 5000 })
// result.stdout, result.stderr, result.code, result.killed

const active = pi.getActiveTools() // ["read", "bash", ...]
const all = pi.getAllTools()
// all = [{
//   name: "read",
//   description: "Read file contents...",
//   parameters: ...,
//   promptGuidelines: ["Use read to examine files instead of cat or sed."],
//   sourceInfo: { path: "<builtin:read>", source: "builtin", scope: "temporary", origin: "top-level" }
// }, ...]
const builtinTools = all.filter((t) => t.sourceInfo.source === 'builtin')
const extensionTools = all.filter(
  (t) => t.sourceInfo.source !== 'builtin' && t.sourceInfo.source !== 'sdk',
)
pi.setActiveTools([...new Set([...active, 'my_custom_tool'])]) // Keep current tools and enable my_custom_tool
pi.setActiveTools(['read', 'bash']) // Switch to read-only

const model = ctx.modelRegistry.find('anthropic', 'claude-sonnet-4-5')
if (model) {
  const success = await pi.setModel(model)
  if (!success) {
    ctx.ui.notify('No API key for this model', 'error')
  }
}

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

pi.events.on("my:event", (data) => { ... });
pi.events.emit("my:event", { ... });

// Register a new provider with custom models
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 (keeps all models)
pi.registerProvider("anthropic", {
  baseUrl: "https://proxy.example.com"
});

// Register provider with OAuth support for /login
pi.registerProvider("corporate-ai", {
  baseUrl: "https://ai.corp.com",
  api: "openai-responses",
  models: [...],
  oauth: {
    name: "Corporate AI (SSO)",
    async login(callbacks) {
      // Custom OAuth flow
      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) {
      // Refresh logic
      return credentials;
    },
    getApiKey(credentials) {
      return credentials.access;
    }
  }
});

pi.registerCommand('my-setup-teardown', {
  description: 'Remove the custom proxy provider',
  handler: async (_args, _ctx) => {
    pi.unregisterProvider('my-proxy')
  },
})

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
      }
    },
  })
}

import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { dirname, resolve } from "node:path";

async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
  const absolutePath = resolve(ctx.cwd, params.path);

  return withFileMutationQueue(absolutePath, async () => {
    await mkdir(dirname(absolutePath), { recursive: true });
    const current = await readFile(absolutePath, "utf8");
    const next = current.replace(params.oldText, params.newText);
    await writeFile(absolutePath, next, "utf8");

    return {
      content: [{ type: "text", text: `Updated ${params.path}` }],
      details: {},
    };
  });
}

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

pi.registerTool({
  name: "my_tool",
  label: "My Tool",
  description: "What this tool does (shown to LLM)",
  promptSnippet: "List or add items in the project todo list",
  promptGuidelines: [
    "Use my_tool for todo planning instead of direct file edits when the user asks for a task list."
  ],
  parameters: Type.Object({
    action: StringEnum(["list", "add"] as const),  // Use StringEnum for Google compatibility
    text: Type.Optional(Type.String()),
  }),
  prepareArguments(args) {
    if (!args || typeof args !== "object") return args;
    const input = args as { action?: string; oldAction?: string };
    if (typeof input.oldAction === "string" && input.action === undefined) {
      return { ...input, action: input.oldAction };
    }
    return args;
  },

  async execute(toolCallId, params, signal, onUpdate, ctx) {
    // Check for cancellation
    if (signal?.aborted) {
      return { content: [{ type: "text", text: "Cancelled" }] };
    }

    // Stream progress updates
    onUpdate?.({
      content: [{ type: "text", text: "Working..." }],
      details: { progress: 50 },
    });

    // Run commands via pi.exec (captured from extension closure)
    const result = await pi.exec("some-command", [], { signal });

    // Return result
    return {
      content: [{ type: "text", text: "Done" }],  // Sent to LLM
      details: { data: result },                   // For rendering & state
      // Optional: stop after this tool batch when every finalized tool result
      // in the batch also returns terminate: true.
      terminate: true,
    };
  },

  // Optional: Custom rendering
  renderCall(args, theme, context) { ... },
  renderResult(result, options, theme, context) { ... },
});

// Correct: throw to signal an error
async execute(toolCallId, params) {
  if (!isValid(params.input)) {
    throw new Error(`Invalid input: ${params.input}`);
  }
  return { content: [{ type: "text", text: "OK" }], details: {} };
}

pi.registerTool({
  name: 'edit',
  label: 'Edit',
  description: 'Edit a single file using exact text replacement',
  parameters: Type.Object({
    path: Type.String(),
    edits: Type.Array(
      Type.Object({
        oldText: Type.String(),
        newText: Type.String(),
      }),
    ),
  }),
  prepareArguments(args) {
    if (!args || typeof args !== 'object') return args

    const input = args as {
      path?: string
      edits?: Array<{ oldText: string; newText: string }>
      oldText?: unknown
      newText?: unknown
    }

    if (typeof input.oldText !== 'string' || typeof input.newText !== 'string') {
      return args
    }

    return {
      ...input,
      edits: [...(input.edits ?? []), { oldText: input.oldText, newText: input.newText }],
    }
  },
  async execute(toolCallId, params, signal, onUpdate, ctx) {
    // params now matches the current schema
    return {
      content: [{ type: 'text', text: `Applying ${params.edits.length} edit block(s)` }],
      details: {},
    }
  },
})

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

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

// Register, checking flag at execution time
pi.registerTool({
  ...remoteRead,
  async execute(id, params, signal, onUpdate, _ctx) {
    const ssh = getSshConfig()
    if (ssh) {
      const tool = createReadTool(cwd, { operations: createRemoteOps(ssh) })
      return tool.execute(id, params, signal, onUpdate)
    }
    return localRead.execute(id, params, signal, onUpdate)
  },
})