@aliou/pi-dev-kit 0.4.9 → 0.5.0

package/src/skills/pi-extension/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: pi-extension
+description: Create, update, and publish Pi extensions. Use when working on extensions in this repository.
+---
+
+# Pi Extension Development
+
+Guide for creating and maintaining Pi extensions. Read the relevant reference files before implementing.
+
+## Key Imports
+
+```typescript
+// Core types
+import type { ExtensionAPI, ExtensionContext, ToolDefinition, ProviderDefinition } from "@mariozechner/pi-coding-agent";
+
+// Schema (TypeBox)
+import { Type } from "@mariozechner/pi-coding-agent";
+
+// TUI components
+import type { Component, Theme } from "@mariozechner/pi-tui";
+import { Text, Box, Container, Markdown, SelectList } from "@mariozechner/pi-tui";
+
+// Tool UI components (from @aliou/pi-utils-ui)
+import { ToolCallHeader, ToolBody, ToolFooter } from "@aliou/pi-utils-ui";
+
+// Rendering utilities
+import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
+
+// General utilities
+import { truncateHead, highlightCode, getLanguageFromPath, DynamicBorder, BorderedLoader } from "@mariozechner/pi-coding-agent";
+```
+
+## Workflow
+
+### Creating a New Extension
+
+1. Read `references/structure.md` for the project layout and package.json template.
+2. Create the entry point (`src/index.ts`) with a default export function.
+3. Decide what the extension provides:
+   - **Tools** (LLM-callable): Read `references/tools.md`.
+   - **Commands** (user-invoked): Read `references/commands.md`.
+   - **Providers** (LLM backends): Read `references/providers.md`.
+   - **Hooks** (event handlers): Read `references/hooks.md`. Includes both `tool_call` blocking hooks and spawn hooks for transparent command rewriting via `createBashTool`.
+4. Read `references/modes.md` for mode-awareness guidelines. Every extension must handle Interactive, RPC, and Print modes.
+5. If the extension displays rich UI: Read `references/components.md` for TUI components and `references/messages.md` for message display patterns.
+6. If the extension tracks state: Read `references/state.md`.
+7. For less common APIs: Read `references/additional-apis.md`.
+8. If the extension adds a tool that competes with a natural bash fallback (process managers, CI watchers, search tools): inject system prompt guidance. Read the **Guidance Injection Pattern** section in `references/additional-apis.md`.
+9. Before publishing: Read `references/publish.md` and `references/documentation.md`.
+
+### Modifying an Existing Extension
+
+1. Read the extension's `index.ts` to understand its structure.
+2. Read the relevant reference file for the area you are modifying.
+3. Check `references/modes.md` if adding any UI interaction.
+4. Run type checking after changes.
+
+## Reference Files
+
+| File | Content |
+|---|---|
+| `references/structure.md` | Project layout, package.json, tsconfig, biome.json, config.ts, entry point patterns (including acceptable exceptions), API key pattern, imports |
+| `references/tools.md` | Tool registration, execute signature, parameters, streaming, rendering, naming, renderCall/renderResult UI guidelines |
+| `references/hooks.md` | Events, blocking/cancelling, input transformation, system prompt modification, bash spawn hooks (command rewriting) |
+| `references/commands.md` | Command registration, three-tier pattern, component extraction |
+| `references/components.md` | TUI components (pi-tui + pi-coding-agent), custom(), theme styling, keyboard handling |
+| `references/providers.md` | Provider registration, model definition, compat field, API key gating |
+| `references/modes.md` | Mode behavior matrix, ctx.hasUI, dialog vs fire-and-forget, three-tier pattern |
+| `references/messages.md` | sendMessage, registerMessageRenderer, notify, when to use each |
+| `references/state.md` | appendEntry, state reconstruction, appendEntry vs sendMessage |
+| `references/additional-apis.md` | Shortcuts, flags, exec, sendUserMessage, session name, labels, model control, EventBus, theme, UI customization, system prompt guidance injection |
+| `references/publish.md` | npm publishing, changesets (manual file format + CI automation), GitHub Actions publish workflow, first-time setup, NPM_TOKEN, pre-publish checklist |
+| `references/testing.md` | Local development, type checking, manual testing, debugging |
+| `references/documentation.md` | README template, what to document, changelog |
+
+## Reference Extensions
+
+When implementing, look at these existing extensions for patterns:
+
+**Standalone repos (recommended structure):**
+- `pi-linkup` (`/Users/alioudiallo/code/src/github.com/aliou/pi-linkup/`): Tools wrapping a third-party API. Has tools, a command, custom message rendering, API key gating, system prompt guidance injection (`src/guidance.ts` + `src/hooks/system-prompt.ts`).
+- `pi-synthetic` (`/Users/alioudiallo/code/src/github.com/aliou/pi-synthetic/`): Provider + tools. Has a provider with models, a command with `custom()` component, API key gating, async entry point.
+- `pi-processes` (`/Users/alioudiallo/code/src/github.com/aliou/pi-processes/`): Multi-action tool with system prompt guidance injection (`src/guidance.ts` + `src/hooks/system-prompt.ts`), config toggle, background blocker hook.
+
+**Monorepo extensions (simpler structure):**
+- `extensions/defaults/` in this repo: Simple tool registration (get_current_time).
+- `extensions/guardrails/` in this repo: Event hooks (tool_call blocking). Has `hooks/`, `commands/`, `components/`, `utils/` directories with config types in `config.ts`.
+- `extensions/toolchain/` in this repo: Bash spawn hooks (command rewriting via `createBashTool`) combined with tool_call blockers. Has `blockers/`, `rewriters/`, `commands/`, `utils/` directories.
+- `extensions/processes/` in this repo: Multi-action tool with StringEnum parameters.
+
+## Critical Rules
+
+1. **Execute parameter order**: `(toolCallId, params, signal, onUpdate, ctx)`. Signal before onUpdate.
+2. **Always use `onUpdate?.()`**: Optional chaining. The parameter can be `undefined`.
+3. **No `.js` in imports**: Use bare module paths (`./tools/my-tool`, not `./tools/my-tool.js`).
+4. **Mode awareness**: Every `ctx.ui.custom()` call needs an RPC fallback (use `select`/`confirm`/`notify` -- they work in RPC). Do not use `done(undefined)` for normal interactive close paths when you detect fallback with `result === undefined`; use explicit sentinels (`null`, `"closed"`, boolean). Every `tool_call` hook with dialogs needs a `ctx.hasUI` check.
+5. **API key gating**: Check before registering tools that require the key. Providers handle missing keys internally via their `models()` function.
+6. **Tool naming**: Prefix with API name for third-party integrations (`linkup_web_search`). No prefix for internal tools (`get_current_time`).
+7. **Tool call header pattern**: Keep `renderCall` consistent: first line `[Tool Name]: [Action] [Main arg] [Option args]`, extra lines for long args. Use display names, not raw tool IDs.
+8. **Deterministic call rendering**: Build `renderCall` with a stable extraction order (action → main arg → option args → long args), process-style. Same input should produce same header layout.
+9. **Long args placement**: Put long prompt/task/question/context strings on following lines. Keep first line scannable.
+10. **Result layout consistency**: In `renderResult`, handle `isPartial` first, start final output with a clear state summary, use `expanded` for compact-vs-full detail, and keep one blank line before any footer.
+11. **peerDependencies**: Any package Pi already ships (`@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`, `@mariozechner/pi-ai`) must be listed in `peerDependencies` with `optional: true` in `peerDependenciesMeta` if imported at runtime. Without `optional: true`, npm 7+ auto-installs peers, adding hundreds of packages on every install even though Pi already provides them. Keep them in `devDependencies` too for local type checking — `pnpm install` installs peers, so development is unaffected. Use `>=CURRENT_VERSION` range, not `*`.
+12. **Check existing components**: Before creating a new TUI component, check if `pi-tui` or `pi-coding-agent` already exports one that fits.
+13. **Forward abort signals**: Always pass `signal` through to `fetch()`, `pi.exec()`, and API client methods. A tool that ignores its signal prevents cancellation from reaching the underlying operation. Never prefix with `_signal` unless the tool truly has no async work to cancel.
+14. **Never use Node child_process APIs**: Do not use `child_process.exec`, `execSync`, `spawn`, `spawnSync`, `execFile`, or `execFileSync` to run binaries or shell scripts. Always use `pi.exec()`. `pi.exec` handles CWD, signal propagation, and output capture consistently. The only exception is if you need a long-lived streaming process with stdin/stdout piping that `pi.exec` cannot support — document the reason in code comments.
+15. **Never use `homedir()` for pi paths**: Use the SDK helpers from `@mariozechner/pi-coding-agent` instead. They respect the `PI_CODING_AGENT_DIR` env var which is used for testing and custom setups. Key functions: `getAgentDir()`, `getSettingsPath()`, `getSessionsDir()`, `getPromptsDir()`, `getToolsDir()`, `getCustomThemesDir()`, `getModelsPath()`, `getAuthPath()`, `getBinDir()`, `getDebugLogPath()`. All exported from the main package entry point.
+16. **Config uses the interface pattern**: `config.ts` defines two TypeScript interfaces (`RawConfig` with all fields optional, `ResolvedConfig` with all fields required) and a `ConfigLoader<Raw, Resolved>` instance. Do not use TypeBox schemas for config types.
+17. **Entry point deviations must be documented**: The standard entry point pattern is load config → check `enabled` → register. Deviations (no config, API-key-first ordering, no `enabled` toggle) are acceptable when justified, but must be noted in `AGENTS.md`.
+
+## Checklist
+
+Before considering an extension complete:
+
+- [ ] Entry point has correct default export signature.
+- [ ] All tools have correct execute parameter order.
+- [ ] All `onUpdate` calls use optional chaining.
+- [ ] No `.js` file extensions in imports.
+- [ ] `renderCall` uses a consistent first-line pattern (tool, action if any, main arg, options).
+- [ ] `renderCall` arg extraction is deterministic (action → main arg → option args → long args).
+- [ ] Long call arguments are moved to follow-up lines, not crammed into first line.
+- [ ] `renderResult` handles `isPartial`, starts with a clear state summary, and uses `expanded` for compact-vs-full detail.
+- [ ] If result includes a footer, there is a blank line above it.
+- [ ] `renderResult` handles errors from thrown exceptions: checks for missing expected fields in `details` (framework passes `{}`, not `undefined`), extracts error message from `content`.
+- [ ] `ctx.ui.custom()` calls have RPC fallback, and interactive close/cancel paths do not rely on `done(undefined)` when fallback detection uses `result === undefined`.
+- [ ] `tool_call` hooks check `ctx.hasUI` before dialog methods.
+- [ ] Fire-and-forget methods (notify, setStatus, etc.) are used without hasUI guards.
+- [ ] If using custom message renderers: collapsed view is scannable, expanded view adds depth, and renderer has plain-text fallback when `details` is missing.
+- [ ] `signal` is forwarded to all async operations (fetch, `pi.exec`, API clients). No unused `_signal`.
+- [ ] Missing API keys produce a notification, not a crash.
+- [ ] If in a monorepo: package doesn't depend on private workspace packages (run `pnpm run check:public-deps` if available).
+- [ ] `pnpm typecheck` passes.
+- [ ] No `child_process` imports -- uses `pi.exec()` for shell commands.
+- [ ] No `homedir()` calls for pi paths -- uses SDK helpers (`getAgentDir()`, etc.).
+- [ ] README documents tools, commands, env vars.
+- [ ] `@mariozechner/pi-tui` (and any other Pi-provided package) is in `peerDependencies` with `optional: true` if imported at runtime, not just `devDependencies`.
+- [ ] `prepare` script is `"[ -d .git ] && husky || true"`, not bare `"husky"`.
+- [ ] `config.ts` uses `ConfigLoader<Raw, Resolved>` with TypeScript interfaces, not TypeBox schemas.
+- [ ] If deviating from the standard entry point pattern (load-config → check-enabled → register), the reason is documented in `AGENTS.md`.
+- [ ] If the extension adds a tool that competes with a bash fallback: guidance is injected via `src/guidance.ts` + `src/hooks/system-prompt.ts`, with a `systemPromptGuidance` config toggle defaulting to `true`.

package/src/skills/pi-extension/references/additional-apis.md

@@ -0,0 +1,264 @@
+# Additional APIs
+
+These APIs are available on `ExtensionAPI` and `ExtensionContext` but are less commonly used. Each is shown with a minimal example.
+
+When you implement something using one of these APIs, update this skill reference with a fuller example based on your actual usage.
+
+## Shortcuts
+
+Register global keyboard shortcuts:
+
+```typescript
+pi.registerShortcut("ctrl+shift+p", {
+  description: "Toggle plan mode",
+  handler: async (ctx) => {
+    planModeEnabled = !planModeEnabled;
+    ctx.ui.setStatus("plan", planModeEnabled ? "Plan Mode" : "");
+  },
+});
+```
+
+Shortcuts work only in Interactive mode.
+
+## Flags
+
+Register boolean flags that persist across sessions:
+
+```typescript
+// Register
+pi.registerFlag("auto-commit", {
+  description: "Auto-commit after each turn",
+  default: false,
+});
+
+// Read (in any handler)
+const autoCommit = pi.getFlag("auto-commit");
+```
+
+Users toggle flags with `/flag auto-commit` in the input editor.
+
+## sendUserMessage
+
+Inject a user message into the conversation programmatically:
+
+```typescript
+pi.sendUserMessage("Please summarize what we just discussed");
+```
+
+This triggers a full agent turn as if the user typed the message. Useful for file watchers, timers, or other automated triggers.
+
+## Session Name
+
+Set or get a name for the current session (shown in the session selector):
+
+```typescript
+pi.setSessionName("Feature: Auth Refactor");
+const name = pi.getSessionName();
+```
+
+## Labels
+
+Set a label on a specific session entry (shown in `/tree` view):
+
+```typescript
+pi.setLabel(entryId, "checkpoint: before refactor");
+```
+
+## exec
+
+Run a shell command and get the result. This is the **only** way to run external binaries or shell scripts from an extension.
+
+```typescript
+const result = await pi.exec("git status --porcelain", { cwd: process.cwd() });
+// result: { stdout, stderr, exitCode }
+```
+
+Useful for git operations, environment checks, running CLI tools, etc.
+
+**Do not use Node `child_process` APIs** (`exec`, `execSync`, `spawn`, `spawnSync`, `execFile`, `execFileSync`). `pi.exec` handles CWD resolution, output capture, and integrates with the extension lifecycle. Using `child_process` directly bypasses these guarantees and creates inconsistent behavior across environments.
+
+The only exception is a long-lived streaming process that requires direct stdin/stdout piping — document the reason in code comments if this applies.
+
+## Active Tools
+
+Get or set which tools are currently active:
+
+```typescript
+const tools = pi.getActiveTools(); // string[]
+pi.setActiveTools(["bash", "read", "write", "my_custom_tool"]);
+```
+
+Setting active tools restricts which tools the LLM can use.
+
+## Model Control
+
+```typescript
+// Set the active model
+pi.setModel("anthropic/claude-sonnet-4-20250514");
+
+// Get/set thinking level
+const level = pi.getThinkingLevel(); // "none" | "low" | "medium" | "high"
+pi.setThinkingLevel("high");
+```
+
+## System Prompt
+
+Read or modify the system prompt (typically in `before_agent_start`):
+
+```typescript
+pi.on("before_agent_start", async (_event, ctx) => {
+  const prompt = ctx.getSystemPrompt();
+  ctx.setSystemPrompt(prompt + "\n\nExtra instructions.");
+});
+```
+
+The system prompt resets each turn, so modifications are not cumulative.
+
+### Guidance Injection Pattern
+
+Extensions that add tools or behavioral patterns the agent may not know how to use correctly should inject guidance into the system prompt. Without it, agents fall back to bash workarounds even when a better tool is available.
+
+**When to inject guidance:**
+- Your extension adds a tool that competes with a natural bash fallback (e.g. a process manager, a CI watcher, a search tool)
+- Correct usage depends on subtle conditions (alert flags, when-not-to-use, alert vs. poll)
+- You have observed agents ignoring the tool or reaching for `bash` instead
+
+**When not to:**
+- The tool description alone is self-explanatory
+- The tool has no plausible bash alternative
+
+**Structure: three files**
+
+`src/guidance.ts` — the guidance text as a named export:
+
+```typescript
+export const MY_EXTENSION_GUIDANCE = `
+## My Extension
+
+Use the \`my_tool\` tool for X. Don't use bash for X.
+
+**Use \`my_tool\` when:**
+- Situation A
+- Situation B
+
+**Use \`bash\` when:**
+- You need the result immediately to proceed (quick commands that finish in seconds)
+
+**Never do this:**
+\`\`\`bash
+workaround_command  # loses observability
+\`\`\`
+
+**Do this instead:**
+\`\`\`
+my_tool({ action: "start", ... })
+\`\`\`
+`;
+```
+
+`src/hooks/system-prompt.ts` — the hook:
+
+```typescript
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { configLoader } from "../config";
+import { MY_EXTENSION_GUIDANCE } from "../guidance";
+
+export function registerGuidance(pi: ExtensionAPI): void {
+  pi.on("before_agent_start", async (event) => {
+    const config = configLoader.getConfig();
+    if (!config.systemPromptGuidance) return;
+
+    return {
+      systemPrompt: `${event.systemPrompt}\n${MY_EXTENSION_GUIDANCE}`,
+    };
+  });
+}
+```
+
+`src/config.ts` — add the toggle (default `true`):
+
+```typescript
+export interface MyExtensionConfig {
+  // ...
+  /** Inject tool guidance into the system prompt each turn. Default: true. */
+  systemPromptGuidance?: boolean;
+}
+```
+
+Call `registerGuidance(pi)` from your hooks setup function.
+
+**What makes guidance effective:**
+
+- Lead with the decision rule: **when to use AND when not to use**. The when-not-to-use is as important — it gives the agent permission to keep using `bash` for quick tasks and prevents overcorrection.
+- Name anti-patterns explicitly by their exact form (`cmd &`, `nohup`, `sleep 30 &&`). Abstract descriptions ("don't use bash workarounds") are ignored.
+- Use 2–3 tight code examples. More than that dilutes attention; fewer leave the pattern underspecified.
+- Keep the guidance section header (`## My Extension`) so it reads as a named capability, not a restriction.
+- Avoid stacking emphasis markers (`NEVER`, `ALWAYS`, `IMPORTANT`). One or two land; more are ignored.
+
+**Reference implementations:** `pi-linkup` (`src/hooks/system-prompt.ts`, `src/guidance.ts`) and `pi-processes` (`src/hooks/system-prompt.ts`, `src/guidance.ts`).
+
+## Compaction
+
+Trigger compaction programmatically:
+
+```typescript
+await pi.compact();
+```
+
+## Shutdown
+
+Shut down pi gracefully:
+
+```typescript
+pi.shutdown();
+```
+
+## EventBus
+
+Inter-extension communication via a shared event bus:
+
+```typescript
+// Extension A: emit
+pi.events.emit("my-extension:data-ready", { items: [...] });
+
+// Extension B: listen
+pi.events.on("my-extension:data-ready", (data) => {
+  console.log("Received:", data.items.length, "items");
+});
+```
+
+Namespace event names with your extension name to avoid collisions. The event bus is supplementary -- most extensions do not need it. Use it when two extensions need to coordinate.
+
+## Theme Control
+
+```typescript
+// Get current and available themes
+const current = ctx.ui.getTheme();
+const all = ctx.ui.getAllThemes();
+
+// Set theme
+const result = ctx.ui.setTheme("catppuccin-mocha");
+// result: { success: boolean, error?: string }
+```
+
+## UI Customization
+
+```typescript
+// Replace the footer
+ctx.ui.setFooter((maxWidth, theme) => {
+  return theme.fg("muted", "Custom footer content");
+});
+
+// Replace the startup header
+ctx.ui.setHeader((maxWidth, theme) => {
+  return theme.fg("accent", "My Custom Header");
+});
+
+// Set the editor component
+ctx.ui.setEditorComponent((tui, theme, kb) => {
+  return new CustomEditor(tui, theme, kb);
+});
+
+// Prefill the editor
+ctx.ui.setEditorText("Prefilled content");
+```

package/src/skills/pi-extension/references/commands.md

@@ -0,0 +1,100 @@
+# Commands
+
+Commands are user-invoked actions triggered with `/command-name` in the input editor.
+
+## Registration
+
+```typescript
+pi.registerCommand("my-command", {
+  description: "What this command does",
+  handler: async (args, ctx) => {
+    // args: string (everything after the command name)
+    // ctx: ExtensionContext
+  },
+});
+```
+
+## Command Context
+
+The `ctx` parameter provides the same `ExtensionContext` as hooks, with access to `ctx.ui`, `ctx.hasUI`, `ctx.cwd`, etc.
+
+Commands are interactive by nature (the user typed them), so `ctx.hasUI` is usually `true`. However, commands can also be invoked programmatically (for example via RPC), so the three-tier pattern still applies.
+
+## Simple Command
+
+```typescript
+pi.registerCommand("balance", {
+  description: "Check API balance",
+  handler: async (_args, ctx) => {
+    const balance = await fetchBalance();
+    ctx.ui.notify(`Balance: $${balance.toFixed(2)}`, "info");
+  },
+});
+```
+
+## Command with Rich Display
+
+When a command needs a rich TUI display, use the three-tier pattern from `references/modes.md`:
+
+```typescript
+pi.registerCommand("quotas", {
+  description: "Show API quotas",
+  handler: async (_args, ctx) => {
+    const quotas = await fetchQuotas();
+
+    // Print mode
+    if (!ctx.hasUI) {
+      console.log(formatQuotasPlain(quotas));
+      return;
+    }
+
+    // Interactive mode: full TUI component.
+    // Use explicit sentinel value for close/cancel, not undefined.
+    const result = await ctx.ui.custom<"closed">((tui, theme, _kb, done) => {
+      return new QuotasDisplay(theme, quotas, () => done("closed"));
+    });
+
+    // RPC mode: custom() returns undefined by design.
+    if (result === undefined) {
+      ctx.ui.notify(formatQuotasPlain(quotas), "info");
+    }
+  },
+});
+```
+
+Do not use `done(undefined)` in normal interactive close paths if you rely on `result === undefined` to detect RPC fallback.
+
+## Extracting Components
+
+Keep command handlers thin. Extract the TUI component into a separate file:
+
+```
+src/
+  commands/
+    quotas.ts              # Handler + formatQuotasPlain
+  components/
+    quotas-display.ts      # QuotasDisplay component class
+```
+
+The component file should export the component class. The command file imports it and wires up the handler.
+
+## Arguments
+
+The `args` parameter is the raw string after the command name. Parse it yourself:
+
+```typescript
+handler: async (args, ctx) => {
+  const parts = args.trim().split(/\s+/);
+  const subcommand = parts[0];
+  // ...
+},
+```
+
+## Command vs Tool
+
+| Aspect | Command | Tool |
+|---|---|---|
+| Invoked by | User (typing `/name`) | LLM (during a turn) |
+| Purpose | User-facing actions, settings, displays | LLM capabilities |
+| UI access | Full (user is present) | Limited (LLM is driving) |
+| Return value | void | `AgentToolResult` (output for LLM) |

package/src/skills/pi-extension/references/components.md

@@ -0,0 +1,166 @@
+# Components
+
+TUI components render custom UI in the terminal. They are used in `ctx.ui.custom()`, `renderResult`, and other display contexts.
+
+## Component Interface
+
+```typescript
+import type { Component, Theme } from "@mariozechner/pi-tui";
+
+class MyComponent implements Component {
+  render(maxWidth: number, maxHeight: number): string {
+    return "Hello from my component";
+  }
+
+  // Optional: handle keyboard input
+  handleInput?(key: string): void;
+}
+```
+
+`render` is called whenever the TUI needs to repaint. Return a string (can include ANSI codes via theme helpers). `maxWidth` and `maxHeight` are the available terminal dimensions.
+
+## Available Components from pi-tui
+
+Before creating custom components, check if an existing one fits your need:
+
+| Component | Description |
+|---|---|
+| `Text` | Styled text with wrapping |
+| `Box` | Container with borders and padding |
+| `Container` | Vertical/horizontal layout |
+| `Spacer` | Empty space |
+| `Input` | Text input field |
+| `Editor` | Multi-line text editor |
+| `SelectList` | Scrollable selection list |
+| `SettingsList` | Key-value settings display |
+| `Loader` | Loading spinner |
+| `CancellableLoader` | Loader with cancel support |
+| `Markdown` | Markdown rendering |
+| `Image` | Image rendering (kitty/sixel protocol) |
+| `TruncatedText` | Text with line limit and expand/collapse |
+
+Import from `@mariozechner/pi-tui`:
+
+```typescript
+import { Text, Box, Container, SelectList } from "@mariozechner/pi-tui";
+```
+
+## Utility Components from pi-coding-agent
+
+These are higher-level components for common extension patterns:
+
+| Component | Description |
+|---|---|
+| `DynamicBorder` | Border that adjusts to content width |
+| `BorderedLoader` | Loader inside a bordered box with optional cancel |
+| `ToolExecutionComponent` | Standard tool execution display |
+
+Import from `@mariozechner/pi-coding-agent`:
+
+```typescript
+import { DynamicBorder, BorderedLoader } from "@mariozechner/pi-coding-agent";
+```
+
+## Using ctx.ui.custom()
+
+`custom()` displays a full-screen component and returns when the component calls `done()`.
+
+```typescript
+const result = await ctx.ui.custom<string>((tui, theme, kb, done) => {
+  return new MyPickerComponent(theme, items, (selected) => done(selected));
+});
+```
+
+Parameters passed to the factory:
+- `tui`: The TUI instance (rarely needed directly).
+- `theme`: Current theme for styling.
+- `kb`: Keybinding configuration.
+- `done(value)`: Call to close the component and return the value.
+
+The generic type (`<string>` above) is the type of value passed to `done()`.
+
+Mode behavior:
+- Interactive: returns the value passed to `done(value)`.
+- RPC: returns `undefined` (by design; no local TUI).
+- Print: returns `undefined`.
+
+Important: `undefined` is ambiguous. In Interactive mode you can also produce it yourself by calling `done(undefined)`. If you need to detect RPC fallback, use explicit non-undefined sentinels for interactive close paths (`null`, `"closed"`, `false`, etc.).
+
+See `references/modes.md` for the three-tier pattern.
+
+## Theme Styling
+
+All render functions receive a `theme` object for consistent styling:
+
+```typescript
+// Foreground colors
+theme.fg("toolTitle", text)    // Tool names
+theme.fg("accent", text)       // Highlights
+theme.fg("success", text)      // Green
+theme.fg("error", text)        // Red
+theme.fg("warning", text)      // Yellow
+theme.fg("muted", text)        // Secondary text
+theme.fg("dim", text)          // Tertiary text
+
+// Text styles
+theme.bold(text)
+theme.italic(text)
+theme.strikethrough(text)
+```
+
+## `renderResult` is not a Component
+
+`renderResult` is a plain render function. It returns a string (or `undefined`) and is not an interactive `Component` class.
+
+```typescript
+renderResult(result, { expanded, isPartial }, theme) {
+  if (isPartial) return theme.fg("muted", "Loading...");
+
+  const items = result.details?.items ?? [];
+  const visible = expanded ? items : items.slice(0, 5);
+  return [
+    theme.fg("success", `Found ${items.length} results`),
+    ...visible.map((item: string) => `  ${theme.fg("accent", item)}`),
+  ].join("\n");
+},
+```
+
+For full `renderCall`/`renderResult` formatting rules, follow `references/tools.md` (Tool UI Rendering Guidelines + consistency contract).
+
+## Keyboard Handling in custom()
+
+Interactive components handle keyboard input through `handleInput`:
+
+```typescript
+class MyComponent implements Component {
+  private done: (value: string | null) => void;
+
+  constructor(done: (value: string | null) => void) {
+    this.done = done;
+  }
+
+  handleInput(key: string) {
+    if (key === "escape" || key === "q") {
+      this.done(null); // Cancel (explicit sentinel)
+    }
+    if (key === "return") {
+      this.done("selected"); // Confirm
+    }
+  }
+
+  render(maxWidth: number, maxHeight: number): string {
+    return "Press Enter to confirm, Esc to cancel";
+  }
+}
+```
+
+## Code Highlighting
+
+For displaying code in renderers:
+
+```typescript
+import { highlightCode, getLanguageFromPath } from "@mariozechner/pi-coding-agent";
+
+const lang = getLanguageFromPath("/path/to/file.ts"); // "typescript"
+const highlighted = highlightCode(code, lang, theme);
+```