@counterposition/skill-pi 0.2.0 → 0.65.1

package/README.md

@@ -2,6 +2,9 @@
 
 Single-skill npm package for installing the `pi` skill with `pi install`.
 
+Package versions track the Pi coding agent release that the bundled skill
+documentation targets.
+
 ## Install
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@counterposition/skill-pi",
-  "version": "0.2.0",
+  "version": "0.65.1",
   "description": "Pi skill package for pi install",
   "keywords": [
     "pi-package"

package/skills/pi/README.md

@@ -1,44 +1,48 @@
 # Pi Skill
 
-Reference skill for the Pi coding agent.
+> Knowing others is intelligence; knowing yourself is true wisdom.
+>
+> — Lao Tzu, *Tao Te Ching*
 
-- 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.
+A coding agent that cannot reason about its own architecture will invent APIs that don't exist, hallucinate configuration formats, and give confident wrong answers about its own internals. The failure mode is subtle: the answers *sound* right, because the agent knows how systems like it tend to work. But Pi is specific, and the details matter.
+
+This skill gives Pi self-knowledge. It injects task-specific reference documentation into context so that Pi reasons from grounded facts — about its extensions, settings, providers, sessions, and SDK — rather than from plausible fictions.
+
+Without this skill, Pi guesses about itself. With it, Pi *knows*.
 
 ## Install
 
 ```bash
-# multi-skill repo
+# as a skill
 npx skills add counterposition/pi --skill pi
 
-# pi install from npm
+# as a Pi package
 pi install npm:@counterposition/skill-pi
 ```
 
-Maintainer smoke tests:
+### Maintainer Paths
 
 ```bash
-# canonical skill from a local checkout
+# from a local checkout
 npx skills add /absolute/path/to/pi --skill pi
 
-# packaged Pi install from the monorepo root
+# packaged install from monorepo root
 pi install ./packages/skill-pi
 ```
 
-If you are developing inside this repo, Pi already loads the canonical skill via `.pi/settings.json`, so you usually do not need `pi install`.
+If you develop inside this repo, Pi already loads the skill via `.pi/settings.json`.
+
+## What this covers
 
-## Covers
+Pi's architecture and package layout. Skill authoring, discovery, and routing. Extensions, tools, and UI hooks. Settings, models, providers, and packages. Sessions, forks, and compaction. The SDK and RPC interface.
 
-- Pi architecture and package layout
-- Skill authoring and discovery
-- Extensions, tools, and UI hooks
-- Settings, models, providers, and packages
-- Sessions, forks, and compaction
+The reference material lives in `references/` as task-specific documents — not a single monolith, but pieces sized for injection into a conversation when relevant.
 
 ## Files
 
-- `SKILL.md` - trigger description and routing
-- `LICENSE.md` - bundled GPLv3 license text
-- `references/` - task-specific Pi docs
-- `evals/evals.json` - example eval cases
+| Path | Purpose |
+|---|---|
+| `SKILL.md` | Trigger rules and routing description |
+| `references/` | Task-specific Pi reference documents |
+| `evals/evals.json` | Example evaluation cases |
+| `LICENSE.md` | GPLv3 license text |

package/skills/pi/SKILL.md

@@ -105,6 +105,7 @@ Read `references/patterns.md` for copy-paste-ready examples.
 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
+- **`Shift+T` in `/tree`** — Toggle timestamps on tree entry labels
 - **`/compact`** — Manually trigger context compaction
 - **`/fork`** — Branch from a specific point
 - **Auto-compaction** — Triggers when `contextTokens > contextWindow - reserveTokens`

package/skills/pi/references/extensions.md

@@ -65,12 +65,9 @@ export default function (pi: ExtensionAPI) {
 
 Useful session events:
 
-- `session_directory`
 - `session_start`
 - `session_before_switch`
-- `session_switch`
 - `session_before_fork`
-- `session_fork`
 - `session_before_compact`
 - `session_compact`
 - `session_before_tree`
@@ -78,6 +75,18 @@ Useful session events:
 - `session_shutdown`
 - `resources_discover`
 
+Pi 0.65.0 removed the post-transition `session_switch` and `session_fork` events. Handle startup, reload, new, resume, and fork in `session_start` instead:
+
+```typescript
+pi.on("session_start", async (event, ctx) => {
+  if (event.reason === "fork" && event.previousSessionFile && ctx.hasUI) {
+    ctx.ui.notify(`Forked from ${event.previousSessionFile}`, "info");
+  }
+});
+```
+
+Use `event.reason` to distinguish `"startup"`, `"reload"`, `"new"`, `"resume"`, and `"fork"`. For `"new"`, `"resume"`, and `"fork"`, `event.previousSessionFile` points at the session file being replaced.
+
 Useful agent events:
 
 - `input`

package/skills/pi/references/sdk.md

@@ -1,6 +1,6 @@
 # SDK
 
-The SDK embeds Pi in Node.js applications via `createAgentSession()`.
+The SDK embeds Pi in Node.js applications via `createAgentSession()`. Use `createAgentSessionRuntime()` when you need `/new`, `/resume`, `/fork`, or import-style session replacement.
 
 ## Installation
 
@@ -99,12 +99,62 @@ await session.followUp("Summarize the changes afterward");
 
 `prompt()` expands file-based prompt templates. During active streaming, calling it without `streamingBehavior` throws.
 
+## Session Runtime
+
+Pi 0.65.0 moved session replacement off `AgentSession` and onto `AgentSessionRuntime`. Use the runtime when you need `newSession()`, `switchSession()`, `fork()`, or `importFromJsonl()`.
+
+```typescript
+import {
+  type CreateAgentSessionRuntimeFactory,
+  createAgentSessionFromServices,
+  createAgentSessionRuntime,
+  createAgentSessionServices,
+  getAgentDir,
+  SessionManager,
+} from "@mariozechner/pi-coding-agent";
+
+const createRuntime: CreateAgentSessionRuntimeFactory = async ({
+  cwd,
+  sessionManager,
+  sessionStartEvent,
+}) => {
+  const services = await createAgentSessionServices({ cwd });
+  return {
+    ...(await createAgentSessionFromServices({
+      services,
+      sessionManager,
+      sessionStartEvent,
+    })),
+    services,
+    diagnostics: services.diagnostics,
+  };
+};
+
+const runtime = await createAgentSessionRuntime(createRuntime, {
+  cwd: process.cwd(),
+  agentDir: getAgentDir(),
+  sessionManager: SessionManager.create(process.cwd()),
+});
+
+let session = runtime.session;
+let unsubscribe = session.subscribe(() => {});
+
+await runtime.newSession();
+
+unsubscribe();
+session = runtime.session;
+unsubscribe = session.subscribe(() => {});
+```
+
+Notes:
+
+- `runtime.session` changes after replacement. Re-subscribe to session-local events after `newSession()`, `switchSession()`, `fork()`, or `importFromJsonl()`.
+- Cross-cwd replacement rebuilds cwd-bound services and session configuration.
+- `runtime.diagnostics` carries startup and replacement diagnostics instead of printing or exiting directly.
+
 ## Session Surface
 
 ```typescript
-await session.newSession();
-await session.switchSession("/path/to/session.jsonl");
-await session.fork("entry-id");
 await session.navigateTree("entry-id", { summarize: true });
 await session.compact("Summarize design decisions only");
 
@@ -113,6 +163,8 @@ await session.agent.waitForIdle();
 session.dispose();
 ```
 
+Use `runtime.newSession()`, `runtime.switchSession()`, and `runtime.fork()` for session replacement. Keep `navigateTree()` and `compact()` on the live `session`.
+
 Useful state:
 
 - `session.sessionFile` / `session.sessionId`
@@ -155,3 +207,27 @@ session.subscribe((event) => {
 - Override `agentsFiles` to inject virtual `AGENTS.md` content
 - Add custom skills or prompt templates without touching disk
 - Share an event bus between the host app and loaded extensions
+
+## Standalone Custom Tools
+
+Use `defineTool()` when you want a reusable custom tool definition outside `pi.registerTool(...)`:
+
+```typescript
+import { defineTool } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+const myTool = defineTool({
+  name: "my_tool",
+  label: "My Tool",
+  description: "Does something useful",
+  parameters: Type.Object({
+    input: Type.String({ description: "Input value" }),
+  }),
+  async execute(_toolCallId, params) {
+    return {
+      content: [{ type: "text", text: `Result: ${params.input}` }],
+      details: {},
+    };
+  },
+});
+```

package/skills/pi/references/settings.md

@@ -46,6 +46,7 @@ Edit JSON directly or use `/settings` for common interactive options.
 
 - `doubleEscapeAction`: `"tree"`, `"fork"`, or `"none"`
 - `treeFilterMode`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, or `"all"`
+- In `/tree`, `Shift+T` toggles timestamps on entry labels
 
 ## Compaction, Branch Summary, Retry
 
@@ -119,11 +120,7 @@ Notes:
 }
 ```
 
-Precedence for session storage is:
-
-1. `--session-dir`
-2. `sessionDir` in settings
-3. Extension `session_directory` hooks
+When multiple sources specify a session directory, `--session-dir` takes precedence over `sessionDir` in settings. Pi 0.65.0 removed the old `session_directory` extension/settings hook.
 
 ## Resources