@counterposition/skill-pi 0.1.0

package/skills/pi/README.md

@@ -0,0 +1,38 @@
+# Pi Skill
+
+Reference skill for the Pi coding agent.
+
+- Use when working on Pi extensions, skills, settings, packages, SDK usage, providers, sessions, or compaction.
+- Good trigger terms: `.pi/`, `SKILL.md`, `models.json`, `pi-ai`, `pi-tui`, `pi-agent-core`, `pi-coding-agent`.
+- Not for Raspberry Pi hardware or the math constant.
+
+## Install
+
+```bash
+# multi-skill repo
+npx skills add counterposition/pi --skill pi
+
+# local checkout
+npx skills add /absolute/path/to/pi --skill pi
+
+# pi install from npm
+pi install npm:@counterposition/skill-pi
+
+# pi install from local package
+pi install ./packages/skill-pi
+```
+
+## Covers
+
+- Pi architecture and package layout
+- Skill authoring and discovery
+- Extensions, tools, and UI hooks
+- Settings, models, providers, and packages
+- Sessions, forks, and compaction
+
+## Files
+
+- `SKILL.md` - trigger description and routing
+- `LICENSE.md` - bundled GPLv3 license text
+- `references/` - task-specific Pi docs
+- `evals/evals.json` - example eval cases

package/skills/pi/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: pi
+description: "Provides Pi-specific guidance for extensions, skills, `.pi/` config, `settings.json`, `models.json`, packages, providers, themes, SDK/RPC, sessions, and compaction in Pi, the coding agent. Use when the user mentions Pi or Pi-specific terms such as `.pi/`, `SKILL.md`, `createAgentSession()`, `thinkingLevel`, `session_before_compact`, `pi-ai`, `pi-tui`, `pi-agent-core`, or `pi-coding-agent`. Not for Raspberry Pi hardware, the math constant, or unrelated generic tooling."
+license: GPLv3
+compatibility: "Pi-specific guidance for agents that support Agent Skills"
+---
+
+# Pi Coding Agent
+
+Pi is a minimal, extensible terminal coding agent. It ships four default tools (read, write, edit, bash) and four execution modes (interactive TUI, print/JSON, RPC, SDK). Everything else — sub-agents, plan mode, permission popups, MCP — is added through extensions.
+
+Pi's philosophy: **adapt Pi to your workflows, not the other way around**. Users extend it via TypeScript extensions, skills, prompt templates, themes, and shareable Pi packages.
+
+## Architecture at a Glance
+
+Pi is a monorepo with four core packages:
+
+| Package | npm | Purpose |
+|---------|-----|---------|
+| `pi-ai` | `@mariozechner/pi-ai` | Unified LLM API across 20+ providers |
+| `pi-agent-core` | `@mariozechner/pi-agent-core` | Agent loop, tool execution, state management |
+| `pi-tui` | `@mariozechner/pi-tui` | Terminal UI component library |
+| `pi-coding-agent` | `@mariozechner/pi-coding-agent` | CLI, extensions, skills, sessions, settings |
+
+**Source:** [github.com/badlogic/pi-mono](https://github.com/badlogic/pi-mono)
+
+## File System Layout
+
+```text
+~/.pi/agent/                    # Global config directory (PI_CODING_AGENT_DIR overrides)
+├── settings.json               # Global settings
+├── auth.json                   # Credentials (0600 perms)
+├── models.json                 # Custom provider/model definitions
+├── keybindings.json            # Keyboard shortcuts
+├── presets.json                # Named configurations (via preset extension)
+├── extensions/                 # Global extensions (auto-discovered)
+├── skills/                     # Global skills (auto-discovered)
+├── prompts/                    # Global prompt templates (auto-discovered)
+├── themes/                     # Custom themes
+├── sessions/                   # JSONL session files
+└── bin/                        # Tool binaries (fd, ripgrep)
+
+<project>/
+├── .pi/                        # Project-local config (overrides global)
+│   ├── settings.json           # Project settings (merged over global)
+│   ├── extensions/             # Project extensions (auto-discovered)
+│   ├── skills/                 # Project skills
+│   ├── prompts/                # Project prompt templates
+│   ├── themes/                 # Project themes
+│   └── agents/                 # Agent definitions (for subagent extension)
+```
+
+## Key Concepts
+
+### Extensions
+
+TypeScript modules that hook into Pi's lifecycle. They can register tools, intercept tool calls, add commands, build custom UIs, and persist state. Extensions have **full system access** — they run with the user's permissions.
+
+Read `references/extensions.md` for the complete API, lifecycle events, tool registration, UI methods, and working examples.
+
+### Skills
+
+Markdown-based capability packages (`SKILL.md` with frontmatter). Pi loads skill names and descriptions into the system prompt; the full skill body is read on demand. Skills follow the Agent Skills standard.
+
+Read `references/skills.md` for the authoring guide, frontmatter schema, and directory conventions.
+
+### Settings
+
+Hierarchical JSON configuration: project `.pi/settings.json` merges over global `~/.pi/agent/settings.json`. Controls model, thinking level, compaction, retry, shell, transport, and resource loading.
+
+Read `references/settings.md` for every setting with its type, default, and effect.
+
+### Packages
+
+Bundles of extensions, skills, prompts, and themes distributed via npm, git, or local paths. Installed with `pi install`.
+
+Read `references/packages.md` for the package structure, `pi` manifest field, installation, and publishing.
+
+### SDK
+
+Programmatic embedding via `createAgentSession()`. Gives full control over models, tools, extensions, sessions, and event streaming.
+
+Read `references/sdk.md` for factory options, event types, and usage patterns.
+
+### Custom Providers & Models
+
+Add any OpenAI-compatible, Anthropic, Google, or custom LLM endpoint via `models.json` or extension-based `registerProvider()`.
+
+Read `references/providers.md` for provider configuration, auth methods, and the model schema.
+
+### Common Patterns
+
+Practical recipes for permission gates, presets, sub-agents, git checkpoints, custom compaction, TUI components, and more.
+
+Read `references/patterns.md` for copy-paste-ready examples.
+
+## Sessions & Compaction
+
+Sessions are append-only JSONL files with a tree structure (entries linked by `id`/`parentId`). This allows branching without modifying history. Key operations:
+
+- **`/tree`** — Navigate the session tree, jump to any point
+- **`/compact`** — Manually trigger context compaction
+- **`/fork`** — Branch from a specific point
+- **Auto-compaction** — Triggers when `contextTokens > contextWindow - reserveTokens`
+
+Compaction walks backward from the newest message, keeping `keepRecentTokens` (default 20,000) of recent conversation, and summarizes everything older. Extensions can intercept compaction via `session_before_compact`.
+
+## Built-in Tools
+
+| Tool | Description |
+|------|-------------|
+| `read` | Read files (with offset/limit support, images, PDFs) |
+| `write` | Create or overwrite files |
+| `edit` | Line-based file editing with diffs |
+| `bash` | Execute shell commands with streaming output |
+| `grep` | Search file contents by pattern |
+| `find` | Find files by glob pattern |
+| `ls` | List directory contents |
+
+**Tool presets:** `CODING_TOOLS` = [read, bash, edit, write], `READ_ONLY_TOOLS` = [read, grep, find, ls], `ALL_TOOLS` = all seven.
+
+## Execution Modes
+
+| Mode | Start with | Use case |
+|------|-----------|----------|
+| Interactive | `pi` | Full TUI with editor, streaming, keybindings |
+| Print | `pi -p "prompt"` | Single-shot text output |
+| JSON | `pi --mode json -p "prompt"` | Newline-delimited JSON events |
+| RPC | `pi --mode rpc` | JSON-RPC over stdin/stdout for IDE integration |
+| SDK | `createAgentSession()` | Embed in Node.js applications |
+
+## Quick Reference: CLI Flags
+
+```text
+pi [options] [message]
+
+--model, -m <model>       Model (e.g., "claude-sonnet-4-20250514")
+--provider <name>         Provider name
+--api-key <key>           API key override
+--tools <list>            Comma-separated tool names
+--extensions, -e <path>   Load extension from path
+--skills <path>           Load skill from path
+--system-prompt <text>    Override system prompt
+--thinking-level <level>  off | minimal | low | medium | high | xhigh
+--new                     Start new session
+--resume <id>             Resume session by ID
+--fork <id>               Fork from session
+--continue-recent         Continue most recent session
+--no-session              Don't persist session
+--mode <mode>             json | rpc
+-p                        Print mode (non-interactive)
+install <source>          Install package (npm:pkg, git:url, path)
+remove <pkg>              Remove package
+update                    Update packages
+list                      List installed packages
+```
+
+## How to Use This Skill
+
+When working with Pi, read the appropriate reference file for the task at hand:
+
+| Task | Reference |
+|------|-----------|
+| Writing an extension (tools, commands, events, UI) | `references/extensions.md` |
+| Creating a skill (SKILL.md authoring) | `references/skills.md` |
+| Configuring Pi (settings.json options) | `references/settings.md` |
+| Building a shareable package | `references/packages.md` |
+| Embedding Pi programmatically | `references/sdk.md` |
+| Adding LLM providers or models | `references/providers.md` |
+| Looking for a recipe or pattern | `references/patterns.md` |

package/skills/pi/evals/evals.json

@@ -0,0 +1,50 @@
+{
+  "skill_name": "pi",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Write a Pi extension that blocks any bash command containing `curl` unless the user confirms, and logs all blocked commands to a file at ~/.pi/agent/blocked-commands.log",
+      "expected_output": "A TypeScript extension file that hooks into tool_call events, checks for curl in bash commands, prompts via ctx.ui.select, and appends blocked commands to a log file. Should check ctx.hasUI and handle non-interactive mode.",
+      "files": [],
+      "assertions": [
+        "Uses correct ExtensionAPI import from @mariozechner/pi-coding-agent",
+        "Hooks into tool_call event (the correct event for intercepting tool calls)",
+        "Checks event.toolName === 'bash' before inspecting command",
+        "Tests for curl in the command string",
+        "Checks ctx.hasUI before calling interactive UI methods",
+        "Uses ctx.ui.select or ctx.ui.confirm for user confirmation",
+        "Returns { block: true, reason: '...' } to prevent execution",
+        "Logs blocked commands to ~/.pi/agent/blocked-commands.log",
+        "Uses correct export default function (pi: ExtensionAPI) signature"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I want to set up Pi to use Ollama with llama3.2 locally, with auto-compaction disabled and a custom session directory at ~/pi-sessions. Walk me through the configuration.",
+      "expected_output": "Instructions covering models.json with Ollama provider config (baseUrl localhost:11434/v1, api openai-completions, dummy apiKey, model id llama3.2), settings.json with compaction.enabled=false and sessionDir pointing to ~/pi-sessions.",
+      "files": [],
+      "assertions": [
+        "Provides models.json with Ollama baseUrl containing localhost:11434",
+        "Uses api type openai-completions (correct for Ollama)",
+        "Includes model entry with id llama3.2",
+        "Provides settings.json with compaction.enabled set to false",
+        "Sets sessionDir to ~/pi-sessions",
+        "Correct file paths: ~/.pi/agent/models.json and ~/.pi/agent/settings.json"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Create a Pi skill that helps with database migrations — it should know about Prisma, Drizzle, and raw SQL approaches. Give me the full SKILL.md and any reference files.",
+      "expected_output": "A SKILL.md with proper frontmatter (name, description), a main body routing to reference files, and separate reference docs for Prisma, Drizzle, and raw SQL migration patterns.",
+      "files": [],
+      "assertions": [
+        "SKILL.md has valid YAML frontmatter with name and description fields",
+        "Name follows Pi convention: lowercase, hyphens only, max 64 chars",
+        "Description mentions trigger contexts (migrations, Prisma, Drizzle, SQL)",
+        "Includes separate reference files for Prisma, Drizzle, and raw SQL",
+        "SKILL.md uses relative paths to reference files",
+        "Body routes to the correct reference doc based on the user's framework choice"
+      ]
+    }
+  ]
+}

package/skills/pi/references/extensions.md

@@ -0,0 +1,343 @@
+# Extensions
+
+Extensions are TypeScript modules that customize Pi's behavior. They have **full system permissions** — they can read/write files, run commands, make network requests, and access anything the user can.
+
+## Placement & Discovery
+
+| Location | Scope | Auto-discovered |
+|----------|-------|-----------------|
+| `~/.pi/agent/extensions/*.ts` | Global (all projects) | Yes |
+| `.pi/extensions/*.ts` | Project-local | Yes |
+| `settings.json` → `extensions` | Configured | Yes |
+| `pi -e ./path.ts` | CLI one-off | No |
+
+Subdirectories with an `index.ts` or a `package.json` containing a `"pi"` field are also discovered. Reload with `/reload`.
+
+## Basic Structure
+
+```typescript
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  // Subscribe to lifecycle events
+  pi.on("session_start", async (_event, ctx) => {
+    ctx.ui.notify("Extension loaded!", "info");
+  });
+
+  // Register a tool the LLM can call
+  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) {
+      const { name } = params as { name: string };
+      return {
+        content: [{ type: "text", text: `Hello, ${name}!` }],
+        details: { greeted: name },
+      };
+    },
+  });
+
+  // Register a slash command
+  pi.registerCommand("mycommand", {
+    description: "Do something",
+    async handler(args, ctx) {
+      ctx.ui.notify(`You said: ${args}`, "info");
+    },
+  });
+}
+```
+
+**Import note:** Use `Type` from `@mariozechner/pi-ai` (re-exports TypeBox) and `StringEnum` from the same package for string enums (required for Google API compatibility — do not use `Type.Union` with `Type.Literal` for string enums).
+
+## Lifecycle Events
+
+### Session Events
+
+| Event | When | Payload |
+|-------|------|---------|
+| `session_start` | Session begins | `{ sessionId }` |
+| `session_switch` | User switches session | `{ sessionId }` |
+| `session_fork` | Session forked | `{ entryId }` |
+| `session_before_fork` | Before fork executes | `{ entryId }` |
+| `session_shutdown` | Session closing | `{}` |
+| `session_tree` | After `/tree` navigation | `{ entryId }` |
+| `session_before_tree` | Before `/tree` navigation | `{ entryId, messages }` |
+| `session_before_compact` | Before compaction | `{ messages, settings, ... }` |
+| `session_compact` | After compaction | `{ summary }` |
+| `resources_discover` | Resource discovery phase | `{ extensions, skills, prompts, themes }` |
+
+### Agent Events
+
+| Event | When | Payload |
+|-------|------|---------|
+| `before_agent_start` | Before LLM call (modify system prompt) | `{ systemPrompt }` |
+| `agent_start` | Agent begins processing | `{}` |
+| `agent_end` | Agent finishes | `{}` |
+| `turn_start` | New LLM turn begins | `{}` |
+| `turn_end` | LLM turn finishes | `{}` |
+
+### Tool Events
+
+| Event | When | Payload |
+|-------|------|---------|
+| `tool_call` | Before tool executes | `{ toolName, input }` — return `{ block, reason }` to prevent |
+| `tool_result` | After tool executes | `{ toolName, result }` |
+| `tool_execution_start` | Tool execution begins | `{ toolCallId, toolName }` |
+| `tool_execution_end` | Tool execution ends | `{ toolCallId, toolName }` |
+
+### Other Events
+
+| Event | When | Payload |
+|-------|------|---------|
+| `input` | User submits input | `{ text }` — return modified text or `{ block }` |
+| `model_select` | Model selector opened | `{ models }` — return filtered list |
+
+## Event Handler Signature
+
+```typescript
+pi.on("event_name", async (event, ctx) => {
+  // event: event-specific payload
+  // ctx: ExtensionContext
+});
+```
+
+### ExtensionContext
+
+```typescript
+interface ExtensionContext {
+  ui: ExtensionUIContext;      // UI interaction methods
+  cwd: string;                 // Working directory
+  session: AgentSession;       // Session access
+  sessionManager: SessionManager; // JSONL session persistence
+  modelRegistry: ModelRegistry;   // Available models
+  hasUI: boolean;              // Whether interactive mode is available
+  isIdle(): boolean;           // Whether the agent is idle
+  abort(): void;               // Stop current generation
+  getContextUsage(): ContextUsage; // Token usage info
+  getSystemPrompt(): string;   // Current system prompt
+}
+```
+
+## Tool Registration
+
+```typescript
+pi.registerTool({
+  name: "tool_name",           // Unique identifier
+  label: "Tool Name",          // Display name
+  description: "What this tool does",  // Shown to LLM
+  parameters: Type.Object({    // TypeBox schema
+    arg1: Type.String({ description: "..." }),
+    arg2: Type.Optional(Type.Number()),
+  }),
+
+  // Execute the tool (called by LLM)
+  async execute(toolCallId, params, signal, onUpdate, ctx) {
+    // params: parsed and validated parameters
+    // signal: AbortSignal for cancellation — check signal?.aborted
+    // onUpdate: callback for streaming partial results
+    // ctx: ExtensionContext
+
+    return {
+      content: [{ type: "text", text: "result" }],
+      details: { anyMetadata: true },  // Stored in session, available on branch restore
+    };
+  },
+
+  // Optional: custom TUI rendering for tool calls
+  renderCall(args, theme, context) {
+    return new Text(theme.fg("accent", `tool ${args.arg1}`), 0, 0);
+  },
+
+  // Optional: custom TUI rendering for tool results
+  renderResult(result, { expanded }, theme, context) {
+    return new Text(result.content[0].text, 0, 0);
+  },
+});
+```
+
+**Critical rules for tools:**
+
+1. **Truncate output** — Default limits are 50KB or 2000 lines. Use `truncateHead()` or `truncateTail()` from the tools module.
+2. **Handle cancellation** — Check `signal?.aborted` in long-running operations.
+3. **Throw on error** — Throwing signals failure to the LLM. Returning always means success.
+4. **Use `withFileMutationQueue()`** — If your tool modifies files, wrap the operation to participate in the mutation queue.
+5. **Store state in `details`** — Tool result `details` persist in session history and survive branching. Reconstruct state from session entries on `session_start`.
+
+## UI Methods
+
+All UI methods are on `ctx.ui`. **Always check `ctx.hasUI` first** — non-interactive modes (print, JSON, RPC) may not support UI.
+
+```typescript
+// Dialogs (blocking — waits for user response)
+const choice = await ctx.ui.select("Pick one:", ["Option A", "Option B"]);
+const confirmed = await ctx.ui.confirm("Are you sure?", "Details here");
+const text = await ctx.ui.input("Enter a value:", "default");
+const edited = await ctx.ui.editor("Edit this text", initialContent);
+
+// Notifications (non-blocking)
+ctx.ui.notify("Something happened", "info");  // "info" | "warning" | "error"
+
+// Status indicators
+ctx.ui.setStatus("Processing...");  // Footer status text
+ctx.ui.setWidget("above", component);  // Widget above/below editor
+ctx.ui.setFooter(component);  // Custom footer component
+
+// Editor control
+ctx.ui.setEditorText("prefilled text");
+ctx.ui.pasteToEditor("appended text");
+
+// Custom components (advanced)
+const handle = ctx.ui.custom(component, { overlay: true });
+handle.requestRender();
+handle.close();
+```
+
+## Command Registration
+
+```typescript
+pi.registerCommand("commandname", {
+  description: "What this command does",  // Shown in autocomplete
+  args: "optional args description",
+
+  // Argument autocompletion
+  complete(partial) {
+    return ["suggestion1", "suggestion2"].filter(s => s.startsWith(partial));
+  },
+
+  // Handler receives ExtensionCommandContext (superset of ExtensionContext)
+  async handler(args, ctx) {
+    await ctx.waitForIdle();     // Wait for agent to finish
+    ctx.newSession();            // Create new session
+    ctx.fork(entryId);           // Fork from entry
+    ctx.navigateTree();          // Open tree navigator
+    ctx.reload();                // Reload extensions
+  },
+});
+```
+
+## Keybinding Registration
+
+```typescript
+pi.registerKeybinding({
+  key: "ctrl+shift+k",
+  description: "Do something",
+  handler: async (ctx) => { /* ... */ },
+});
+```
+
+## CLI Flag Registration
+
+```typescript
+pi.registerFlag({
+  name: "--my-flag",
+  description: "Enable something",
+  handler: (value) => { /* value is the flag argument */ },
+});
+```
+
+## State Persistence
+
+Extensions persist state via custom session entries:
+
+```typescript
+// Write state
+pi.appendEntry("my-extension-state", { key: "value" });
+
+// Read state on session restore
+pi.on("session_start", async (_event, ctx) => {
+  const branch = ctx.sessionManager.getBranch();
+  for (const entry of branch.reverse()) {
+    if (entry.type === "custom" && entry.name === "my-extension-state") {
+      const state = entry.data;
+      // Restore from state
+      break;
+    }
+  }
+});
+```
+
+## Provider Registration
+
+Extensions can register custom LLM providers:
+
+```typescript
+pi.registerProvider("my-provider", {
+  baseUrl: "https://api.example.com",
+  api: "openai-completions",
+  apiKey: "sk-...",
+  models: [
+    { id: "my-model", name: "My Model", contextWindow: 128000, maxTokens: 4096 },
+  ],
+});
+```
+
+For full custom streaming, implement `streamSimple` on the provider config. See `references/providers.md`.
+
+## Bash Execution
+
+```typescript
+const { stdout, stderr, exitCode } = await pi.exec("git", ["status"]);
+```
+
+## Practical Examples
+
+### Permission Gate
+
+```typescript
+pi.on("tool_call", async (event, ctx) => {
+  if (event.toolName !== "bash") return;
+  const cmd = event.input.command as string;
+  if (/\brm\s+(-rf?|--recursive)/i.test(cmd)) {
+    if (!ctx.hasUI) return { block: true, reason: "Dangerous command blocked" };
+    const ok = await ctx.ui.select(`⚠️ Dangerous: ${cmd}\nAllow?`, ["Yes", "No"]);
+    if (ok !== "Yes") return { block: true, reason: "Blocked by user" };
+  }
+});
+```
+
+### System Prompt Injection
+
+```typescript
+pi.on("before_agent_start", async (event, _ctx) => {
+  event.systemPrompt += "\n\nAdditional instructions here.";
+});
+```
+
+### Git Checkpoint on Every Turn
+
+```typescript
+pi.on("turn_start", async () => {
+  const { stdout } = await pi.exec("git", ["stash", "create"]);
+  if (stdout.trim()) checkpoints.set(currentEntryId, stdout.trim());
+});
+```
+
+### Custom Compaction
+
+```typescript
+pi.on("session_before_compact", async (event, ctx) => {
+  // Return a custom CompactionResult to override default compaction
+  const allMessages = [...event.messagesToSummarize, ...event.turnPrefixMessages];
+  const summary = await generateCustomSummary(allMessages);
+  return { summary, firstKeptEntryId: event.firstKeptEntryId, tokensBefore: event.tokens };
+});
+```
+
+### Dynamic Tool Registration
+
+```typescript
+pi.on("session_start", async () => {
+  pi.registerTool({ name: "echo", /* ... */ });
+});
+
+pi.registerCommand("add-tool", {
+  async handler(name, ctx) {
+    pi.registerTool({ name, /* ... */ });
+    ctx.ui.notify(`Registered tool: ${name}`, "info");
+  },
+});
+```