pi-code 0.1.0

package/extensions/hooks.ts

@@ -0,0 +1,178 @@
+/**
+ * Claude Hooks Extension
+ *
+ * Runs Claude Code's `.claude/settings.json` hooks on pi's lifecycle events, so
+ * a project's existing hooks work under pi:
+ * - PreToolUse  -> pi `tool_call` (can block the tool)
+ * - PostToolUse -> pi `tool_execution_end` (fire-and-forget)
+ * - SessionStart-> pi `session_start` (fire-and-forget)
+ *
+ * Hook commands run via `sh -c` with the event JSON on stdin. A PreToolUse
+ * hook blocks the tool by exiting 2 (stderr becomes the reason) or by printing
+ * `{"hookSpecificOutput": {"permissionDecision": "deny", ...}}` (or the older
+ * `{"decision": "block"}`).
+ *
+ * Config is merged from ~/.claude/settings.json (always) plus the project's
+ * .claude/settings.json and settings.local.json (only when the project is
+ * trusted, since hooks execute arbitrary shell). Claude tool matchers are
+ * PascalCase (`Bash`); pi tool names are lowercase (`bash`), so matchers are
+ * applied case-insensitively.
+ *
+ * Docs: https://code.claude.com/docs/en/hooks.md
+ */
+
+import { spawn } from 'node:child_process'
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+const DEFAULT_TIMEOUT_S = 60
+
+interface HookCommand {
+  type?: string
+  command: string
+  timeout?: number
+}
+interface HookMatcher {
+  matcher?: string
+  hooks: HookCommand[]
+}
+export type HooksConfig = Record<string, HookMatcher[]>
+
+export interface HookDecision {
+  block: boolean
+  reason?: string
+}
+export interface HookRunResult {
+  code: number
+  stdout: string
+  stderr: string
+}
+export type HookRunner = (command: string, payload: unknown, timeoutMs: number) => Promise<HookRunResult>
+
+/** Settings files to read, newest-winning. Project files load only when trusted. */
+export function hookFiles(cwd: string, home: string, trusted: boolean): string[] {
+  const files = [path.join(home, '.claude', 'settings.json')]
+  if (trusted) files.push(path.join(cwd, '.claude', 'settings.json'), path.join(cwd, '.claude', 'settings.local.json'))
+  return files
+}
+
+export function loadHooks(files: string[]): HooksConfig {
+  const config: HooksConfig = {}
+  for (const file of files) {
+    let parsed: { hooks?: HooksConfig }
+    try {
+      parsed = JSON.parse(fs.readFileSync(file, 'utf-8'))
+    } catch {
+      continue
+    }
+    for (const [event, matchers] of Object.entries(parsed.hooks ?? {})) {
+      if (Array.isArray(matchers)) config[event] = [...(config[event] ?? []), ...matchers]
+    }
+  }
+  return config
+}
+
+function matcherApplies(matcher: string | undefined, name: string): boolean {
+  if (!matcher || matcher === '*') return true
+  try {
+    return new RegExp(`^(?:${matcher})$`, 'i').test(name)
+  } catch {
+    return matcher.toLowerCase() === name.toLowerCase()
+  }
+}
+
+/** Command specs whose matcher applies to the given tool/source name. */
+export function matchingCommands(matchers: HookMatcher[] | undefined, name: string): HookCommand[] {
+  const result: HookCommand[] = []
+  for (const entry of matchers ?? []) {
+    if (matcherApplies(entry.matcher, name)) result.push(...(entry.hooks ?? []))
+  }
+  return result
+}
+
+function tryParseJson(text: string): { hookSpecificOutput?: { permissionDecision?: string; permissionDecisionReason?: string }; decision?: string; reason?: string } | undefined {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
+/** Map a hook's exit code / output to a block-or-allow decision. */
+export function interpretHookResult(code: number, stdout: string, stderr: string): HookDecision {
+  if (code === 2) return { block: true, reason: stderr.trim() || 'Blocked by hook' }
+  const parsed = tryParseJson(stdout)
+  const specific = parsed?.hookSpecificOutput
+  if (specific?.permissionDecision === 'deny') return { block: true, reason: specific.permissionDecisionReason ?? 'Blocked by hook' }
+  if (parsed?.decision === 'block') return { block: true, reason: parsed.reason ?? 'Blocked by hook' }
+  return { block: false }
+}
+
+export const runHookCommand: HookRunner = (command, payload, timeoutMs) =>
+  new Promise((resolve) => {
+    const child = spawn('sh', ['-c', command], { stdio: ['pipe', 'pipe', 'pipe'] })
+    let stdout = ''
+    let stderr = ''
+    const timer = setTimeout(() => child.kill('SIGKILL'), timeoutMs)
+    child.stdout?.on('data', (chunk) => {
+      stdout += chunk
+    })
+    child.stderr?.on('data', (chunk) => {
+      stderr += chunk
+    })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      resolve({ code: code ?? 0, stdout, stderr })
+    })
+    child.on('error', () => {
+      clearTimeout(timer)
+      resolve({ code: 0, stdout, stderr })
+    })
+    // A hook that exits without reading stdin (e.g. `exit 2`) closes the pipe first,
+    // so ignore EPIPE on this write rather than crashing the host process.
+    child.stdin?.on('error', () => {})
+    child.stdin?.end(JSON.stringify(payload))
+  })
+
+function timeoutMs(command: HookCommand): number {
+  return (command.timeout ?? DEFAULT_TIMEOUT_S) * 1000
+}
+
+/** Run PreToolUse hooks for a tool; the first blocking verdict wins. */
+export async function runPreToolUse(config: HooksConfig, toolName: string, toolInput: unknown, runner: HookRunner): Promise<HookDecision> {
+  for (const command of matchingCommands(config.PreToolUse, toolName)) {
+    const result = await runner(command.command, { hook_event_name: 'PreToolUse', tool_name: toolName, tool_input: toolInput }, timeoutMs(command))
+    const decision = interpretHookResult(result.code, result.stdout, result.stderr)
+    if (decision.block) return decision
+  }
+  return { block: false }
+}
+
+async function runNotifyHooks(commands: HookCommand[], payload: unknown, runner: HookRunner): Promise<void> {
+  await Promise.all(commands.map((command) => runner(command.command, payload, timeoutMs(command))))
+}
+
+export default function hooksExtension(pi: ExtensionAPI) {
+  let config: HooksConfig = {}
+
+  pi.on('session_start', async (event, ctx) => {
+    const trusted = ctx.isProjectTrusted?.() ?? false
+    config = loadHooks(hookFiles(ctx.cwd, os.homedir(), trusted))
+    // Only fire SessionStart hooks on a genuine session begin, matched by source (Claude uses
+    // "startup"/"resume"/...). "reload" and "fork" re-fire in-process and would double-run hooks.
+    if (event.reason === 'reload' || event.reason === 'fork') return
+    await runNotifyHooks(matchingCommands(config.SessionStart, event.reason), { hook_event_name: 'SessionStart', source: event.reason }, runHookCommand)
+  })
+
+  pi.on('tool_call', async (event) => {
+    const decision = await runPreToolUse(config, event.toolName, event.input, runHookCommand)
+    return decision.block ? { block: true, reason: decision.reason } : undefined
+  })
+
+  pi.on('tool_execution_end', async (event) => {
+    if (event.isError) return
+    await runNotifyHooks(matchingCommands(config.PostToolUse, event.toolName), { hook_event_name: 'PostToolUse', tool_name: event.toolName }, runHookCommand)
+  })
+}

package/extensions/mcp.ts

@@ -0,0 +1,268 @@
+/**
+ * MCP Adapter Extension
+ *
+ * Connects MCP (Model Context Protocol) servers from mcp.json and registers
+ * their tools in pi as `<server>_<tool>`. Async factory connects eagerly at
+ * startup (per-server timeout, failures skip with a notice); stdio and HTTP
+ * (streamable with SSE fallback) transports; /mcp shows status.
+ *
+ * Reads Claude Code's MCP config too. Merge order (later wins): ~/.claude.json,
+ * ~/.pi/agent/mcp.json, .mcp.json, then .pi/mcp.json. User config connects at
+ * startup; project config (.mcp.json / .pi/mcp.json) can run arbitrary commands,
+ * so it connects only once the project is trusted.
+ * Values support ${VAR} environment interpolation.
+ */
+
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import { Type } from 'typebox'
+
+const CONNECT_TIMEOUT_MS = 10_000
+const CALL_TIMEOUT_MS = 120_000
+const MAX_INLINE_RESULT = 50_000
+// pi's built-in tool names must never be shadowed by an MCP tool
+const RESERVED_NAMES = new Set(['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls', 'mcp'])
+
+export interface StdioServerConfig {
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+  cwd?: string
+}
+
+export interface HttpServerConfig {
+  url: string
+  headers?: Record<string, string>
+  bearerToken?: string
+  bearerTokenEnv?: string
+}
+
+export type ServerConfig = StdioServerConfig | HttpServerConfig
+
+export function interpolateEnv(value: string, env: NodeJS.ProcessEnv = process.env): string {
+  return value.replace(/\$\{(\w+)\}/g, (_, name) => env[name] ?? '')
+}
+
+/** User-scoped MCP config (the user's own; safe to load without project trust). */
+export function userConfigPaths(home: string): string[] {
+  return [path.join(home, '.claude.json'), path.join(home, '.pi', 'agent', 'mcp.json')]
+}
+
+/** Project-scoped MCP config. Loaded only for trusted projects: a server's `command` runs on connect. */
+export function projectConfigPaths(cwd: string): string[] {
+  return [path.join(cwd, '.mcp.json'), path.join(cwd, '.pi', 'mcp.json')]
+}
+
+/** All config files, later winning: user first, then project. */
+export function configPaths(cwd: string, home: string): string[] {
+  return [...userConfigPaths(home), ...projectConfigPaths(cwd)]
+}
+
+export function loadConfig(cwd: string): Record<string, ServerConfig> {
+  return loadConfigFrom(configPaths(cwd, os.homedir()))
+}
+
+export function loadConfigFrom(files: string[]): Record<string, ServerConfig> {
+  const servers: Record<string, ServerConfig> = {}
+  for (const file of files) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'))
+      Object.assign(servers, parsed.mcpServers ?? {})
+    } catch {
+      // missing or invalid file: skip silently, /mcp reports what loaded
+    }
+  }
+  return servers
+}
+
+export function formatToolName(server: string, tool: string): string {
+  return `${server}_${tool}`.replace(/-/g, '_')
+}
+
+export function normalizeSchema(schema: unknown): object {
+  const base = (schema as Record<string, unknown>) ?? {}
+  const { $schema: _dropSchema, additionalProperties: _dropAdditional, ...rest } = base
+  if (!rest.type) return { type: 'object', properties: {} }
+  return rest
+}
+
+interface McpContentBlock {
+  type: string
+  text?: string
+  data?: string
+  mimeType?: string
+  resource?: { uri?: string; text?: string }
+}
+
+export type ToolContent = { type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string }
+
+export function mapContent(content: McpContentBlock[] | undefined, structured?: unknown): ToolContent[] {
+  if (!content || content.length === 0) {
+    return [{ type: 'text', text: structured !== undefined ? JSON.stringify(structured, null, 2) : '(empty result)' }]
+  }
+  return content.map((block) => {
+    if (block.type === 'text') {
+      const text = block.text ?? ''
+      return text.length > MAX_INLINE_RESULT ? { type: 'text', text: `${text.slice(0, MAX_INLINE_RESULT)}\n[truncated ${text.length - MAX_INLINE_RESULT} chars]` } : { type: 'text', text }
+    }
+    if (block.type === 'image' && block.data) {
+      return { type: 'image', data: block.data, mimeType: block.mimeType ?? 'image/png' }
+    }
+    if (block.type === 'resource' && block.resource) {
+      return { type: 'text', text: `[Resource: ${block.resource.uri ?? 'unknown'}]\n${block.resource.text ?? ''}` }
+    }
+    return { type: 'text', text: JSON.stringify(block) }
+  })
+}
+
+function isStdio(config: ServerConfig): config is StdioServerConfig {
+  return 'command' in config
+}
+
+async function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms)
+  })
+  // If the timeout wins, `promise` stays pending; swallow any late rejection so it can never
+  // surface as an unhandled rejection that crashes the host.
+  promise.catch(() => {})
+  try {
+    return await Promise.race([promise, timeout])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+async function connect(name: string, config: ServerConfig): Promise<Client> {
+  const client = new Client({ name: 'pi-code-mcp', version: '0.1.0' })
+  if (isStdio(config)) {
+    const env: Record<string, string> = { ...(process.env as Record<string, string>) }
+    for (const [key, value] of Object.entries(config.env ?? {})) env[key] = interpolateEnv(value)
+    const transport = new StdioClientTransport({
+      command: config.command,
+      args: config.args ?? [],
+      env,
+      cwd: config.cwd?.replace(/^~(?=\/|$)/, os.homedir()),
+      stderr: 'ignore',
+    })
+    await withTimeout(client.connect(transport), CONNECT_TIMEOUT_MS, `connect ${name}`)
+    return client
+  }
+  const headers: Record<string, string> = {}
+  for (const [key, value] of Object.entries(config.headers ?? {})) headers[key] = interpolateEnv(value)
+  const token = config.bearerToken ?? (config.bearerTokenEnv ? process.env[config.bearerTokenEnv] : undefined)
+  if (token) headers.Authorization = `Bearer ${token}`
+  const url = new URL(interpolateEnv(config.url))
+  try {
+    const transport = new StreamableHTTPClientTransport(url, { requestInit: { headers } })
+    await withTimeout(client.connect(transport), CONNECT_TIMEOUT_MS, `connect ${name}`)
+    return client
+  } catch (error) {
+    if (String(error).includes('Unauthorized')) throw error
+    const fallback = new Client({ name: 'pi-code-mcp', version: '0.1.0' })
+    const transport = new SSEClientTransport(url, { requestInit: { headers } })
+    await withTimeout(fallback.connect(transport), CONNECT_TIMEOUT_MS, `connect ${name} (sse)`)
+    return fallback
+  }
+}
+
+async function listAllTools(client: Client): Promise<Array<{ name: string; description?: string; inputSchema?: unknown }>> {
+  const tools: Array<{ name: string; description?: string; inputSchema?: unknown }> = []
+  let cursor: string | undefined
+  do {
+    const page = await client.listTools({ cursor })
+    tools.push(...page.tools)
+    cursor = page.nextCursor
+  } while (cursor)
+  return tools
+}
+
+export default async function mcpExtension(pi: ExtensionAPI) {
+  const clients = new Map<string, Client>()
+  const status = new Map<string, { state: string; tools: number }>()
+  const registered = new Set<string>()
+
+  async function connectServers(servers: Record<string, ServerConfig>): Promise<void> {
+    for (const [name, config] of Object.entries(servers)) {
+      try {
+        const client = await connect(name, config)
+        clients.set(name, client)
+        const tools = await withTimeout(listAllTools(client), CONNECT_TIMEOUT_MS, `list tools ${name}`)
+        let count = 0
+        for (const tool of tools) {
+          const toolName = formatToolName(name, tool.name)
+          if (RESERVED_NAMES.has(toolName) || registered.has(toolName)) {
+            console.warn(`pi-code-mcp: skipping colliding tool name ${toolName}`)
+            continue
+          }
+          registered.add(toolName)
+          count++
+          pi.registerTool({
+            name: toolName,
+            label: `${name}: ${tool.name}`,
+            description: tool.description ?? `MCP tool ${tool.name} from ${name}`,
+            parameters: Type.Unsafe(normalizeSchema(tool.inputSchema)),
+            async execute(_id, params) {
+              const result = await withTimeout(client.callTool({ name: tool.name, arguments: params as Record<string, unknown> }), CALL_TIMEOUT_MS, toolName)
+              const content = mapContent(result.content as McpContentBlock[], result.structuredContent)
+              const details: { error?: string } = {}
+              if (result.isError) {
+                details.error = 'tool_error'
+                const hint = JSON.stringify(normalizeSchema(tool.inputSchema))
+                content.push({ type: 'text', text: `Tool reported an error. Expected input schema: ${hint}` })
+              }
+              return { content, details }
+            },
+          })
+        }
+        status.set(name, { state: 'connected', tools: count })
+      } catch (error) {
+        status.set(name, { state: `failed: ${error instanceof Error ? error.message : String(error)}`, tools: 0 })
+      }
+    }
+  }
+
+  // User config is the user's own, so connect it eagerly.
+  await connectServers(loadConfigFrom(userConfigPaths(os.homedir())))
+
+  let projectConnected = false
+  pi.on('session_start', async (_event, ctx) => {
+    // A project .mcp.json can run arbitrary commands on connect, so only honor it once the project is trusted.
+    if (!projectConnected && ctx.isProjectTrusted?.()) {
+      projectConnected = true
+      await connectServers(loadConfigFrom(projectConfigPaths(ctx.cwd)))
+    }
+
+    const connected = [...status.values()].filter((s) => s.state === 'connected')
+    const failed = [...status.entries()].filter(([, s]) => s.state !== 'connected')
+    if (connected.length > 0 || failed.length > 0) {
+      const total = connected.reduce((sum, s) => sum + s.tools, 0)
+      const failNote = failed.length > 0 ? `, ${failed.length} failed` : ''
+      ctx.ui.notify(`MCP: ${total} tools from ${connected.length} servers${failNote}`, failed.length > 0 ? 'warning' : 'info')
+    }
+  })
+
+  pi.on('session_shutdown', async () => {
+    // Close in parallel with a per-client timeout so one hung server can't stall pi's exit.
+    await Promise.all([...clients.values()].map((client) => withTimeout(client.close(), 3000, 'close').catch(() => {})))
+  })
+
+  pi.registerCommand('mcp', {
+    description: 'Show MCP server status and tools',
+    handler: async (_args, ctx) => {
+      if (status.size === 0) {
+        ctx.ui.notify('No MCP servers configured. Add them to .mcp.json, .pi/mcp.json, ~/.claude.json, or ~/.pi/agent/mcp.json', 'info')
+        return
+      }
+      const lines = [...status.entries()].map(([name, s]) => `${name}: ${s.state} (${s.tools} tools)`)
+      ctx.ui.notify(lines.join('\n'), 'info')
+    },
+  })
+}

package/extensions/memory.ts

@@ -0,0 +1,127 @@
+/**
+ * Memory Extension
+ *
+ * Claude Code style persistent memory, per project. Memories live as markdown
+ * files under ~/.pi/agent/memory/<project-slug>/ with a MEMORY.md index whose
+ * content is injected into the system prompt each session. The agent manages
+ * memories through the memory tool (save / read / delete / list).
+ */
+
+import * as fs from 'node:fs'
+import * as os from 'node:os'
+import * as path from 'node:path'
+import { StringEnum } from '@earendil-works/pi-ai'
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { Type } from 'typebox'
+
+const INDEX_FILE = 'MEMORY.md'
+
+export function projectSlug(cwd: string): string {
+  return cwd.replace(/[/\\]/g, '-').replace(/^-+/, '-')
+}
+
+export function memoryDir(cwd: string): string {
+  return path.join(os.homedir(), '.pi', 'agent', 'memory', projectSlug(cwd))
+}
+
+export function slugifyName(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 64) || 'memory'
+  )
+}
+
+/** Add or replace this memory's line in the index, keyed by its markdown link target. */
+export function upsertIndexLine(index: string, name: string, description: string): string {
+  const line = `- [${name}](${name}.md): ${description}`
+  const lines = index.split('\n').filter((l) => l.trim().length > 0 && !l.includes(`](${name}.md)`))
+  if (lines.length === 0 || !lines[0].startsWith('#')) lines.unshift('# Memory index')
+  lines.push(line)
+  return `${lines.join('\n')}\n`
+}
+
+export function removeIndexLine(index: string, name: string): string {
+  const lines = index.split('\n').filter((l) => l.trim().length > 0 && !l.includes(`](${name}.md)`))
+  return lines.length > 0 ? `${lines.join('\n')}\n` : ''
+}
+
+const MemoryParams = Type.Object({
+  action: StringEnum(['save', 'read', 'delete', 'list'] as const, { description: 'What to do' }),
+  name: Type.Optional(Type.String({ description: 'Short kebab-case memory name (save/read/delete)' })),
+  description: Type.Optional(Type.String({ description: 'One-line summary shown in the always-loaded index (save)' })),
+  content: Type.Optional(Type.String({ description: 'Full memory content in markdown (save)' })),
+})
+
+function readIndex(dir: string): string {
+  try {
+    return fs.readFileSync(path.join(dir, INDEX_FILE), 'utf-8')
+  } catch {
+    return ''
+  }
+}
+
+export default function memoryExtension(pi: ExtensionAPI) {
+  let dir = memoryDir(process.cwd())
+
+  pi.on('session_start', async (_event, ctx) => {
+    dir = memoryDir(ctx.cwd)
+    const count = readIndex(dir)
+      .split('\n')
+      .filter((l) => l.startsWith('- ')).length
+    if (count > 0) ctx.ui.notify(`Memory: ${count} memories loaded`, 'info')
+  })
+
+  pi.on('before_agent_start', async (event) => {
+    const index = readIndex(dir)
+    if (!index.trim()) return
+    return {
+      systemPrompt: `${event.systemPrompt}\n\n## Memory\n\nPersistent memories from earlier sessions (index):\n\n${index}\nUse the memory tool with action "read" to load a memory's full content when relevant.`,
+    }
+  })
+
+  pi.registerTool({
+    name: 'memory',
+    label: 'Memory',
+    description: 'Persistent memory across sessions. Save durable facts, user preferences, corrections, and project decisions that are not derivable from the code. Actions: save (name + description + content), read (name), delete (name), list.',
+    parameters: MemoryParams,
+    async execute(_id, params) {
+      const name = params.name ? slugifyName(params.name) : undefined
+      const indexPath = path.join(dir, INDEX_FILE)
+
+      if (params.action === 'save') {
+        if (!name || !params.description || !params.content) {
+          return { content: [{ type: 'text' as const, text: 'save requires name, description, and content.' }], details: {} }
+        }
+        fs.mkdirSync(dir, { recursive: true })
+        fs.writeFileSync(path.join(dir, `${name}.md`), params.content)
+        fs.writeFileSync(indexPath, upsertIndexLine(readIndex(dir), name, params.description))
+        return { content: [{ type: 'text' as const, text: `Saved memory ${name}.` }], details: {} }
+      }
+
+      if (params.action === 'read') {
+        if (!name) return { content: [{ type: 'text' as const, text: 'read requires name.' }], details: {} }
+        try {
+          const body = fs.readFileSync(path.join(dir, `${name}.md`), 'utf-8')
+          return { content: [{ type: 'text' as const, text: body }], details: {} }
+        } catch {
+          return { content: [{ type: 'text' as const, text: `No memory named ${name}.` }], details: {} }
+        }
+      }
+
+      if (params.action === 'delete') {
+        if (!name) return { content: [{ type: 'text' as const, text: 'delete requires name.' }], details: {} }
+        fs.rmSync(path.join(dir, `${name}.md`), { force: true })
+        const remaining = removeIndexLine(readIndex(dir), name)
+        if (remaining) fs.writeFileSync(indexPath, remaining)
+        else fs.rmSync(indexPath, { force: true })
+        return { content: [{ type: 'text' as const, text: `Deleted memory ${name}.` }], details: {} }
+      }
+
+      const index = readIndex(dir)
+      return { content: [{ type: 'text' as const, text: index.trim() || 'No memories saved for this project yet.' }], details: {} }
+    },
+  })
+}

package/extensions/notify.ts

@@ -0,0 +1,52 @@
+/**
+ * Pi Notify Extension
+ *
+ * Sends a native terminal notification when Pi agent is done and waiting for input.
+ * Supports multiple terminal protocols:
+ * - OSC 777: Ghostty, iTerm2, WezTerm, rxvt-unicode
+ * - OSC 99: Kitty
+ * - Windows toast: Windows Terminal (WSL)
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+
+function windowsToastScript(title: string, body: string): string {
+  const type = 'Windows.UI.Notifications'
+  const mgr = `[${type}.ToastNotificationManager, ${type}, ContentType = WindowsRuntime]`
+  const template = `[${type}.ToastTemplateType]::ToastText01`
+  const toast = `[${type}.ToastNotification]::new($xml)`
+  return [`${mgr} > $null`, `$xml = [${type}.ToastNotificationManager]::GetTemplateContent(${template})`, `$xml.GetElementsByTagName('text')[0].AppendChild($xml.CreateTextNode('${body}')) > $null`, `[${type}.ToastNotificationManager]::CreateToastNotifier('${title}').Show(${toast})`].join('; ')
+}
+
+function notifyOSC777(title: string, body: string): void {
+  process.stdout.write(`\x1b]777;notify;${title};${body}\x07`)
+}
+
+function notifyOSC99(title: string, body: string): void {
+  // Kitty OSC 99: i=notification id, d=0 means not done yet, p=body for second part
+  process.stdout.write(`\x1b]99;i=1:d=0;${title}\x1b\\`)
+  process.stdout.write(`\x1b]99;i=1:p=body;${body}\x1b\\`)
+}
+
+function notifyWindows(title: string, body: string): void {
+  const { execFile } = require('node:child_process')
+  // The callback captures a spawn failure (e.g. powershell.exe missing) instead of
+  // letting an unhandled 'error' event crash the host process.
+  execFile('powershell.exe', ['-NoProfile', '-Command', windowsToastScript(title, body)], () => {})
+}
+
+function notify(title: string, body: string): void {
+  if (process.env.WT_SESSION) {
+    notifyWindows(title, body)
+  } else if (process.env.KITTY_WINDOW_ID) {
+    notifyOSC99(title, body)
+  } else {
+    notifyOSC777(title, body)
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on('agent_end', async () => {
+    notify('Pi', 'Ready for input')
+  })
+}