@ssweens/pi-handoff 1.1.1 → 1.3.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.
 
@@ -112,8 +114,25 @@ function extractFileOpsFromMessage(message: any, fileOps: FileOps): void {
 	}
 }
 
-/** Compute read-only and modified file lists, append to summary as XML tags. */
-function appendFileOperations(summary: string, messages: any[]): string {
+// ---------------------------------------------------------------------------
+// Collapsed file markers
+// ---------------------------------------------------------------------------
+// File lists are shown as compact markers in the editor (e.g. "[📂 12 read files]")
+// and expanded to full XML tags when the user submits via the input event hook.
+
+/** Pending file lists keyed by marker text → expanded XML content. */
+type FileMarkerStore = Map<string, string>;
+
+function createReadMarker(count: number): string {
+	return `[+${count} read filename${count === 1 ? "" : "s"}]`;
+}
+
+function createModifiedMarker(count: number): string {
+	return `[+${count} modified filename${count === 1 ? "" : "s"}]`;
+}
+
+/** Build collapsed markers + expansion map from tool-call messages. */
+function buildFileOperations(messages: any[]): { markers: string; expansions: FileMarkerStore } | null {
 	const fileOps = createFileOps();
 	for (const msg of messages) extractFileOpsFromMessage(msg, fileOps);
 
@@ -121,31 +140,50 @@ function appendFileOperations(summary: string, messages: any[]): string {
 	const readFiles = [...fileOps.read].filter((f) => !modified.has(f)).sort();
 	const modifiedFiles = [...modified].sort();
 
-	const sections: string[] = [];
+	if (readFiles.length === 0 && modifiedFiles.length === 0) return null;
+
+	const expansions: FileMarkerStore = new Map();
+	const markerLines: string[] = [];
+
 	if (readFiles.length > 0) {
-		sections.push(`<read-files>\n${readFiles.join("\n")}\n</read-files>`);
+		const marker = createReadMarker(readFiles.length);
+		expansions.set(marker, `<read-files>\n${readFiles.join("\n")}\n</read-files>`);
+		markerLines.push(marker);
 	}
 	if (modifiedFiles.length > 0) {
-		sections.push(`<modified-files>\n${modifiedFiles.join("\n")}\n</modified-files>`);
+		const marker = createModifiedMarker(modifiedFiles.length);
+		expansions.set(marker, `<modified-files>\n${modifiedFiles.join("\n")}\n</modified-files>`);
+		markerLines.push(marker);
 	}
 
-	return sections.length > 0 ? `${summary}\n\n${sections.join("\n\n")}` : summary;
+	return { markers: markerLines.join("\n"), expansions };
+}
+
+/** Expand all file markers in text using the stored expansions. */
+function expandFileMarkers(text: string, store: FileMarkerStore): string {
+	let result = text;
+	for (const [marker, expanded] of store) {
+		result = result.replaceAll(marker, expanded);
+	}
+	return result;
 }
 
 // ---------------------------------------------------------------------------
 // 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);
 
@@ -171,11 +209,11 @@ async function generateHandoffPrompt(
 
 			if (response.stopReason === "aborted") return null;
 			if (response.stopReason === "error") {
-				throw new Error(
+				const msg =
 					"errorMessage" in response && typeof (response as any).errorMessage === "string"
 						? (response as any).errorMessage
-						: "Handoff generation failed",
-				);
+						: "LLM request failed";
+				return { type: "error" as const, message: msg };
 			}
 
 			const text = response.content
@@ -184,14 +222,14 @@ async function generateHandoffPrompt(
 				.join("\n")
 				.trim();
 
-			return text.length > 0 ? text : null;
+			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;
@@ -203,24 +241,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}`;
 }
 
 // ---------------------------------------------------------------------------
@@ -250,6 +342,10 @@ export default function (pi: ExtensionAPI) {
 	// Store prompt keyed by parent session for the session_switch handler.
 	const pendingHandoffText = new Map<string, string>();
 
+	// -- Collapsed file marker expansion state --------------------------------
+	// Stores marker→XML mappings so the input hook can expand them on submit.
+	let activeFileMarkers: FileMarkerStore = new Map();
+
 	// ── session_switch ──────────────────────────────────────────────────────
 	// Set editor text for command-path handoffs + clear context filter.
 	pi.on("session_switch", async (event, ctx) => {
@@ -283,6 +379,26 @@ export default function (pi: ExtensionAPI) {
 		}
 	});
 
+	// ── input: expand collapsed file markers before LLM sees the text ───────
+	pi.on("input", (event) => {
+		if (activeFileMarkers.size === 0) return;
+
+		// Check if any markers are present in the input text
+		let hasMarkers = false;
+		for (const marker of activeFileMarkers.keys()) {
+			if (event.text.includes(marker)) {
+				hasMarkers = true;
+				break;
+			}
+		}
+		if (!hasMarkers) return;
+
+		const expanded = expandFileMarkers(event.text, activeFileMarkers);
+		// Clear after first expansion — markers are single-use (one handoff prompt)
+		activeFileMarkers = new Map();
+		return { action: "transform" as const, text: expanded, images: event.images };
+	});
+
 	// ── agent_end: deferred session switch for tool path ────────────────────
 	pi.on("agent_end", (_event, ctx) => {
 		if (!pendingHandoff) return;
@@ -335,24 +451,22 @@ 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) {
+		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);
+		// Build collapsed file markers from the messages being summarized
+		const fileOps = buildFileOperations(preparation.messagesToSummarize);
+		let prompt = fileOps
+			? `${handoffResult.text}\n\n${fileOps.markers}`
+			: handoffResult.text;
 
 		// Switch session via raw sessionManager (safe — no agent loop running)
 		const currentSessionFile = ctx.sessionManager.getSessionFile();
@@ -372,6 +486,8 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
+		// Activate markers for input hook expansion, then set editor text
+		if (fileOps) activeFileMarkers = fileOps.expansions;
 		ctx.ui.setEditorText(prompt);
 		ctx.ui.notify("Handoff ready — edit if needed, press Enter to send", "info");
 
@@ -399,14 +515,21 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
-			let prompt = await generateHandoffPrompt(conv.text, goal, ctx);
-			if (!prompt) {
+			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);
+			// Build collapsed file markers from tool calls
+			const fileOps = buildFileOperations(conv.messages);
+			let prompt = fileOps
+				? `${result.text}\n\n${fileOps.markers}`
+				: result.text;
 
 			const currentSessionFile = ctx.sessionManager.getSessionFile();
 
@@ -416,14 +539,19 @@ export default function (pi: ExtensionAPI) {
 			if (currentSessionFile) {
 				pendingHandoffText.set(currentSessionFile, prompt);
 			}
+			// Stage markers — they'll be activated in session_switch after editor text is set
+			const pendingMarkers = fileOps?.expansions;
 
-			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;
 			}
+
+			// Activate markers for the new session's input hook
+			if (pendingMarkers) activeFileMarkers = pendingMarkers;
 		},
 	});
 
@@ -450,16 +578,25 @@ 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) {
+			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);
+			const fileOps = buildFileOperations(conv.messages);
+			let prompt = fileOps
+				? `${result.text}\n\n${fileOps.markers}`
+				: result.text;
 
 			const currentSessionFile = ctx.sessionManager.getSessionFile();
 			prompt = wrapWithParentSession(prompt, currentSessionFile ?? null);
 
+			// Stage markers for activation after session switch
+			if (fileOps) activeFileMarkers = fileOps.expansions;
+
 			// Defer session switch to agent_end
 			pendingHandoff = {
 				prompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssweens/pi-handoff",
-  "version": "1.1.1",
+  "version": "1.3.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