@aliou/pi-dev-kit 0.4.9 → 0.6.0

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.

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

@@ -0,0 +1,134 @@
+# Providers
+
+Providers add LLM backends to pi. They connect pi to model APIs (OpenAI-compatible or custom).
+
+## Registration
+
+```typescript
+import { Type, type ExtensionAPI, type ProviderDefinition } from "@mariozechner/pi-coding-agent";
+
+const myProvider: ProviderDefinition = {
+  name: "my-provider",
+  models: () => {
+    const apiKey = process.env.MY_API_KEY;
+    if (!apiKey) return [];
+
+    return [
+      {
+        id: "my-provider/model-name",
+        name: "Model Name",
+        provider: "my-provider",
+        canStream: true,
+        contextLength: 128000,
+        maxOutputTokens: 8192,
+        pricing: { inputPerMillion: 3.0, outputPerMillion: 15.0 },
+        compat: {
+          type: "openai-completions",
+          maxTokensField: "max_tokens",
+          supportsDeveloperRole: false,
+        },
+      },
+    ];
+  },
+  apiKey: () => process.env.MY_API_KEY,
+  baseUrl: () => "https://api.my-provider.com/v1",
+};
+
+export default function (pi: ExtensionAPI) {
+  pi.registerProvider(myProvider);
+}
+```
+
+## Provider Definition
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | Unique provider identifier. Used as prefix in model IDs. |
+| `models` | `() => ProviderModelConfig[]` | Returns available models. Called when pi needs the model list. Return `[]` if the API key is missing. |
+| `apiKey` | `() => string \| undefined` | Returns the API key. Pi calls this when making requests. |
+| `baseUrl` | `() => string \| undefined` | Returns the base URL for the API. |
+
+The `models` function is the right place to check for API key presence. If the key is missing, return an empty array and the provider will appear registered but offer no models.
+
+## Model Definition
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `string` | Unique model ID. Convention: `provider/model-name`. |
+| `name` | `string` | Display name shown in model picker. |
+| `provider` | `string` | Must match the provider's `name`. |
+| `canStream` | `boolean` | Whether the model supports streaming responses. |
+| `contextLength` | `number` | Maximum context window in tokens. |
+| `maxOutputTokens` | `number` | Maximum output tokens per response. |
+| `pricing` | `object` | `{ inputPerMillion, outputPerMillion }` in USD. Used for cost display. |
+| `compat` | `object` | OpenAI compatibility settings. See below. |
+
+## Compat Field
+
+The `compat` field tells pi how to talk to the model's API. Most third-party APIs are OpenAI-compatible but differ in which features they support.
+
+```typescript
+compat: {
+  type: "openai-completions",
+
+  // Which field name the API uses for max output tokens
+  maxTokensField: "max_tokens" | "max_completion_tokens",
+
+  // Whether the API supports the 'developer' role (vs 'system')
+  supportsDeveloperRole: boolean,
+
+  // Whether the API supports the 'store' parameter
+  supportsStore: boolean,
+
+  // Whether the API supports reasoning_effort parameter
+  supportsReasoningEffort: boolean,
+
+  // Whether usage stats are included in streaming responses
+  supportsUsageInStreaming: boolean,
+
+  // Whether tool results must include a 'name' field
+  requiresToolResultName: boolean,
+
+  // Whether an assistant message is required after tool results
+  requiresAssistantAfterToolResult: boolean,
+
+  // Whether thinking/reasoning must be sent as text content
+  requiresThinkingAsText: boolean,
+
+  // Mistral-specific tool ID requirements
+  requiresMistralToolIds: boolean,
+
+  // Format for thinking/reasoning blocks
+  thinkingFormat: "openai" | "zai" | "qwen",
+
+  // OpenRouter-specific routing hints
+  openRouterRouting: object,
+
+  // Vercel AI Gateway routing
+  vercelGatewayRouting: object,
+}
+```
+
+All fields in `compat` are optional except `type`. Start with the minimum and add fields as needed based on API behavior.
+
+There is also `type: "openai-responses"` for providers using the OpenAI Responses API, which currently has no additional compat fields.
+
+## Provider with API Key Gate
+
+Register the provider unconditionally but gate tools/commands on the API key:
+
+```typescript
+export default function (pi: ExtensionAPI) {
+  // Provider always registered -- models() returns [] if no key
+  pi.registerProvider(myProvider);
+
+  const apiKey = process.env.MY_API_KEY;
+  if (!apiKey) return;
+
+  // Only register tools that need the key
+  pi.registerTool(createSearchTool(apiKey));
+  pi.registerCommand(createQuotasCommand(apiKey));
+}
+```
+
+This way the provider appears in pi's provider list even without a key, and users see a clear "no models available" state rather than a missing provider.

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

@@ -0,0 +1,139 @@
+# Publishing
+
+Extensions are published to npm and installed with `pi install`.
+
+## Package Setup
+
+The `package.json` must have the `pi` key declaring extension resources. See `references/structure.md` for the full template.
+
+Key fields for publishing:
+
+```json
+{
+  "name": "@scope/pi-my-extension",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "publishConfig": { "access": "public" },
+  "files": ["src", "README.md"],
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": ">=0.51.0"
+  }
+}
+```
+
+## Versioning with Changesets
+
+Use [changesets](https://github.com/changesets/changesets) for versioning and changelogs.
+
+### `.changeset/config.json`
+
+```json
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}
+```
+
+### Creating a changeset
+
+The interactive CLI (`pnpm changeset`) is not available in headless environments. Write the file directly instead. Create `.changeset/<descriptive-name>.md`:
+
+```md
+---
+"@scope/pi-my-extension": patch
+---
+
+Description of what changed and why it matters to users.
+```
+
+Bump types: `patch` for fixes and internal changes, `minor` for new user-facing features, `major` for breaking changes.
+
+Commit the changeset file alongside the changes it describes. Multiple changeset files can coexist — they are all consumed together on the next release.
+
+### Releasing manually (no CI)
+
+```bash
+pnpm changeset version   # consumes .changeset/*.md, bumps version, updates CHANGELOG.md
+pnpm changeset publish   # publishes to npm
+```
+
+## GitHub Actions Automation
+
+The recommended setup uses a single `publish.yml` workflow that runs on every push to `main`. It handles two cases automatically:
+
+- **Pending changesets present**: opens (or updates) a version PR titled `Updating @scope/pi-my-extension to version X.Y.Z`.
+- **Version PR merged**: publishes the package to npm and creates a GitHub release with a matching git tag.
+
+Copy `.github/workflows/publish.yml` from `pi-extension-template` into the new repo. It uses `changesets/action@v1` under the hood.
+
+The workflow requires two secrets, configured in the repo's GitHub settings under **Settings → Secrets and variables → Actions**:
+
+- `GITHUB_TOKEN` — automatically provided by GitHub Actions, no setup needed.
+- `NPM_TOKEN` — an npm automation token with publish access to the `@scope` org. Create one at npmjs.com under **Access Tokens → Generate New Token → Automation**. Add it as a repository secret named `NPM_TOKEN`. Without this, the publish step will fail silently on the version PR merge.
+
+The workflow also sets `NPM_CONFIG_PROVENANCE=true`, which links the published package to the GitHub Actions run for supply chain transparency (requires the `id-token: write` permission, already included in the template).
+
+## First-time Setup for a New Package
+
+Before the workflow can publish a package that has never been on npm:
+
+1. Make sure `"private": false` and `"publishConfig": { "access": "public" }` are in `package.json`.
+2. Add the `NPM_TOKEN` secret to the repo (see above).
+3. The first time the version PR is merged, the workflow publishes the package. npm will create the package entry automatically — no manual `npm publish` needed.
+
+If the package name is scoped (e.g., `@aliou/pi-my-extension`) and the scope is new to your npm account, you may need to create the scope first at npmjs.com or run `npm publish --access public` once manually to register it.
+
+## Installation
+
+Users install extensions with:
+
+```bash
+pi install @scope/pi-my-extension
+```
+
+Pi reads the `pi` key from the package's `package.json` to discover extensions, skills, themes, and prompts.
+
+## Dependency Management in Monorepos
+
+If publishing from a monorepo that contains both public and private packages:
+
+**Critical rule**: Public packages cannot depend on private workspace packages. This will break when users try to install your package from npm.
+
+In the pi-extensions monorepo, this is enforced by:
+- Pre-commit hook that blocks commits with invalid dependencies
+- CI check that prevents merging bad dependencies
+- `pnpm run check:public-deps` validates all dependencies
+
+When adding a workspace dependency to a `package.json`:
+1. Check if the dependency is public (`"private": false` or `"publishConfig": { "access": "public" }`).
+2. If the dependency is private, either make it public, make your package private, or remove the dependency.
+
+## Pre-publish Checklist
+
+- [ ] `"private": false` is set.
+- [ ] `"publishConfig": { "access": "public" }` is set.
+- [ ] `"files"` lists only what users need (`["src", "README.md"]`).
+- [ ] `peerDependencies` version range is correct (`>=` minimum supported version).
+- [ ] `@mariozechner/pi-tui` is in `peerDependencies` with `optional: true` in `peerDependenciesMeta` if imported at runtime.
+- [ ] `prepare` script is `[ -d .git ] && husky || true`, not bare `husky`.
+- [ ] `check:lockfile` script is present.
+- [ ] `description` is clear and concise.
+- [ ] `pi.extensions` paths are correct.
+- [ ] `NPM_TOKEN` secret is set on the GitHub repo.
+- [ ] `.github/workflows/publish.yml` is present.
+- [ ] If in a monorepo: no dependency on private workspace packages (`pnpm run check:public-deps` if available).
+- [ ] README documents what the extension does, required environment variables, and available tools/commands.
+- [ ] If wrapping a third-party API: extension handles missing API key gracefully (notification, not crash).
+- [ ] `pnpm typecheck` and `pnpm lint` pass.

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

@@ -0,0 +1,56 @@
+# State Management
+
+Extensions can persist state in the session history using `appendEntry`. State is reconstructed by replaying entries when a session is loaded.
+
+## appendEntry
+
+Adds an entry to the session conversation. Unlike `sendMessage`, entries from `appendEntry` are explicitly for state tracking and are rendered via the tool result rendering system.
+
+```typescript
+pi.appendEntry({
+  toolName: "todo",
+  toolCallId: `todo-${Date.now()}`,
+  input: { action: "add", text: "Buy groceries" },
+  output: "Added: Buy groceries",
+  display: true,
+  details: { items: ["Buy groceries"] },
+});
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `toolName` | `string` | Which tool this entry is associated with. Used for rendering. |
+| `toolCallId` | `string` | Unique ID for this entry. |
+| `input` | `object` | The "input" shown in the entry (as if the tool was called with these params). |
+| `output` | `string` | The text output (what the LLM sees). |
+| `display` | `boolean` | Whether to show in TUI. |
+| `details` | `object` | Rich data for the tool's `renderResult`. |
+
+## Reconstructing State from Session
+
+When a session loads, you can reconstruct state by iterating over existing entries. This is typically done in a `session_start` or `session_switch` handler:
+
+```typescript
+pi.on("session_start", async (_event, ctx) => {
+  // Rebuild state from session entries
+  const entries = ctx.getEntries();
+  for (const entry of entries) {
+    if (entry.toolName === "todo" && entry.details) {
+      todoItems = entry.details.items;
+    }
+  }
+});
+```
+
+This pattern makes state survive session reloads, forks, and compactions (as long as the entries are included in the compaction summary).
+
+## When to Use appendEntry vs sendMessage
+
+| | `appendEntry` | `sendMessage` |
+|---|---|---|
+| Rendered as | Tool call/result pair | Assistant message |
+| Custom renderer | Tool's `renderResult` | `registerMessageRenderer` |
+| Use for | State changes, action logs | Information display, command results |
+| LLM sees | The `output` field | The `content` field |
+
+Use `appendEntry` when you are tracking state changes that need to be replayed. Use `sendMessage` when you are displaying a one-time result.