feat(ai): Pi provider via RPC subprocess (#377)

* refactor(ai): extract BaseSession and buildEffectivePrompt

Pull shared session lifecycle (~80 lines duplicated across Claude and
Codex providers) into BaseSession: query guard, abort, ID resolution,
generation counter. Extract first-query prompt prepending into
buildEffectivePrompt() in context.ts.

Both providers now extend BaseSession. Behavior-preserving — all 54
existing tests pass unchanged.

For provenance purposes, this commit was AI assisted.

* feat(ai): add Pi provider via RPC subprocess

Spawns `pi --mode rpc` and communicates via JSONL over stdio. No Pi SDK
bundled — user must have the pi CLI installed. Provider auto-discovers
available models at startup via get_available_models.

Includes: PiProcess (JSONL client), PiSDKProvider, PiSDKSession extending
BaseSession, mapPiEvent for streaming, Pi icon in provider UI, and 12
new tests (9 event mapping + 3 buildEffectivePrompt).

For provenance purposes, this commit was AI assisted.

* fix(ai): harden Pi provider error paths

- Surface startup errors when Pi process dies (bad config, missing API keys)
  instead of hanging the chat indefinitely
- Map tool-call errors as non-terminal tool_result instead of AIErrorMessage,
  so Pi can continue reasoning after a failed tool call
- Fix subprocess leak in fetchModels() by moving proc.kill() to finally block

For provenance purposes, this commit was AI assisted.

* fix(ai): detect Pi prompt rejections and process crashes

- Use sendAndWait for prompt command so RPC-level rejections (expired
  credentials, invalid session) surface as errors instead of hanging
- Emit process_exited instead of synthetic agent_end when Pi subprocess
  dies, so crashes show as errors instead of silent empty successes

For provenance purposes, this commit was AI assisted.

* docs(ai): add Pi to AI features guide, code review docs, and installation

For provenance purposes, this commit was AI assisted.

* style(ai): apply biome formatting to new files

For provenance purposes, this commit was AI assisted.

Author: backnotprop

apps/marketing/src/content/docs/commands/code-review.md

@@ -83,8 +83,9 @@ Plannotator supports multiple AI providers. Providers are auto-detected based on
 
 - **Claude** — Requires the `claude` CLI ([Claude Code](https://docs.anthropic.com/en/docs/claude-code))
 - **Codex** — Requires the `codex` CLI ([OpenAI Codex](https://github.com/openai/codex))
+- **Pi** — Requires the `pi` CLI ([Pi](https://github.com/mariozechner/pi-coding-agent))
 
-Both providers can be available simultaneously. Plannotator does not manage API keys — you must be authenticated with each CLI independently (`claude` uses `~/.claude/` credentials, `codex` uses `OPENAI_API_KEY`).
+All providers can be available simultaneously. Plannotator does not manage API keys — you must be authenticated with each CLI independently (`claude` uses `~/.claude/` credentials, `codex` uses `OPENAI_API_KEY`, `pi` uses its own local configuration).
 
 ### Choosing a provider
 

apps/marketing/src/content/docs/getting-started/installation.md

@@ -1,6 +1,6 @@
 ---
 title: "Installation"
-description: "How to install Plannotator for Claude Code, OpenCode, and other agent hosts."
+description: "How to install Plannotator for Claude Code, OpenCode, Pi, and other agent hosts."
 sidebar:
   order: 1
 section: "Getting Started"
@@ -109,3 +109,21 @@ Install the binary, then use it directly:
 !plannotator review           # Code review for current changes
 !plannotator annotate file.md # Annotate a markdown file
 ```
+
+## Pi
+
+Install the Pi extension:
+
+```bash
+pi install npm:@plannotator/pi-extension
+```
+
+Or try it without installing:
+
+```bash
+pi -e npm:@plannotator/pi-extension
+```
+
+Start plan mode with `pi --plan`, or toggle mid-session with `/plannotator` or `Ctrl+Alt+P`. The extension provides file-based plan review, code review (`/plannotator-review`), markdown annotation (`/plannotator-annotate`), bash safety gating during planning, and progress tracking during execution.
+
+See [Plannotator Meets Pi](/blog/plannotator-meets-pi) for the full walkthrough.

apps/marketing/src/content/docs/guides/ai-features.md

@@ -33,6 +33,12 @@ Requires the `codex` CLI installed and authenticated. The AI operates in a sandb
 - GPT-5.2 Codex
 - GPT-5.2
 
+### Pi (via RPC subprocess)
+
+Requires the `pi` CLI installed and configured. Plannotator spawns `pi --mode rpc` and communicates over JSONL/stdio. Models are discovered dynamically from your Pi installation — whatever models you've configured in Pi are available here.
+
+No API keys are managed by Plannotator — Pi uses its own local configuration.
+
 ## Configuration
 
 Provider and model selection is available in **Settings > AI**. These persist via cookies across sessions.
@@ -47,6 +53,8 @@ A session is created lazily on your first question. Until then, no resources are
 
 **Codex sessions** inject the review context as a system prompt prefix. The AI has Codex's built-in capabilities plus the diff. Codex sessions are always standalone — fork support is not available.
 
+**Pi sessions** inject the review context as a system prompt prefix, similar to Codex. Pi uses its full default toolset (read, bash, edit, write). Pi sessions are always standalone — fork and resume are not available.
+
 **Diff context handling:** Large diffs are truncated at roughly 40k characters to stay within context limits. However, when you select specific lines and ask a question, the selected code is always sent alongside the question regardless of truncation.
 
 ## Permission requests
@@ -55,20 +63,22 @@ When using Claude, the AI may request permission to use tools like Read, Glob, G
 
 Codex sessions run in a sandboxed read-only mode, so permission requests do not apply.
 
+Pi does not expose a permission approval gate over RPC, so tool execution is handled entirely by Pi's own runtime.
+
 ## Reasoning effort
 
 Codex supports a reasoning effort setting with four levels: **Low**, **Medium**, **High**, and **Max**. This is available in the config bar at the bottom of the AI sidebar. Higher effort means slower but more thorough responses.
 
-This setting only applies to Codex — Claude does not expose a reasoning effort control.
+This setting only applies to Codex — Claude and Pi do not expose a reasoning effort control.
 
 ## Available settings
 
 | Setting | Description | Provider |
 |---------|-------------|----------|
-| Provider | Claude or Codex | Both |
-| Model | Model selection per provider | Both |
+| Provider | Claude, Codex, or Pi | All |
+| Model | Model selection per provider | All |
 | Reasoning effort | Low / Medium / High / Max | Codex only |
 | Default tools | Read, Glob, Grep, WebSearch | Claude only |
 | Sandbox mode | Read-only | Codex only |
 | Permission mode | Default | Claude only |
-| Max turns | 99 | Both |
+| Max turns | 99 | Claude, Codex |

bun.lock

@@ -904,3 +904,153 @@ describe("Multi-provider endpoints", () => {
     expect(data.sessionId).toBeDefined();
   });
 });
+
+// ---------------------------------------------------------------------------
+// buildEffectivePrompt
+// ---------------------------------------------------------------------------
+
+import { buildEffectivePrompt } from "./context.ts";
+
+describe("buildEffectivePrompt", () => {
+  test("prepends preamble on first query", () => {
+    const result = buildEffectivePrompt("What is this?", "System context here", false);
+    expect(result).toBe("System context here\n\n---\n\nUser question: What is this?");
+  });
+
+  test("returns bare prompt on subsequent queries", () => {
+    const result = buildEffectivePrompt("What is this?", "System context here", true);
+    expect(result).toBe("What is this?");
+  });
+
+  test("returns bare prompt when preamble is null", () => {
+    const result = buildEffectivePrompt("What is this?", null, false);
+    expect(result).toBe("What is this?");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// mapPiEvent
+// ---------------------------------------------------------------------------
+
+import { mapPiEvent } from "./providers/pi-sdk.ts";
+
+describe("mapPiEvent", () => {
+  const SESSION_ID = "pi-session-123";
+
+  test("text_delta from message_update", () => {
+    const result = mapPiEvent({
+      type: "message_update",
+      assistantMessageEvent: { type: "text_delta", delta: "Hello", contentIndex: 0, partial: {} },
+    }, SESSION_ID);
+    expect(result).toEqual([{ type: "text_delta", delta: "Hello" }]);
+  });
+
+  test("toolcall_end from message_update", () => {
+    const result = mapPiEvent({
+      type: "message_update",
+      assistantMessageEvent: {
+        type: "toolcall_end",
+        contentIndex: 0,
+        toolCall: { type: "toolCall", id: "tc_1", name: "read", arguments: { path: "/foo" } },
+        partial: {},
+      },
+    }, SESSION_ID);
+    expect(result).toEqual([{
+      type: "tool_use",
+      toolName: "read",
+      toolInput: { path: "/foo" },
+      toolUseId: "tc_1",
+    }]);
+  });
+
+  test("tool_execution_end maps to tool_result", () => {
+    const result = mapPiEvent({
+      type: "tool_execution_end",
+      toolCallId: "tc_1",
+      toolName: "read",
+      result: "file contents",
+      isError: false,
+    }, SESSION_ID);
+    expect(result).toEqual([{
+      type: "tool_result",
+      toolUseId: "tc_1",
+      result: "file contents",
+    }]);
+  });
+
+  test("tool_execution_end with error maps to tool_result with [Error] prefix", () => {
+    const result = mapPiEvent({
+      type: "tool_execution_end",
+      toolCallId: "tc_1",
+      toolName: "read",
+      result: "not found",
+      isError: true,
+    }, SESSION_ID);
+    expect(result).toEqual([{
+      type: "tool_result",
+      toolUseId: "tc_1",
+      result: "[Error] not found",
+    }]);
+  });
+
+  test("agent_end maps to result", () => {
+    const result = mapPiEvent({
+      type: "agent_end",
+      messages: [],
+    }, SESSION_ID);
+    expect(result).toEqual([{
+      type: "result",
+      sessionId: SESSION_ID,
+      success: true,
+    }]);
+  });
+
+  test("process_exited maps to error", () => {
+    const result = mapPiEvent({ type: "process_exited" }, SESSION_ID);
+    expect(result).toEqual([{
+      type: "error",
+      error: "Pi process exited unexpectedly.",
+      code: "pi_process_exit",
+    }]);
+  });
+
+  test("ignored events return empty", () => {
+    expect(mapPiEvent({ type: "agent_start" }, SESSION_ID)).toEqual([]);
+    expect(mapPiEvent({ type: "turn_start" }, SESSION_ID)).toEqual([]);
+    expect(mapPiEvent({ type: "turn_end", message: {}, toolResults: [] }, SESSION_ID)).toEqual([]);
+    expect(mapPiEvent({ type: "message_start", message: {} }, SESSION_ID)).toEqual([]);
+    expect(mapPiEvent({ type: "message_end", message: {} }, SESSION_ID)).toEqual([]);
+    expect(mapPiEvent({ type: "tool_execution_start", toolCallId: "x", toolName: "y", args: {} }, SESSION_ID)).toEqual([]);
+  });
+
+  test("message_update with thinking events returns empty", () => {
+    const result = mapPiEvent({
+      type: "message_update",
+      assistantMessageEvent: { type: "thinking_delta", delta: "hmm", contentIndex: 0, partial: {} },
+    }, SESSION_ID);
+    expect(result).toEqual([]);
+  });
+
+  test("message_update with done returns empty", () => {
+    const result = mapPiEvent({
+      type: "message_update",
+      assistantMessageEvent: { type: "done", reason: "stop", message: {} },
+    }, SESSION_ID);
+    expect(result).toEqual([]);
+  });
+
+  test("tool_execution_end with object result stringifies it", () => {
+    const result = mapPiEvent({
+      type: "tool_execution_end",
+      toolCallId: "tc_2",
+      toolName: "ls",
+      result: { files: ["a.ts", "b.ts"] },
+      isError: false,
+    }, SESSION_ID);
+    expect(result).toEqual([{
+      type: "tool_result",
+      toolUseId: "tc_2",
+      result: JSON.stringify({ files: ["a.ts", "b.ts"] }),
+    }]);
+  });
+});

packages/ai/ai.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Shared session base class — extracts the common lifecycle, abort, and
+ * ID-resolution logic that every AIProvider session needs.
+ *
+ * Concrete providers extend this and implement query().
+ */
+
+import type { AIMessage, AISession } from "./types.ts";
+
+export abstract class BaseSession implements AISession {
+	readonly parentSessionId: string | null;
+	onIdResolved?: (oldId: string, newId: string) => void;
+
+	protected _placeholderId: string;
+	protected _resolvedId: string | null = null;
+	protected _isActive = false;
+	protected _currentAbort: AbortController | null = null;
+	protected _queryGen = 0;
+	protected _firstQuerySent = false;
+
+	constructor(opts: { parentSessionId: string | null; initialId?: string }) {
+		this.parentSessionId = opts.parentSessionId;
+		this._placeholderId = opts.initialId ?? crypto.randomUUID();
+	}
+
+	get id(): string {
+		return this._resolvedId ?? this._placeholderId;
+	}
+
+	get isActive(): boolean {
+		return this._isActive;
+	}
+
+	// ---------------------------------------------------------------------------
+	// Query lifecycle helpers — call from concrete query() implementations
+	// ---------------------------------------------------------------------------
+
+	/** Error message returned when a query is already active. */
+	static readonly BUSY_ERROR: AIMessage = {
+		type: "error",
+		error:
+			"A query is already in progress. Abort the current query before sending a new one.",
+		code: "session_busy",
+	};
+
+	/**
+	 * Call at the start of query(). Returns the generation number and abort
+	 * signal, or null if the session is busy.
+	 */
+	protected startQuery(): { gen: number; signal: AbortSignal } | null {
+		if (this._isActive) return null;
+
+		const gen = ++this._queryGen;
+		this._isActive = true;
+		this._currentAbort = new AbortController();
+		return { gen, signal: this._currentAbort.signal };
+	}
+
+	/**
+	 * Call in the finally block of query(). Only clears state if the
+	 * generation matches (prevents a stale finally from clobbering a newer query).
+	 */
+	protected endQuery(gen: number): void {
+		if (this._queryGen === gen) {
+			this._isActive = false;
+			this._currentAbort = null;
+		}
+	}
+
+	/**
+	 * Call when the provider resolves the real session ID from the backend.
+	 * Fires the onIdResolved callback so the SessionManager can remap its key.
+	 */
+	protected resolveId(newId: string): void {
+		if (this._resolvedId) return; // Already resolved
+		const oldId = this._placeholderId;
+		this._resolvedId = newId;
+		this.onIdResolved?.(oldId, newId);
+	}
+
+	/**
+	 * Abort the current in-flight query. Subclasses should call super.abort()
+	 * after any provider-specific cleanup.
+	 */
+	abort(): void {
+		if (this._currentAbort) {
+			this._currentAbort.abort();
+			this._isActive = false;
+			this._currentAbort = null;
+		}
+	}
+
+	abstract query(prompt: string): AsyncIterable<AIMessage>;
+}

packages/ai/base-session.ts

@@ -101,6 +101,22 @@ export function buildForkPreamble(ctx: AIContext): string {
   return lines.join("\n");
 }
 
+/**
+ * Build the effective prompt for a query, prepending a preamble on the first
+ * message. Used by providers that inject context via the prompt itself (Codex,
+ * Pi) rather than a separate system-prompt channel (Claude).
+ */
+export function buildEffectivePrompt(
+  userPrompt: string,
+  preamble: string | null,
+  firstQuerySent: boolean,
+): string {
+  if (!firstQuerySent && preamble) {
+    return `${preamble}\n\n---\n\nUser question: ${userPrompt}`;
+  }
+  return userPrompt;
+}
+
 // ---------------------------------------------------------------------------
 // Internals
 // ---------------------------------------------------------------------------

packages/ai/context.ts

@@ -73,6 +73,7 @@ export type {
   CreateSessionOptions,
   ClaudeAgentSDKConfig,
   CodexSDKConfig,
+  PiSDKConfig,
 } from "./types.ts";
 
 // Provider registry
@@ -83,7 +84,10 @@ export {
 } from "./provider.ts";
 
 // Context builders
-export { buildSystemPrompt, buildForkPreamble } from "./context.ts";
+export { buildSystemPrompt, buildForkPreamble, buildEffectivePrompt } from "./context.ts";
+
+// Base session
+export { BaseSession } from "./base-session.ts";
 
 // Session manager
 export { SessionManager } from "./session-manager.ts";