@ssweens/pi-handoff 1.1.0 → 1.2.0

package/extensions/handoff.ts

@@ -13,21 +13,23 @@
  * User presses Enter to send it.
  */
 
+import { existsSync, readFileSync } from "node:fs";
 import { complete, type Message } from "@mariozechner/pi-ai";
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
 	ExtensionContext,
 	SessionEntry,
+	SessionHeader,
 } from "@mariozechner/pi-coding-agent";
-import { BorderedLoader, convertToLlm, serializeConversation } from "@mariozechner/pi-coding-agent";
+import { BorderedLoader, buildSessionContext, convertToLlm, serializeConversation } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 
 // ---------------------------------------------------------------------------
 // System prompts
 // ---------------------------------------------------------------------------
 
-const SYSTEM_PROMPT = `You are a context transfer assistant. Read the conversation and produce a structured handoff summary for the stated goal. The new thread must be able to proceed without the old conversation.
+export const SYSTEM_PROMPT = `You are a context transfer assistant. Read the conversation and produce a structured handoff summary for the stated goal. The new thread must be able to proceed without the old conversation.
 
 Do NOT continue the conversation. Do NOT respond to any questions in the history. ONLY output the structured summary.
 
@@ -136,16 +138,18 @@ function appendFileOperations(summary: string, messages: any[]): string {
 // Shared helpers
 // ---------------------------------------------------------------------------
 
+type HandoffResult = { type: "prompt"; text: string } | { type: "error"; message: string } | null;
+
 /**
  * Generate a handoff prompt via LLM with a loader UI.
- * Returns the prompt text, or null if cancelled/failed.
+ * Returns { type: "prompt", text } on success, { type: "error", message } on failure, or null if user cancelled.
  */
 async function generateHandoffPrompt(
 	conversationText: string,
 	goal: string,
 	ctx: ExtensionContext,
-): Promise<string | null> {
-	return ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+): Promise<HandoffResult> {
+	return ctx.ui.custom<HandoffResult>((tui, theme, _kb, done) => {
 		const loader = new BorderedLoader(tui, theme, "Generating handoff prompt...");
 		loader.onAbort = () => done(null);
 
@@ -170,18 +174,28 @@ async function generateHandoffPrompt(
 			);
 
 			if (response.stopReason === "aborted") return null;
+			if (response.stopReason === "error") {
+				const msg =
+					"errorMessage" in response && typeof (response as any).errorMessage === "string"
+						? (response as any).errorMessage
+						: "LLM request failed";
+				return { type: "error" as const, message: msg };
+			}
 
-			return response.content
+			const text = response.content
 				.filter((c): c is { type: "text"; text: string } => c.type === "text")
 				.map((c) => c.text)
-				.join("\n");
+				.join("\n")
+				.trim();
+
+			return text.length > 0 ? { type: "prompt" as const, text } : { type: "error" as const, message: "LLM returned empty response" };
 		};
 
 		run()
 			.then(done)
 			.catch((err) => {
-				console.error("Handoff generation failed:", err);
-				done(null);
+				const message = err instanceof Error ? err.message : String(err);
+				done({ type: "error" as const, message });
 			});
 
 		return loader;
@@ -193,24 +207,78 @@ async function generateHandoffPrompt(
  * Returns serialized text + raw messages (for file op extraction), or null if empty.
  */
 function gatherConversation(ctx: ExtensionContext): { text: string; messages: any[] } | null {
+	// Use buildSessionContext instead of raw getBranch so we only get what the
+	// agent actually sees: compaction summary + kept/recent messages.
+	// Raw getBranch returns the entire session history including messages that
+	// were already compacted away, which can exceed the model's context window.
 	const branch = ctx.sessionManager.getBranch();
-	const messages = branch
-		.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
-		.map((entry) => entry.message);
+	const leafId = ctx.sessionManager.getLeafId();
+	const { messages } = buildSessionContext(branch, leafId);
 
 	if (messages.length === 0) return null;
 
 	return { text: serializeConversation(convertToLlm(messages)), messages };
 }
 
+/**
+ * Read a session file's header to extract parentSession.
+ * Only reads the first line (the header is always line 1 in a .jsonl session file).
+ */
+function getSessionHeader(sessionFile: string): SessionHeader | null {
+	try {
+		if (!existsSync(sessionFile)) return null;
+		const content = readFileSync(sessionFile, "utf-8");
+		const firstLine = content.slice(0, content.indexOf("\n")).trim();
+		if (!firstLine) return null;
+		const parsed = JSON.parse(firstLine);
+		return parsed.type === "session" ? parsed : null;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Walk the session ancestry chain (parent → grandparent → …).
+ * Returns an ordered list of session file paths, starting with the immediate parent.
+ * Stops at the first missing/unreadable file or when there's no parentSession.
+ * Guards against cycles with a visited set.
+ */
+function getSessionAncestry(parentSessionFile: string): string[] {
+	const ancestry: string[] = [];
+	const visited = new Set<string>();
+	let current: string | undefined = parentSessionFile;
+
+	while (current && !visited.has(current)) {
+		visited.add(current);
+		ancestry.push(current);
+		const header = getSessionHeader(current);
+		current = header?.parentSession;
+	}
+
+	return ancestry;
+}
+
 /**
  * Wrap a handoff prompt with the parent session reference and session-query skill.
- * Enables the new session to query the old one for details not in the summary.
+ * Includes the full ancestry chain so the new session can query any ancestor.
  */
 function wrapWithParentSession(prompt: string, parentSessionFile: string | null): string {
 	if (!parentSessionFile) return prompt;
 
-	return `/skill:pi-session-query\n\n**Parent session:** \`${parentSessionFile}\`\n\n${prompt}`;
+	const ancestry = getSessionAncestry(parentSessionFile);
+
+	const lines = [`/skill:pi-session-query`, ""];
+	lines.push(`**Parent session:** \`${ancestry[0]}\``);
+	if (ancestry.length > 1) {
+		lines.push("");
+		lines.push(`**Ancestor sessions:**`);
+		for (let i = 1; i < ancestry.length; i++) {
+			lines.push(`- \`${ancestry[i]}\``);
+		}
+	}
+	lines.push("");
+
+	return `${lines.join("\n")}${prompt}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -325,24 +393,19 @@ export default function (pi: ExtensionAPI) {
 		contextForHandoff += `## Recent Conversation\n\n${conversationText}`;
 
 		// Generate handoff prompt
-		let prompt: string | null;
-		try {
-			prompt = await generateHandoffPrompt(contextForHandoff, "Continue current work", ctx);
-		} catch (err) {
-			ctx.ui.notify(
-				`Handoff failed: ${err instanceof Error ? err.message : String(err)}. Compacting instead.`,
-				"warning",
-			);
-			return;
-		}
+		const handoffResult = await generateHandoffPrompt(contextForHandoff, "Continue current work", ctx);
 
-		if (prompt === null) {
+		if (!handoffResult) {
 			ctx.ui.notify("Handoff cancelled. Compacting instead.", "warning");
 			return;
 		}
+		if (handoffResult.type === "error") {
+			ctx.ui.notify(`Handoff failed: ${handoffResult.message}. Compacting instead.`, "warning");
+			return;
+		}
 
 		// Append programmatic file tracking from the messages being summarized
-		prompt = appendFileOperations(prompt, preparation.messagesToSummarize);
+		let prompt = appendFileOperations(handoffResult.text, preparation.messagesToSummarize);
 
 		// Switch session via raw sessionManager (safe — no agent loop running)
 		const currentSessionFile = ctx.sessionManager.getSessionFile();
@@ -389,14 +452,18 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			let prompt = await generateHandoffPrompt(conv.text, goal, ctx);
-			if (prompt === null) {
+			const result = await generateHandoffPrompt(conv.text, goal, ctx);
+			if (!result) {
 				ctx.ui.notify("Handoff cancelled.", "info");
 				return;
 			}
+			if (result.type === "error") {
+				ctx.ui.notify(`Handoff failed: ${result.message}`, "error");
+				return;
+			}
 
 			// Append programmatic file tracking (read/modified from tool calls)
-			prompt = appendFileOperations(prompt, conv.messages);
+			let prompt = appendFileOperations(result.text, conv.messages);
 
 			const currentSessionFile = ctx.sessionManager.getSessionFile();
 
@@ -407,9 +474,9 @@ export default function (pi: ExtensionAPI) {
 				pendingHandoffText.set(currentSessionFile, prompt);
 			}
 
-			const result = await ctx.newSession({ parentSession: currentSessionFile ?? undefined });
+			const sessionResult = await ctx.newSession({ parentSession: currentSessionFile ?? undefined });
 
-			if (result.cancelled) {
+			if (sessionResult.cancelled) {
 				if (currentSessionFile) pendingHandoffText.delete(currentSessionFile);
 				ctx.ui.notify("New session cancelled.", "info");
 				return;
@@ -440,12 +507,15 @@ export default function (pi: ExtensionAPI) {
 				return { content: [{ type: "text" as const, text: "No conversation to hand off." }] };
 			}
 
-			let prompt = await generateHandoffPrompt(conv.text, params.goal, ctx);
-			if (prompt === null) {
+			const result = await generateHandoffPrompt(conv.text, params.goal, ctx);
+			if (!result) {
 				return { content: [{ type: "text" as const, text: "Handoff cancelled." }] };
 			}
+			if (result.type === "error") {
+				return { content: [{ type: "text" as const, text: `Handoff failed: ${result.message}` }] };
+			}
 
-			prompt = appendFileOperations(prompt, conv.messages);
+			let prompt = appendFileOperations(result.text, conv.messages);
 
 			const currentSessionFile = ctx.sessionManager.getSessionFile();
 			prompt = wrapWithParentSession(prompt, currentSessionFile ?? null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssweens/pi-handoff",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "scripts": {
     "test": "bun test tests/",
     "test:watch": "bun test --watch tests/"

package/skills/pi-session-query/SKILL.md

@@ -12,9 +12,9 @@ This skill is automatically invoked in handed-off sessions when you need to look
 
 ## When to Use
 
-- When the handoff summary references a "Parent session" path
+- When the handoff summary references a "Parent session" or "Ancestor sessions" path
 - When you need specific details not included in the handoff summary
-- When you need to verify a decision or approach from the parent session
+- When you need to verify a decision or approach from the parent or an ancestor session
 - When you need file paths or code snippets from earlier work
 
 ## Usage
@@ -51,6 +51,7 @@ session_query("/path/to/session.jsonl", "Summarize the key decisions made")
 2. **Reference code** - Ask about specific files or functions when relevant
 3. **Verify before assuming** - If the handoff summary seems incomplete, query for details
 4. **Don't over-query** - The handoff summary should have most context; query only when needed
+5. **Check ancestors** - If the parent session doesn't have the info, try ancestor sessions listed in the handoff
 
 ## How It Works