@mariozechner/pi-coding-agent 0.30.2 → 0.31.1

package/examples/hooks/confirm-destructive.ts

@@ -2,17 +2,16 @@
  * Confirm Destructive Actions Hook
  *
  * Prompts for confirmation before destructive session actions (clear, switch, branch).
- * Demonstrates how to cancel session events using the before_* variants.
+ * Demonstrates how to cancel session events using the before_* events.
  */
 
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI, SessionBeforeSwitchEvent, SessionMessageEntry } from "@mariozechner/pi-coding-agent";
 
 export default function (pi: HookAPI) {
-	pi.on("session", async (event, ctx) => {
-		// Only handle before_* events (the ones that can be cancelled)
-		if (event.reason === "before_new") {
-			if (!ctx.hasUI) return;
+	pi.on("session_before_switch", async (event: SessionBeforeSwitchEvent, ctx) => {
+		if (!ctx.hasUI) return;
 
+		if (event.reason === "new") {
 			const confirmed = await ctx.ui.confirm(
 				"Clear session?",
 				"This will delete all messages in the current session.",
@@ -22,39 +21,39 @@ export default function (pi: HookAPI) {
 				ctx.ui.notify("Clear cancelled", "info");
 				return { cancel: true };
 			}
+			return;
 		}
 
-		if (event.reason === "before_switch") {
-			if (!ctx.hasUI) return;
+		// reason === "resume" - check if there are unsaved changes (messages since last assistant response)
+		const entries = ctx.sessionManager.getEntries();
+		const hasUnsavedWork = entries.some(
+			(e): e is SessionMessageEntry => e.type === "message" && e.message.role === "user",
+		);
 
-			// Check if there are unsaved changes (messages since last assistant response)
-			const hasUnsavedWork = event.entries.some((e) => e.type === "message" && e.message.role === "user");
-
-			if (hasUnsavedWork) {
-				const confirmed = await ctx.ui.confirm(
-					"Switch session?",
-					"You have messages in the current session. Switch anyway?",
-				);
+		if (hasUnsavedWork) {
+			const confirmed = await ctx.ui.confirm(
+				"Switch session?",
+				"You have messages in the current session. Switch anyway?",
+			);
 
-				if (!confirmed) {
-					ctx.ui.notify("Switch cancelled", "info");
-					return { cancel: true };
-				}
+			if (!confirmed) {
+				ctx.ui.notify("Switch cancelled", "info");
+				return { cancel: true };
 			}
 		}
+	});
 
-		if (event.reason === "before_branch") {
-			if (!ctx.hasUI) return;
+	pi.on("session_before_branch", async (event, ctx) => {
+		if (!ctx.hasUI) return;
 
-			const choice = await ctx.ui.select(`Branch from turn ${event.targetTurnIndex}?`, [
-				"Yes, create branch",
-				"No, stay in current session",
-			]);
+		const choice = await ctx.ui.select(`Branch from entry ${event.entryId.slice(0, 8)}?`, [
+			"Yes, create branch",
+			"No, stay in current session",
+		]);
 
-			if (choice !== "Yes, create branch") {
-				ctx.ui.notify("Branch cancelled", "info");
-				return { cancel: true };
-			}
+		if (choice !== "Yes, create branch") {
+			ctx.ui.notify("Branch cancelled", "info");
+			return { cancel: true };
 		}
 	});
 }

package/examples/hooks/custom-compaction.ts

@@ -3,7 +3,7 @@
  *
  * Replaces the default compaction behavior with a full summary of the entire context.
  * Instead of keeping the last 20k tokens of conversation turns, this hook:
- * 1. Summarizes ALL messages (both messagesToSummarize and messagesToKeep and previousSummary)
+ * 1. Summarizes ALL messages (messagesToSummarize + turnPrefixMessages)
  * 2. Discards all old turns completely, keeping only the summary
  *
  * This example also demonstrates using a different model (Gemini Flash) for summarization,
@@ -14,17 +14,15 @@
  */
 
 import { complete, getModel } from "@mariozechner/pi-ai";
-import { messageTransformer } from "@mariozechner/pi-coding-agent";
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
+import { convertToLlm, serializeConversation } from "@mariozechner/pi-coding-agent";
 
 export default function (pi: HookAPI) {
-	pi.on("session", async (event, ctx) => {
-		if (event.reason !== "before_compact") return;
-
+	pi.on("session_before_compact", async (event, ctx) => {
 		ctx.ui.notify("Custom compaction hook triggered", "info");
 
-		const { messagesToSummarize, messagesToKeep, previousSummary, tokensBefore, resolveApiKey, entries, signal } =
-			event;
+		const { preparation, branchEntries: _, signal } = event;
+		const { messagesToSummarize, turnPrefixMessages, tokensBefore, firstKeptEntryId, previousSummary } = preparation;
 
 		// Use Gemini Flash for summarization (cheaper/faster than most conversation models)
 		const model = getModel("google", "gemini-2.5-flash");
@@ -34,35 +32,34 @@ export default function (pi: HookAPI) {
 		}
 
 		// Resolve API key for the summarization model
-		const apiKey = await resolveApiKey(model);
+		const apiKey = await ctx.modelRegistry.getApiKey(model);
 		if (!apiKey) {
 			ctx.ui.notify(`No API key for ${model.provider}, using default compaction`, "warning");
 			return;
 		}
 
 		// Combine all messages for full summary
-		const allMessages = [...messagesToSummarize, ...messagesToKeep];
+		const allMessages = [...messagesToSummarize, ...turnPrefixMessages];
 
 		ctx.ui.notify(
 			`Custom compaction: summarizing ${allMessages.length} messages (${tokensBefore.toLocaleString()} tokens) with ${model.id}...`,
 			"info",
 		);
 
-		// Transform app messages to pi-ai package format
-		const transformedMessages = messageTransformer(allMessages);
+		// Convert messages to readable text format
+		const conversationText = serializeConversation(convertToLlm(allMessages));
 
 		// Include previous summary context if available
 		const previousContext = previousSummary ? `\n\nPrevious session summary for context:\n${previousSummary}` : "";
 
 		// Build messages that ask for a comprehensive summary
 		const summaryMessages = [
-			...transformedMessages,
 			{
 				role: "user" as const,
 				content: [
 					{
 						type: "text" as const,
-						text: `You are a conversation summarizer. Create a comprehensive summary of this entire conversation that captures:${previousContext}
+						text: `You are a conversation summarizer. Create a comprehensive summary of this conversation that captures:${previousContext}
 
 1. The main goals and objectives discussed
 2. Key decisions made and their rationale
@@ -73,7 +70,11 @@ export default function (pi: HookAPI) {
 
 Be thorough but concise. The summary will replace the ENTIRE conversation history, so include all information needed to continue the work effectively.
 
-Format the summary as structured markdown with clear sections.`,
+Format the summary as structured markdown with clear sections.
+
+<conversation>
+${conversationText}
+</conversation>`,
 					},
 				],
 				timestamp: Date.now(),
@@ -94,14 +95,12 @@ Format the summary as structured markdown with clear sections.`,
 				return;
 			}
 
-			// Return a compaction entry that discards ALL messages
-			// firstKeptEntryIndex points past all current entries
+			// Return compaction content - SessionManager adds id/parentId
+			// Use firstKeptEntryId from preparation to keep recent messages
 			return {
-				compactionEntry: {
-					type: "compaction" as const,
-					timestamp: new Date().toISOString(),
+				compaction: {
 					summary,
-					firstKeptEntryIndex: entries.length,
+					firstKeptEntryId,
 					tokensBefore,
 				},
 			};

package/examples/hooks/dirty-repo-guard.ts

@@ -5,47 +5,48 @@
  * Useful to ensure work is committed before switching context.
  */
 
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI, HookContext } from "@mariozechner/pi-coding-agent";
+
+async function checkDirtyRepo(pi: HookAPI, ctx: HookContext, action: string): Promise<{ cancel: boolean } | undefined> {
+	// Check for uncommitted changes
+	const { stdout, code } = await pi.exec("git", ["status", "--porcelain"]);
+
+	if (code !== 0) {
+		// Not a git repo, allow the action
+		return;
+	}
+
+	const hasChanges = stdout.trim().length > 0;
+	if (!hasChanges) {
+		return;
+	}
+
+	if (!ctx.hasUI) {
+		// In non-interactive mode, block by default
+		return { cancel: true };
+	}
+
+	// Count changed files
+	const changedFiles = stdout.trim().split("\n").filter(Boolean).length;
+
+	const choice = await ctx.ui.select(`You have ${changedFiles} uncommitted file(s). ${action} anyway?`, [
+		"Yes, proceed anyway",
+		"No, let me commit first",
+	]);
+
+	if (choice !== "Yes, proceed anyway") {
+		ctx.ui.notify("Commit your changes first", "warning");
+		return { cancel: true };
+	}
+}
 
 export default function (pi: HookAPI) {
-	pi.on("session", async (event, ctx) => {
-		// Only guard destructive actions
-		if (event.reason !== "before_new" && event.reason !== "before_switch" && event.reason !== "before_branch") {
-			return;
-		}
-
-		// Check for uncommitted changes
-		const { stdout, code } = await ctx.exec("git", ["status", "--porcelain"]);
-
-		if (code !== 0) {
-			// Not a git repo, allow the action
-			return;
-		}
-
-		const hasChanges = stdout.trim().length > 0;
-		if (!hasChanges) {
-			return;
-		}
-
-		if (!ctx.hasUI) {
-			// In non-interactive mode, block by default
-			return { cancel: true };
-		}
-
-		// Count changed files
-		const changedFiles = stdout.trim().split("\n").filter(Boolean).length;
-
-		const action =
-			event.reason === "before_new" ? "new session" : event.reason === "before_switch" ? "switch session" : "branch";
-
-		const choice = await ctx.ui.select(`You have ${changedFiles} uncommitted file(s). ${action} anyway?`, [
-			"Yes, proceed anyway",
-			"No, let me commit first",
-		]);
-
-		if (choice !== "Yes, proceed anyway") {
-			ctx.ui.notify("Commit your changes first", "warning");
-			return { cancel: true };
-		}
+	pi.on("session_before_switch", async (event, ctx) => {
+		const action = event.reason === "new" ? "new session" : "switch session";
+		return checkDirtyRepo(pi, ctx, action);
+	});
+
+	pi.on("session_before_branch", async (_event, ctx) => {
+		return checkDirtyRepo(pi, ctx, "branch");
 	});
 }

package/examples/hooks/file-trigger.ts

@@ -9,19 +9,24 @@
  */
 
 import * as fs from "node:fs";
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
 
 export default function (pi: HookAPI) {
-	pi.on("session", async (event, ctx) => {
-		if (event.reason !== "start") return;
-
+	pi.on("session_start", async (_event, ctx) => {
 		const triggerFile = "/tmp/agent-trigger.txt";
 
 		fs.watch(triggerFile, () => {
 			try {
 				const content = fs.readFileSync(triggerFile, "utf-8").trim();
 				if (content) {
-					pi.send(`External trigger: ${content}`);
+					pi.sendMessage(
+						{
+							customType: "file-trigger",
+							content: `External trigger: ${content}`,
+							display: true,
+						},
+						true, // triggerTurn - get LLM to respond
+					);
 					fs.writeFileSync(triggerFile, ""); // Clear after reading
 				}
 			} catch {

package/examples/hooks/git-checkpoint.ts

@@ -5,25 +5,29 @@
  * When branching, offers to restore code to that point in history.
  */
 
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
 
 export default function (pi: HookAPI) {
-	const checkpoints = new Map<number, string>();
+	const checkpoints = new Map<string, string>();
+	let currentEntryId: string | undefined;
 
-	pi.on("turn_start", async (event, ctx) => {
+	// Track the current entry ID when user messages are saved
+	pi.on("tool_result", async (_event, ctx) => {
+		const leaf = ctx.sessionManager.getLeafEntry();
+		if (leaf) currentEntryId = leaf.id;
+	});
+
+	pi.on("turn_start", async () => {
 		// Create a git stash entry before LLM makes changes
-		const { stdout } = await ctx.exec("git", ["stash", "create"]);
+		const { stdout } = await pi.exec("git", ["stash", "create"]);
 		const ref = stdout.trim();
-		if (ref) {
-			checkpoints.set(event.turnIndex, ref);
+		if (ref && currentEntryId) {
+			checkpoints.set(currentEntryId, ref);
 		}
 	});
 
-	pi.on("session", async (event, ctx) => {
-		// Only handle before_branch events
-		if (event.reason !== "before_branch") return;
-
-		const ref = checkpoints.get(event.targetTurnIndex);
+	pi.on("session_before_branch", async (event, ctx) => {
+		const ref = checkpoints.get(event.entryId);
 		if (!ref) return;
 
 		if (!ctx.hasUI) {
@@ -37,7 +41,7 @@ export default function (pi: HookAPI) {
 		]);
 
 		if (choice?.startsWith("Yes")) {
-			await ctx.exec("git", ["stash", "apply", ref]);
+			await pi.exec("git", ["stash", "apply", ref]);
 			ctx.ui.notify("Code restored to checkpoint", "info");
 		}
 	});

package/examples/hooks/handoff.ts

@@ -0,0 +1,150 @@
+/**
+ * Handoff hook - transfer context to a new focused session
+ *
+ * Instead of compacting (which is lossy), handoff extracts what matters
+ * for your next task and creates a new session with a generated prompt.
+ *
+ * Usage:
+ *   /handoff now implement this for teams as well
+ *   /handoff execute phase one of the plan
+ *   /handoff check other places that need this fix
+ *
+ * The generated prompt appears as a draft in the editor for review/editing.
+ */
+
+import { complete, type Message } from "@mariozechner/pi-ai";
+import type { HookAPI, SessionEntry } from "@mariozechner/pi-coding-agent";
+import { BorderedLoader, convertToLlm, serializeConversation } from "@mariozechner/pi-coding-agent";
+
+const SYSTEM_PROMPT = `You are a context transfer assistant. Given a conversation history and the user's goal for a new thread, generate a focused prompt that:
+
+1. Summarizes relevant context from the conversation (decisions made, approaches taken, key findings)
+2. Lists any relevant files that were discussed or modified
+3. Clearly states the next task based on the user's goal
+4. Is self-contained - the new thread should be able to proceed without the old conversation
+
+Format your response as a prompt the user can send to start the new thread. Be concise but include all necessary context. Do not include any preamble like "Here's the prompt" - just output the prompt itself.
+
+Example output format:
+## Context
+We've been working on X. Key decisions:
+- Decision 1
+- Decision 2
+
+Files involved:
+- path/to/file1.ts
+- path/to/file2.ts
+
+## Task
+[Clear description of what to do next based on user's goal]`;
+
+export default function (pi: HookAPI) {
+	pi.registerCommand("handoff", {
+		description: "Transfer context to a new focused session",
+		handler: async (args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("handoff requires interactive mode", "error");
+				return;
+			}
+
+			if (!ctx.model) {
+				ctx.ui.notify("No model selected", "error");
+				return;
+			}
+
+			const goal = args.trim();
+			if (!goal) {
+				ctx.ui.notify("Usage: /handoff <goal for new thread>", "error");
+				return;
+			}
+
+			// Gather conversation context from current branch
+			const branch = ctx.sessionManager.getBranch();
+			const messages = branch
+				.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
+				.map((entry) => entry.message);
+
+			if (messages.length === 0) {
+				ctx.ui.notify("No conversation to hand off", "error");
+				return;
+			}
+
+			// Convert to LLM format and serialize
+			const llmMessages = convertToLlm(messages);
+			const conversationText = serializeConversation(llmMessages);
+			const currentSessionFile = ctx.sessionManager.getSessionFile();
+
+			// Generate the handoff prompt with loader UI
+			const result = await ctx.ui.custom<string | null>((tui, theme, done) => {
+				const loader = new BorderedLoader(tui, theme, `Generating handoff prompt...`);
+				loader.onAbort = () => done(null);
+
+				const doGenerate = async () => {
+					const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+
+					const userMessage: Message = {
+						role: "user",
+						content: [
+							{
+								type: "text",
+								text: `## Conversation History\n\n${conversationText}\n\n## User's Goal for New Thread\n\n${goal}`,
+							},
+						],
+						timestamp: Date.now(),
+					};
+
+					const response = await complete(
+						ctx.model!,
+						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
+						{ apiKey, signal: loader.signal },
+					);
+
+					if (response.stopReason === "aborted") {
+						return null;
+					}
+
+					return response.content
+						.filter((c): c is { type: "text"; text: string } => c.type === "text")
+						.map((c) => c.text)
+						.join("\n");
+				};
+
+				doGenerate()
+					.then(done)
+					.catch((err) => {
+						console.error("Handoff generation failed:", err);
+						done(null);
+					});
+
+				return loader;
+			});
+
+			if (result === null) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			// Let user edit the generated prompt
+			const editedPrompt = await ctx.ui.editor("Edit handoff prompt (ctrl+enter to submit, esc to cancel)", result);
+
+			if (editedPrompt === undefined) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			// Create new session with parent tracking
+			const newSessionResult = await ctx.newSession({
+				parentSession: currentSessionFile,
+			});
+
+			if (newSessionResult.cancelled) {
+				ctx.ui.notify("New session cancelled", "info");
+				return;
+			}
+
+			// Set the edited prompt in the main editor for submission
+			ctx.ui.setEditorText(editedPrompt);
+			ctx.ui.notify("Handoff ready. Submit when ready.", "info");
+		},
+	});
+}

package/examples/hooks/permission-gate.ts

@@ -5,7 +5,7 @@
  * Patterns checked: rm -rf, sudo, chmod/chown 777
  */
 
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
 
 export default function (pi: HookAPI) {
 	const dangerousPatterns = [/\brm\s+(-rf?|--recursive)/i, /\bsudo\b/i, /\b(chmod|chown)\b.*777/i];

package/examples/hooks/protected-paths.ts

@@ -5,7 +5,7 @@
  * Useful for preventing accidental modifications to sensitive files.
  */
 
-import type { HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
 
 export default function (pi: HookAPI) {
 	const protectedPaths = [".env", ".git/", "node_modules/"];

package/examples/hooks/qna.ts

@@ -0,0 +1,119 @@
+/**
+ * Q&A extraction hook - extracts questions from assistant responses
+ *
+ * Demonstrates the "prompt generator" pattern:
+ * 1. /qna command gets the last assistant message
+ * 2. Shows a spinner while extracting (hides editor)
+ * 3. Loads the result into the editor for user to fill in answers
+ */
+
+import { complete, type UserMessage } from "@mariozechner/pi-ai";
+import type { HookAPI } from "@mariozechner/pi-coding-agent";
+import { BorderedLoader } from "@mariozechner/pi-coding-agent";
+
+const SYSTEM_PROMPT = `You are a question extractor. Given text from a conversation, extract any questions that need answering and format them for the user to fill in.
+
+Output format:
+- List each question on its own line, prefixed with "Q: "
+- After each question, add a blank line for the answer prefixed with "A: "
+- If no questions are found, output "No questions found in the last message."
+
+Example output:
+Q: What is your preferred database?
+A: 
+
+Q: Should we use TypeScript or JavaScript?
+A: 
+
+Keep questions in the order they appeared. Be concise.`;
+
+export default function (pi: HookAPI) {
+	pi.registerCommand("qna", {
+		description: "Extract questions from last assistant message into editor",
+		handler: async (_args, ctx) => {
+			if (!ctx.hasUI) {
+				ctx.ui.notify("qna requires interactive mode", "error");
+				return;
+			}
+
+			if (!ctx.model) {
+				ctx.ui.notify("No model selected", "error");
+				return;
+			}
+
+			// Find the last assistant message on the current branch
+			const branch = ctx.sessionManager.getBranch();
+			let lastAssistantText: string | undefined;
+
+			for (let i = branch.length - 1; i >= 0; i--) {
+				const entry = branch[i];
+				if (entry.type === "message") {
+					const msg = entry.message;
+					if ("role" in msg && msg.role === "assistant") {
+						if (msg.stopReason !== "stop") {
+							ctx.ui.notify(`Last assistant message incomplete (${msg.stopReason})`, "error");
+							return;
+						}
+						const textParts = msg.content
+							.filter((c): c is { type: "text"; text: string } => c.type === "text")
+							.map((c) => c.text);
+						if (textParts.length > 0) {
+							lastAssistantText = textParts.join("\n");
+							break;
+						}
+					}
+				}
+			}
+
+			if (!lastAssistantText) {
+				ctx.ui.notify("No assistant messages found", "error");
+				return;
+			}
+
+			// Run extraction with loader UI
+			const result = await ctx.ui.custom<string | null>((tui, theme, done) => {
+				const loader = new BorderedLoader(tui, theme, `Extracting questions using ${ctx.model!.id}...`);
+				loader.onAbort = () => done(null);
+
+				// Do the work
+				const doExtract = async () => {
+					const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+					const userMessage: UserMessage = {
+						role: "user",
+						content: [{ type: "text", text: lastAssistantText! }],
+						timestamp: Date.now(),
+					};
+
+					const response = await complete(
+						ctx.model!,
+						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
+						{ apiKey, signal: loader.signal },
+					);
+
+					if (response.stopReason === "aborted") {
+						return null;
+					}
+
+					return response.content
+						.filter((c): c is { type: "text"; text: string } => c.type === "text")
+						.map((c) => c.text)
+						.join("\n");
+				};
+
+				doExtract()
+					.then(done)
+					.catch(() => done(null));
+
+				return loader;
+			});
+
+			if (result === null) {
+				ctx.ui.notify("Cancelled", "info");
+				return;
+			}
+
+			ctx.ui.setEditorText(result);
+			ctx.ui.notify("Questions loaded. Edit and submit when ready.", "info");
+		},
+	});
+}