@aliou/pi-dev-kit 0.4.9 → 0.5.0

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.