@aliou/pi-dev-kit 0.4.9 → 0.5.0

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

@@ -0,0 +1,54 @@
+# Documentation
+
+Every published extension should have a README that explains what it does, how to set it up, and what it provides.
+
+## README Template
+
+```markdown
+# pi-my-extension
+
+Brief description of the extension.
+
+## Setup
+
+\`\`\`bash
+pi install @scope/pi-my-extension
+\`\`\`
+
+### Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `MY_API_KEY` | Yes | API key from [provider](https://...) |
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `my_tool` | What it does |
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `/my-command` | What it does |
+
+## Providers
+
+| Provider | Models |
+|---|---|
+| `my-provider` | model-a, model-b |
+```
+
+## What to Document
+
+- **Installation**: `pi install` command.
+- **Environment variables**: Every required and optional env var, with links to where to get them.
+- **Tools**: Name and description of each registered tool. Include example usage if non-obvious.
+- **Commands**: Name and description of each registered command.
+- **Providers**: Provider name and available models (if the extension registers a provider).
+- **Limitations**: Known limitations, unsupported modes, or missing features.
+
+## Changelog
+
+If using changesets, the CHANGELOG.md is generated automatically. Each changeset entry should describe what changed from the user's perspective, not implementation details.

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

@@ -0,0 +1,244 @@
+# Hooks (Events)
+
+Hooks let extensions react to lifecycle events. They are registered with `pi.on(eventName, handler)`.
+
+## Event Reference
+
+### Session Events
+
+| Event | When | Can Cancel | Payload |
+|---|---|---|---|
+| `session_start` | New session created | No | `{}` |
+| `session_switch` | Switched to different session | No | `{ reason: "new" \| "switch" \| "fork" }` |
+| `session_before_switch` | Before switching sessions | Yes (`{ cancel: true }`) | `{ reason: "new" \| "switch" \| "fork" }` |
+| `session_before_fork` | Before forking a session | Yes (`{ cancel: true }`) | `{}` |
+| `session_fork` | After session was forked | No | `{}` |
+| `session_shutdown` | Pi is shutting down | No | `{}` |
+| `session_before_compact` | Before compaction | Yes (return custom summary string) | `{ summary: string }` |
+
+### Agent Events
+
+| Event | When | Payload |
+|---|---|---|
+| `before_agent_start` | Before agent turn starts | `{}` |
+| `agent_start` | Agent turn started | `{}` |
+| `turn_start` | Turn begins processing | `{}` |
+| `turn_end` | Turn finishes processing | `{}` |
+| `model_select` | User changed the model | `{ model: string }` |
+
+### Tool Events
+
+| Event | When | Can Block | Payload |
+|---|---|---|---|
+| `tool_call` | Before a tool executes | Yes (`{ block: true, reason }`) | `{ toolName, toolCallId, input }` |
+
+### Input Events
+
+| Event | When | Can Transform | Payload |
+|---|---|---|---|
+| `input` | User submitted a message | Yes (return transformed text) | `{ text: string }` |
+
+### Bash Events
+
+| Event | When | Can Modify | Payload |
+|---|---|---|---|
+| `user_bash` | Before bash command runs | Yes (return modified command/cwd/env) | `{ command, cwd }` |
+
+## Handler Signature
+
+```typescript
+pi.on("event_name", async (event, ctx) => {
+  // event: event-specific payload
+  // ctx: ExtensionContext (hasUI, ui methods, cwd, model, etc.)
+});
+```
+
+The handler receives the event payload and an `ExtensionContext`. The context provides access to UI methods, the current working directory, model info, and more.
+
+## Blocking and Cancelling
+
+Some events let you prevent the default behavior by returning an object.
+
+### Blocking Tool Calls
+
+```typescript
+pi.on("tool_call", async (event, ctx) => {
+  if (event.toolName === "bash" && event.input.command.includes("rm -rf /")) {
+    // Check ctx.hasUI before prompting -- see references/modes.md
+    if (!ctx.hasUI) {
+      return { block: true, reason: "Blocked: dangerous command (no UI to confirm)" };
+    }
+
+    const confirmed = await ctx.ui.confirm(
+      "Dangerous Command",
+      `Allow: ${event.input.command}?`
+    );
+    if (!confirmed) {
+      return { block: true, reason: "Blocked by user" };
+    }
+  }
+  return undefined; // Allow the tool call
+});
+```
+
+### Cancelling Session Operations
+
+```typescript
+pi.on("session_before_switch", async (event, ctx) => {
+  if (event.reason === "new" && ctx.hasUI) {
+    const confirmed = await ctx.ui.confirm("Clear session?", "All messages will be lost.");
+    if (!confirmed) {
+      return { cancel: true };
+    }
+  }
+});
+```
+
+### Custom Compaction
+
+```typescript
+pi.on("session_before_compact", async (event, ctx) => {
+  // Return a custom summary string to replace the default compaction
+  return `Custom summary: ${event.summary.slice(0, 200)}...`;
+});
+```
+
+## Transforming Input
+
+```typescript
+pi.on("input", async (event, ctx) => {
+  if (event.text.startsWith("!")) {
+    return event.text.slice(1).toUpperCase();
+  }
+  return undefined; // No transformation
+});
+```
+
+## Modifying Bash Commands
+
+```typescript
+pi.on("user_bash", async (event, ctx) => {
+  return {
+    command: event.command,
+    cwd: "/sandboxed/directory",
+    env: { ...process.env, SANDBOX: "true" },
+  };
+});
+```
+
+## before_agent_start
+
+This event fires before each agent turn. It is commonly used to modify the system prompt.
+
+The handler receives a `BeforeAgentStartEvent` with a `systemPrompt` field containing the current prompt. Return a `{ systemPrompt }` object to replace it. If multiple extensions return a modified prompt, they are chained.
+
+```typescript
+pi.on("before_agent_start", async (event) => {
+  return {
+    systemPrompt: event.systemPrompt + "\n\nAlways respond as a pirate.",
+  };
+});
+```
+
+Return `undefined` to leave the prompt unchanged.
+
+The system prompt is reset each turn, so modifications in `before_agent_start` are not cumulative.
+
+To access flags inside hooks, use `pi.getFlag()` (see `references/additional-apis.md`).
+
+## Bash Spawn Hook (Command Rewriting)
+
+The `createBashTool` function lets you replace the built-in bash tool with one that transparently rewrites commands before shell execution. This is different from `tool_call` blocking -- the agent never sees that the command was rewritten.
+
+Use spawn hooks when you have a clear rewrite target (e.g. `npm` -> `pnpm`). Use `tool_call` blocking when you need to stop a command entirely or show a confirmation dialog.
+
+```typescript
+import { createBashTool, type BashSpawnHook, type BashSpawnContext } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  const bashTool = createBashTool(process.cwd(), {
+    spawnHook: ({ command, cwd, env }: BashSpawnContext): BashSpawnContext => ({
+      command: command.replace(/^npm /, "pnpm "),
+      cwd,
+      env: { ...env, CUSTOM_VAR: "1" },
+    }),
+  });
+
+  pi.registerTool({ ...bashTool });
+}
+```
+
+### BashSpawnContext
+
+The spawn hook receives and returns a `BashSpawnContext`:
+
+```typescript
+interface BashSpawnContext {
+  command: string;        // The shell command to execute
+  cwd: string;            // Working directory
+  env: NodeJS.ProcessEnv; // Environment variables
+}
+```
+
+You can modify any of these fields. The hook runs after pi's own processing but before the shell spawns.
+
+### Key Points
+
+- **Replaces the built-in bash tool.** When you call `pi.registerTool()` with a tool named `"bash"`, it replaces the default. Only one extension should do this.
+- **Transparent to the agent.** The agent sees the original command in the tool call UI but gets the output of the rewritten command.
+- **Execution order with tool_call hooks.** `tool_call` event hooks (blockers) run first. If a blocker returns `{ block: true }`, the spawn hook never fires. This means you can combine blocking hooks for commands that should be stopped entirely with spawn hooks for commands that should be rewritten.
+- **Prefer AST-based rewrites over regex.** A false positive rewrite corrupts a command silently. Use `@aliou/sh` or similar shell parsers to identify command names in the AST, then do surgical string replacement at the identified positions. If the parse fails, return the command unchanged.
+- **Compose multiple rewriters.** Chain rewriter functions that each transform the context:
+
+```typescript
+const rewriters: ((ctx: BashSpawnContext) => BashSpawnContext)[] = [
+  createPackageManagerRewriter(config),
+  createGitRebaseRewriter(),
+];
+
+const spawnHook = (ctx: BashSpawnContext) => {
+  let result = ctx;
+  for (const rewrite of rewriters) {
+    result = rewrite(result);
+  }
+  return result;
+};
+
+const bashTool = createBashTool(process.cwd(), { spawnHook });
+pi.registerTool({ ...bashTool });
+```
+
+### When to Use What
+
+| Pattern | Use When | Agent Sees |
+|---|---|---|
+| `tool_call` hook + `{ block: true }` | Command must be stopped entirely | Block reason (retries with correct command) |
+| `tool_call` hook + `ctx.ui.confirm()` | User confirmation needed | Block reason if denied |
+| Spawn hook (command rewrite) | Clear 1:1 rewrite target exists | Output of rewritten command (transparent) |
+| Spawn hook (env injection) | Need to set env vars for specific commands | Output with injected env (transparent) |
+
+## Multiple Handlers
+
+Multiple extensions can register handlers for the same event. They execute in registration order. For blocking events (`tool_call`, `session_before_switch`, etc.), the first handler to return a blocking/cancelling result wins.
+
+## Mode Awareness in Hooks
+
+Always consider what happens in Print mode when your hook uses dialog methods. See `references/modes.md` for the full behavior matrix.
+
+Common pattern for `tool_call` handlers:
+
+```typescript
+pi.on("tool_call", async (event, ctx) => {
+  if (shouldBlock(event)) {
+    if (!ctx.hasUI) {
+      return { block: true, reason: "No UI to confirm" };
+    }
+    // Safe to use dialogs here
+    const choice = await ctx.ui.select("Allow?", ["Yes", "No"]);
+    if (choice !== "Yes") {
+      return { block: true, reason: "Blocked by user" };
+    }
+  }
+  return undefined;
+});
+```

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

@@ -0,0 +1,169 @@
+# Messages
+
+Pi provides several ways to display information to the user. Choose based on the UX goal.
+
+## When to Use What
+
+| Method | Persistence | Interactivity | Use When |
+|---|---|---|---|
+| `ctx.ui.notify()` | Transient (fades) | None | Quick feedback: "Saved", "API key missing" |
+| `ctx.ui.custom()` | Until dismissed | Full keyboard | Rich interactive display: pickers, dashboards |
+| `pi.sendMessage()` | In session history | Via renderer | Persistent results that should survive compaction |
+| `pi.appendEntry()` | In session history | Via renderer | State tracking entries (see `references/state.md`) |
+
+## sendMessage
+
+Sends a message into the session conversation. It appears as an assistant message and is persisted in session history.
+
+```typescript
+pi.sendMessage({
+  customType: "balance-result",     // Identifier for the message renderer
+  content: "Balance: $42.50",       // Plain text content (LLM sees this)
+  display: true,                    // Show in TUI
+  details: { balance: 42.50 },     // Rich data for custom rendering
+});
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `customType` | `string` | Identifies the message type. Paired with `registerMessageRenderer`. |
+| `content` | `string` | Plain text content. This is what the LLM sees if the message is in context. |
+| `display` | `boolean` | Whether to show the message in the TUI. |
+| `details` | `object` | Arbitrary data passed to the message renderer. |
+
+## registerMessageRenderer
+
+Registers a custom renderer for messages with a specific `customType`:
+
+```typescript
+pi.registerMessageRenderer("balance-result", (message, theme) => {
+  const { balance } = message.details;
+  return [
+    theme.bold("Account Balance"),
+    "",
+    theme.fg("success", `  $${balance.toFixed(2)}`),
+  ].join("\n");
+});
+```
+
+The renderer receives the full message object and the theme. It returns a string for display in the TUI.
+
+If no renderer is registered for a `customType`, the message's `content` field is displayed as plain text.
+
+## Custom Message Design Guide (breadcrumbs-style)
+
+`breadcrumbs` is a good reference for custom entries/messages (`../pi-extensions/extensions/breadcrumbs/lib/session-link.ts`, plus `commands/handoff.ts` and `commands/spawn.ts`).
+
+### 1) Prefer paired entries for links/handovers
+
+For cross-session workflows, use two custom message types:
+- **Marker** in source session: short line (`Handed off to X` / `Continues in X`).
+- **Source** in new session: header + optional expanded context.
+
+This gives both directions of navigation and keeps history readable.
+
+### 2) Collapsed vs expanded behavior
+
+Keep collapsed view minimal and scannable:
+- one semantic line
+- optional hint (`Press Ctrl+O to expand`) only when extra content exists
+
+Use expanded view for rich content:
+- markdown body
+- multi-line context
+- file lists / instructions
+
+### 3) Renderer resilience
+
+Message renderers should degrade safely:
+- missing `details` => fallback to plain `content`
+- markdown render failure => fallback to plain text
+- unknown fields => ignore, don't throw
+
+### 4) Keep details small and durable
+
+`details` should contain stable identifiers and routing data, not large blobs:
+- session IDs
+- link type (`handoff`, `continue`)
+- short metadata (goal/title)
+
+Put large human-readable content in `content` (for expansion/LLM visibility), not deep nested `details`.
+
+### 5) Use visual hierarchy consistently
+
+For message UIs:
+- muted label + accent target/value (`Continues in <session-name>`)
+- subtle container background for custom message blocks
+- avoid decorative noise; optimize for fast scan in session history
+
+## Pattern: Command with sendMessage Fallback
+
+This combines with the three-tier pattern from `references/modes.md`. Use `sendMessage` as the RPC fallback for commands that use `custom()`:
+
+```typescript
+// Register the renderer once at load time
+pi.registerMessageRenderer("my-results", (message, theme) => {
+  const { items } = message.details;
+  return [
+    theme.bold(`Results (${items.length})`),
+    ...items.map((item: string) => `  ${theme.fg("accent", item)}`),
+  ].join("\n");
+});
+
+pi.registerCommand("results", {
+  description: "Show results",
+  handler: async (_args, ctx) => {
+    const items = await fetchItems();
+
+    if (!ctx.hasUI) {
+      console.log(items.join("\n"));
+      return;
+    }
+
+    const result = await ctx.ui.custom<"closed">((tui, theme, _kb, done) => {
+      return new ResultsDisplay(theme, items, () => done("closed"));
+    });
+
+    // RPC fallback only: custom() returns undefined in RPC/Print.
+    if (result === undefined) {
+      pi.sendMessage({
+        customType: "my-results",
+        content: items.join("\n"),
+        display: true,
+        details: { items },
+      });
+    }
+  },
+});
+```
+
+## notify
+
+For transient feedback that does not need to persist:
+
+```typescript
+ctx.ui.notify("Operation complete", "info");
+ctx.ui.notify("Something went wrong", "error");
+ctx.ui.notify("Proceed with caution", "warning");
+```
+
+The second argument is the notification type: `"info"`, `"error"`, or `"warning"`. It affects the color/icon.
+
+`notify` is fire-and-forget. It works in Interactive and RPC modes, and is a no-op in Print mode.
+
+## Writing custom entries in a new session
+
+When using `ctx.newSession({ setup })`, write custom entries directly through the setup `SessionManager`:
+
+```typescript
+await ctx.newSession({
+  setup: async (sm) => {
+    sm.appendCustomMessageEntry("my-source-type", "Context text", true, {
+      parentSessionId: "...",
+      linkType: "handoff",
+    });
+  },
+});
+```
+
+Use this pattern for handoff/spawn-like workflows where the new session must start with structured context.

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

@@ -0,0 +1,156 @@
+# Mode Awareness
+
+Pi runs in different modes. Extensions must handle all of them gracefully.
+
+## Modes
+
+| Mode | `ctx.hasUI` | Description |
+|---|---|---|
+| **Interactive** | `true` | Full TUI. Normal terminal usage. |
+| **RPC** (`--mode rpc`) | `true` | JSON protocol. A host application handles UI. Dialogs work via request/response. |
+| **Print** (`-p`, `--mode json`) | `false` | No UI. Extensions run but cannot prompt the user. |
+
+Important nuance: in RPC mode, `ctx.hasUI` is `true`, but TUI-only APIs are degraded.
+
+## Method Behavior by Mode
+
+### Dialog Methods (return a value)
+
+These methods prompt the user and return a result. Their behavior varies by mode.
+
+| Method | Interactive | RPC | Print |
+|---|---|---|---|
+| `ctx.ui.select()` | TUI picker | JSON request to host | Returns `undefined` |
+| `ctx.ui.confirm()` | TUI dialog | JSON request to host | Returns `false` |
+| `ctx.ui.input()` | TUI text input | JSON request to host | Returns `undefined` |
+| `ctx.ui.editor()` | TUI editor | JSON request to host | Returns `undefined` |
+| `ctx.ui.custom()` | TUI component | Returns `undefined` | Returns `undefined` |
+
+Key observation: `custom()` returns `undefined` in both RPC and Print modes. All other dialog methods work in RPC (the host presents them to the user).
+
+Second key observation: `custom()` can also resolve to `undefined` in Interactive mode if your component calls `done(undefined)`. So `result === undefined` is not a reliable mode detector by itself.
+
+### Fire-and-Forget Methods (no return value)
+
+These methods are safe to call unconditionally in any mode. In modes that do not support them, they are silently ignored.
+
+| Method | Interactive | RPC | Print |
+|---|---|---|---|
+| `ctx.ui.notify()` | TUI notification | JSON event to host | No-op |
+| `ctx.ui.setStatus()` | Status bar | JSON event to host | No-op |
+| `ctx.ui.setWidget()` | Widget area | JSON event to host (string arrays only) | No-op |
+| `ctx.ui.setTitle()` | Window title | JSON event to host | No-op |
+| `ctx.ui.setEditorText()` | Sets editor content | JSON event to host | No-op |
+| `ctx.ui.setFooter()` | Footer area | No-op | No-op |
+| `ctx.ui.setHeader()` | Header area | No-op | No-op |
+| `ctx.ui.setWorkingMessage()` | Loader text | No-op | No-op |
+| `ctx.ui.setEditorComponent()` | Custom editor | No-op | No-op |
+
+You never need to check `ctx.hasUI` before calling fire-and-forget methods.
+
+## When to Check ctx.hasUI
+
+Check `ctx.hasUI` when a dialog method gates behavior. If the dialog result determines what happens next (for example, blocking a tool call or cancelling a session switch), you must handle the case where the dialog cannot run.
+
+```typescript
+// tool_call handler: must decide to block or allow
+pi.on("tool_call", async (event, ctx) => {
+  if (isDangerous(event)) {
+    if (!ctx.hasUI) {
+      // Print mode: no way to ask the user, block by default
+      return { block: true, reason: "Dangerous command blocked (no UI)" };
+    }
+
+    const choice = await ctx.ui.select("Dangerous command detected", ["Allow", "Block"]);
+    if (choice !== "Allow") {
+      return { block: true, reason: "Blocked by user" };
+    }
+  }
+  return undefined;
+});
+```
+
+You do not need to check `ctx.hasUI` for:
+- Fire-and-forget calls (`notify`, `setStatus`, `setWidget`, etc.).
+- Dialogs where the default return value is acceptable (for example, a non-critical confirm that defaults to `false`).
+
+## The Three-Tier Pattern for Custom Components
+
+When a command uses `ctx.ui.custom()` for a rich TUI display, handle three tiers:
+
+```typescript
+pi.registerCommand("quotas", {
+  description: "Show API quotas",
+  handler: async (_args, ctx) => {
+    const data = await fetchQuotas();
+
+    // Tier 1: Print mode -- no UI at all
+    if (!ctx.hasUI) {
+      console.log(formatPlain(data));
+      return;
+    }
+
+    // Tier 2: Interactive mode -- full TUI component.
+    // Use an explicit non-undefined sentinel for close/cancel.
+    const result = await ctx.ui.custom<"closed">((tui, theme, _kb, done) => {
+      return new QuotasDisplay(theme, data, () => done("closed"));
+    });
+
+    // Tier 3: RPC mode -- custom() returns undefined by design.
+    if (result === undefined) {
+      ctx.ui.notify(formatPlain(data), "info");
+    }
+  },
+});
+```
+
+Since `select`, `confirm`, `input`, and `notify` all work in RPC mode (forwarded to the host via JSON protocol), use them as the RPC fallback. Choose based on UX:
+
+- **`notify`**: Transient feedback or displaying data. Best for most display-only commands.
+- **`select`**: When the custom component is a picker/selector. The RPC host presents a list.
+- **`confirm`**: When the custom component is a confirmation dialog (for example, permission gate).
+- **Notify "requires interactive mode"**: When the custom component is too complex to reduce (for example, settings editor, process manager).
+
+Use `sendMessage` + `registerMessageRenderer` only when the result must persist in session history. See `references/messages.md`.
+
+### Example: Selector Fallback
+
+```typescript
+const result = await ctx.ui.custom<string | null>((_tui, _theme, _kb, done) => {
+  return new FancyPicker(items, done); // done(value) or done(null)
+});
+
+// RPC fallback: use select dialog
+if (result === undefined) {
+  const selected = await ctx.ui.select("Pick an item", items.map((i) => i.label));
+  // ... handle selected
+}
+```
+
+### Example: Confirmation Fallback
+
+```typescript
+// In a tool_call handler:
+if (!ctx.hasUI) {
+  return { block: true, reason: "No UI to confirm" };
+}
+
+const proceed = await ctx.ui.custom<boolean>((_tui, theme, _kb, done) => {
+  return new ConfirmDialog(theme, message, done); // done(true|false)
+});
+
+// RPC fallback: custom() returns undefined, so treat as "not approved".
+if (proceed !== true) {
+  return { block: true, reason: "Blocked" };
+}
+```
+
+## Guidelines
+
+1. Never assume Interactive mode. Always consider what happens in RPC and Print.
+2. Fire-and-forget methods are always safe. Use them freely.
+3. Guard dialog methods that gate behavior with `ctx.hasUI` checks.
+4. Always provide a fallback for `ctx.ui.custom()` because it returns `undefined` in RPC and Print.
+5. Do not use `done(undefined)` for normal interactive close paths if you need to detect RPC fallback.
+6. For `tool_call` handlers, decide a safe default when there is no UI (usually block).
+7. Test your extension in at least Interactive and Print modes. If you use `custom()`, test RPC fallback explicitly.