@aliou/pi-dev-kit 0.6.0 → 0.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliou/pi-dev-kit",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "license": "MIT",
   "type": "module",
   "private": false,
@@ -39,14 +39,14 @@
     "@sinclair/typebox": "^0.34.41"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "0.64.0",
-    "@mariozechner/pi-tui": "0.64.0"
+    "@mariozechner/pi-coding-agent": "0.65.2",
+    "@mariozechner/pi-tui": "0.65.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.13",
     "@changesets/cli": "^2.27.11",
-    "@mariozechner/pi-coding-agent": "0.64.0",
-    "@mariozechner/pi-tui": "0.64.0",
+    "@mariozechner/pi-coding-agent": "0.65.2",
+    "@mariozechner/pi-tui": "0.65.2",
     "@types/node": "^25.0.10",
     "husky": "^9.1.7",
     "typescript": "^5.9.3"

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

@@ -11,10 +11,10 @@ Guide for creating and maintaining Pi extensions. Read the relevant reference fi
 
 Pi injects these packages via jiti at runtime. Extensions do not need to install them — they are available as peer dependencies:
 
-- `@mariozechner/pi-coding-agent` — core types, utilities, `Type`/`Static` (re-exported from TypeBox)
+- `@mariozechner/pi-coding-agent` — core types, utilities, and extension APIs
 - `@mariozechner/pi-tui` — TUI components
 - `@mariozechner/pi-ai` — AI utilities (`StringEnum`, etc.)
-- `@sinclair/typebox` — schema definitions (also re-exported from `pi-coding-agent`, prefer the re-export)
+- `@sinclair/typebox` — schema definitions for tool parameters and related types
 
 ```typescript
 // Tool UI components (from @aliou/pi-utils-ui)
@@ -109,7 +109,7 @@ When implementing, look at these existing extensions for patterns:
 13. **Output truncation**: For tools returning large text, use `truncateHead()` from `@mariozechner/pi-coding-agent`. Write full content to temp file. Append footer with line/byte counts and temp file path.
 14. **Core/lib pattern**: Extract domain logic into modules (`client.ts`, `manager.ts`) that don't import from Pi. Tools are thin wrappers. Core modules are unit-testable with vitest.
 15. **Humanize messages**: Show display names first, IDs in dim/parens. `"Started \"backend\" (proc_42)"` not `"Started proc_42"`.
-16. **peerDependencies**: Pi injects `@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`, `@mariozechner/pi-ai`, and `@sinclair/typebox` via jiti at runtime. Any of these that your extension imports must be listed in `peerDependencies` with `optional: true` in `peerDependenciesMeta`. 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 `*`. Prefer importing `Type`/`Static` from `@mariozechner/pi-coding-agent` rather than `@sinclair/typebox` directly.
+16. **peerDependencies**: Pi injects `@mariozechner/pi-coding-agent`, `@mariozechner/pi-tui`, `@mariozechner/pi-ai`, and `@sinclair/typebox` via jiti at runtime. Any of these that your extension imports must be listed in `peerDependencies` with `optional: true` in `peerDependenciesMeta`. 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 `*`.
 17. **Check existing components**: Before creating a new TUI component, check if `pi-tui` or `pi-coding-agent` already exports one that fits.
 18. **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.
 19. **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.

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

@@ -8,13 +8,11 @@ Hooks let extensions react to lifecycle events. They are registered with `pi.on(
 
 | 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 }` |
+| `session_start` | Session starts, reloads, or is replaced | No | `{ reason: "startup" \| "reload" \| "new" \| "resume" \| "fork", previousSessionFile? }` |
+| `session_before_switch` | Before `/new` or `/resume` replaces the current session | Yes (`{ cancel: true }`) | `{ reason: "new" \| "resume", targetSessionFile? }` |
+| `session_before_fork` | Before forking a session | Yes (`{ cancel: true }`) | `{ entryId }` |
+| `session_shutdown` | Current session runtime is shutting down or being replaced | No | `{}` |
+| `session_before_compact` | Before compaction | Yes (cancel or provide custom compaction) | event-specific compaction data |
 
 ### Agent Events
 
@@ -98,8 +96,13 @@ pi.on("session_before_switch", async (event, ctx) => {
 
 ```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)}...`;
+  return {
+    compaction: {
+      summary: "Custom summary",
+      firstKeptEntryId: event.preparation.firstKeptEntryId,
+      tokensBefore: event.preparation.tokensBefore,
+    },
+  };
 });
 ```
 

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

@@ -1,42 +1,53 @@
 # State Management
 
-Extensions can persist state in the session history using `appendEntry`. State is reconstructed by replaying entries when a session is loaded.
+Extensions can persist state in the session history. In modern Pi extensions, the usual pattern is to store reconstructible state in tool result `details` and rebuild it from the current branch on `session_start`.
 
-## appendEntry
+## Recommended Pattern: Store State in Tool Result Details
 
-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.
+When a tool changes extension state, return the latest state in `details`. That keeps the state aligned with normal tool history, branching, and reconstruction.
 
 ```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"] },
-});
-```
+export default function (pi: ExtensionAPI) {
+  let items: string[] = [];
 
-| 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`. |
+  pi.on("session_start", async (_event, ctx) => {
+    items = [];
+    for (const entry of ctx.sessionManager.getBranch()) {
+      if (entry.type === "message" && entry.message.role === "toolResult") {
+        if (entry.message.toolName === "todo") {
+          items = entry.message.details?.items ?? [];
+        }
+      }
+    }
+  });
+
+  pi.registerTool({
+    name: "todo",
+    // ...
+    async execute() {
+      items.push("Buy groceries");
+      return {
+        content: [{ type: "text", text: "Added todo item" }],
+        details: { items: [...items] },
+      };
+    },
+  });
+}
+```
 
 ## 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:
+When a session loads, reconstruct state in `session_start` by iterating over the current branch or full session through `ctx.sessionManager`:
 
 ```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;
+  todoItems = [];
+
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type === "message" && entry.message.role === "toolResult") {
+      if (entry.message.toolName === "todo") {
+        todoItems = entry.message.details?.items ?? [];
+      }
     }
   }
 });
@@ -53,4 +64,4 @@ This pattern makes state survive session reloads, forks, and compactions (as lon
 | 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.
+Use tool result `details` when the state naturally belongs to a tool call and should follow normal conversation branching. Use `appendEntry` for extension-specific state/history that does not fit a normal tool result. Use `sendMessage` when you are displaying a one-time result.

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

@@ -135,10 +135,10 @@ Only include `pi` sub-fields that are actually used. `skills`, `themes`, `prompt
 
 **`peerDependencies`**: Declares the minimum pi version required. Pi ships these packages and injects them via jiti at runtime, so extensions never need to install them:
 
-- `@mariozechner/pi-coding-agent` — core types, utilities, `Type` (re-exported from TypeBox)
+- `@mariozechner/pi-coding-agent` — core types, utilities, and extension APIs
 - `@mariozechner/pi-tui` — TUI components
 - `@mariozechner/pi-ai` — AI utilities (`StringEnum`, etc.)
-- `@sinclair/typebox` — schema definitions (also re-exported from `pi-coding-agent`)
+- `@sinclair/typebox` — schema definitions for tool parameters and related types
 
 List any of these you import at runtime in `peerDependencies` as optional peers. This prevents npm from installing duplicate copies when a user installs your extension. Use `>=` with the current version when creating.