@ssweens/pi-compaxxt 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ssweens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# pi-compaxxt
+
+```bash
+pi install @ssweens/pi-compaxxt
+```
+
+Enhanced compaction for [pi](https://github.com/badlogic/pi-mono). Two improvements to every compaction, zero extra LLM calls.
+
+## Features
+
+### Session Context
+
+Every compaction summary is prepended with the current session file path and thread ID:
+
+```markdown
+## Session Context
+**Session:** `/Users/you/.pi/agent/sessions/abc123/session.jsonl`
+**Thread ID:** `e7f2a3c1-...`
+
+Use the `session_query` tool to retrieve specific context from messages that were summarized away.
+
+---
+
+## Goal
+...
+```
+
+After compaction, the LLM knows exactly where to look if it needs older context that was summarized away. The bundled `session_query` tool makes this retrieval cheap — it doesn't load the full session, just answers a targeted question from it.
+
+### LLM-Judged Important Files
+
+The compaction prompt is augmented to ask the LLM to identify the most goal-relevant files as part of generating the summary. The file sections are restructured:
+
+```xml
+<important-files>
+src/core/compaction.ts
+extensions/handoff.ts
+</important-files>
+
+<modified-files>
+src/core/compaction.ts
+extensions/handoff.ts
+src/utils.ts
+</modified-files>
+
+<other-read-files>
+package.json
+docs/api.md
+</other-read-files>
+```
+
+Files are selected using these criteria:
+- Directly related to accomplishing the goal
+- Contain reference code or patterns to follow
+- Will need to be read, edited, or created
+- Provide important context or constraints
+
+`<modified-files>` is left untouched (intentional overlap with important-files is fine). `<read-files>` becomes `<other-read-files>` with the important ones pruned out.
+
+If the LLM doesn't output a parseable `## Most Important Files` section, the extension falls back to the default `<read-files>`/`<modified-files>` format silently.
+
+## Components
+
+| Component | Type | Description |
+|-----------|------|-------------|
+| [compaction.ts](extensions/compaction.ts) | Extension | `session_before_compact` hook — session context + file restructuring |
+| [session-query.ts](extensions/session-query.ts) | Extension | `session_query` tool for querying session history |
+| [pi-session-query/](skills/pi-session-query/SKILL.md) | Skill | Instructions for using `session_query` |
+
+## Notes
+
+- If you also have `@ssweens/pi-handoff` installed, both packages register the `session_query` tool. Pi will warn about the duplicate — it's harmless, one will shadow the other.
+- Works with `/compact [instructions]` — user instructions are preserved and the file importance prompt is appended after them.
+- On any compaction error, falls back to pi's default compaction silently (with a warning notification).
+
+## License
+
+MIT

package/extensions/compaction.ts

@@ -0,0 +1,209 @@
+/**
+ * Pi-Compaxxt Compaction Extension
+ *
+ * Enhances pi's default compaction with two features:
+ *
+ * 1. Session context block prepended to every summary — session file path and
+ *    thread ID so the post-compaction LLM can use session_query to retrieve
+ *    older context that was summarized away.
+ *
+ * 2. LLM-judged <important-files> section — the compaction prompt is augmented
+ *    to ask the LLM to identify the most goal-relevant files as part of
+ *    generating the summary (one LLM call, no extra cost). The file sections
+ *    are then restructured:
+ *      <important-files>    — LLM-ranked top 3-5 files
+ *      <modified-files>     — all modified files, unchanged from default
+ *      <other-read-files>   — read-only files minus the important ones
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { compact } from "@mariozechner/pi-coding-agent";
+
+// ---------------------------------------------------------------------------
+// Session context block
+// ---------------------------------------------------------------------------
+
+function buildSessionContextBlock(
+	sessionFile: string | undefined,
+	leafId: string | null,
+): string {
+	const lines: string[] = ["## Session Context"];
+	if (sessionFile) lines.push(`**Session:** \`${sessionFile}\``);
+	if (leafId) lines.push(`**Thread ID:** \`${leafId}\``);
+	lines.push(
+		"",
+		"Use the `session_query` tool to retrieve specific context from messages that were summarized away.",
+		"",
+		"---",
+		"",
+	);
+	return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Important files: parsing + file section restructuring
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the ## Most Important Files section from the LLM summary.
+ * Validates each path against the known file list to guard against hallucination.
+ */
+function parseImportantFiles(summary: string, knownFiles: Set<string>): string[] {
+	const match = summary.match(/\n## Most Important Files\n([\s\S]+?)(?=\n\n<|$)/);
+	if (!match) return [];
+
+	return match[1]
+		.split("\n")
+		.map((line) => line.replace(/^[-*]\s*/, "").trim()) // strip bullets if LLM added them
+		.map((line) => line.split(/\s+/)[0]) // strip any inline explanation after the path
+		.filter((path) => path.length > 0 && knownFiles.has(path));
+}
+
+/**
+ * Restructure the file XML sections in the summary:
+ *   - Remove ## Most Important Files from markdown (now encoded in XML)
+ *   - Remove <read-files> and replace with <other-read-files> (pruned)
+ *   - Insert <important-files> before <modified-files>
+ *   - Leave <modified-files> untouched (may overlap with important-files — intentional)
+ */
+function restructureFileSections(
+	summary: string,
+	importantFiles: string[],
+	readFiles: string[],
+): string {
+	const importantSet = new Set(importantFiles);
+
+	// Remove the ## Most Important Files markdown section
+	let result = summary.replace(/\n## Most Important Files\n[\s\S]+?(?=\n\n<|$)/, "");
+
+	// Remove the existing <read-files> block entirely
+	result = result.replace(/\n\n<read-files>\n[\s\S]+?\n<\/read-files>/, "");
+
+	// Compute other-read-files: read-only files not in the important list
+	const otherReadFiles = readFiles.filter((f) => !importantSet.has(f));
+
+	const importantSection = `<important-files>\n${importantFiles.join("\n")}\n</important-files>`;
+	const otherReadSection =
+		otherReadFiles.length > 0
+			? `<other-read-files>\n${otherReadFiles.join("\n")}\n</other-read-files>`
+			: "";
+
+	// Insert <important-files> before <modified-files> if present, otherwise append
+	if (result.includes("<modified-files>")) {
+		result = result.replace(
+			"\n\n<modified-files>",
+			`\n\n${importantSection}\n\n<modified-files>`,
+		);
+		if (otherReadSection) {
+			result = result.replace("</modified-files>", `</modified-files>\n\n${otherReadSection}`);
+		}
+	} else {
+		// Read-only session — no modified-files section
+		result += `\n\n${importantSection}`;
+		if (otherReadSection) result += `\n\n${otherReadSection}`;
+	}
+
+	return result;
+}
+
+// ---------------------------------------------------------------------------
+// Extension
+// ---------------------------------------------------------------------------
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_before_compact", async (event, ctx) => {
+		if (!ctx.model) return;
+
+		const apiKey = await ctx.modelRegistry.getApiKey(ctx.model);
+		if (!apiKey) return;
+
+		const { preparation, customInstructions: userInstructions, signal } = event;
+
+		// Equivalent to computeFileLists() from compaction/utils — not re-exported by the package
+		const modified = new Set([...preparation.fileOps.edited, ...preparation.fileOps.written]);
+		const readFiles = [...preparation.fileOps.read].filter((f) => !modified.has(f)).sort();
+		const modifiedFiles = [...modified].sort();
+		const allFiles = [...readFiles, ...modifiedFiles];
+
+		// Build file importance instruction, respecting any user /compact [instructions]
+		let combinedInstructions = userInstructions ?? "";
+
+		if (allFiles.length > 0) {
+			const fileLines: string[] = [];
+			if (modifiedFiles.length > 0) {
+				fileLines.push(`Modified:\n${modifiedFiles.map((f) => `  ${f}`).join("\n")}`);
+			}
+			if (readFiles.length > 0) {
+				fileLines.push(`Read-only:\n${readFiles.map((f) => `  ${f}`).join("\n")}`);
+			}
+
+			const fileImportanceInstruction = `After all other sections, add:
+
+## Most Important Files
+Identify files that are:
+- Directly related to accomplishing the goal
+- Contain reference code or patterns to follow
+- Will need to be read, edited, or created
+- Provide important context or constraints
+
+List 3-5 files from those accessed this session, most important first.
+One path per line, no bullets, no explanation.
+
+All files accessed this session:
+${fileLines.join("\n\n")}`;
+
+			combinedInstructions = combinedInstructions
+				? `${combinedInstructions}\n\n${fileImportanceInstruction}`
+				: fileImportanceInstruction;
+		}
+
+		try {
+			const result = await compact(
+				preparation,
+				ctx.model,
+				apiKey,
+				combinedInstructions || undefined,
+				signal,
+			);
+
+			if (signal.aborted) return;
+
+			let summary = result.summary;
+
+			// Parse and restructure file sections
+			if (allFiles.length > 0) {
+				const knownFiles = new Set(allFiles);
+				const importantFiles = parseImportantFiles(summary, knownFiles);
+				if (importantFiles.length > 0) {
+					summary = restructureFileSections(summary, importantFiles, readFiles);
+				}
+				// If LLM didn't follow the format, summary falls back to default
+				// <read-files>/<modified-files> sections untouched
+			}
+
+			// Prepend session context block
+			const sessionFile = ctx.sessionManager.getSessionFile();
+			const leafId = ctx.sessionManager.getLeafId();
+			if (sessionFile || leafId) {
+				summary = buildSessionContextBlock(sessionFile, leafId) + summary;
+			}
+
+			return {
+				compaction: {
+					summary,
+					firstKeptEntryId: result.firstKeptEntryId,
+					tokensBefore: result.tokensBefore,
+					details: result.details,
+				},
+			};
+		} catch (err) {
+			if (!signal.aborted) {
+				ctx.ui.notify(
+					`pi-compaxxt: compaction failed, using default. ${err instanceof Error ? err.message : String(err)}`,
+					"warning",
+				);
+			}
+			return; // fall back to default compaction
+		}
+	});
+}

package/extensions/session-query.ts

@@ -0,0 +1,219 @@
+/**
+ * Session Query Extension - Query previous pi sessions
+ *
+ * Provides a tool the model can use to query past sessions for context,
+ * decisions, code changes, or other information.
+ *
+ * Works with handoff: when a handoff prompt includes "Parent session: <path>",
+ * the model can use this tool to look up details from that session.
+ *
+ * Based on pi-amplike's session-query, enhanced with:
+ * - Better error handling
+ * - Rendered results with markdown support
+ * - Session metadata in response
+ */
+
+import { complete, type Message } from "@mariozechner/pi-ai";
+import type { ExtensionAPI, SessionEntry } from "@mariozechner/pi-coding-agent";
+import {
+	SessionManager,
+	convertToLlm,
+	serializeConversation,
+	getMarkdownTheme,
+} from "@mariozechner/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+import * as fs from "node:fs";
+
+// Maximum characters of serialized conversation to send to the query LLM.
+// Prevents blowing context when the parent session is very large.
+// ~100k chars ≈ ~25-30k tokens for most models — leaves room for the
+// question, system prompt, and answer within a 128k context window.
+const MAX_SESSION_CHARS = 100_000;
+
+const QUERY_SYSTEM_PROMPT = `Extract information relevant to the question from the session history.
+Return a concise answer using bullet points where appropriate.
+Use code pointers (path/to/file.ts:42 or path/to/file.ts#functionName) when referencing specific code.
+If the information is not in the session, say so clearly.`;
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "session_query",
+		label: (params) => `Query Session: ${params.question}`,
+		description:
+			"Query a previous pi session file for context, decisions, or information. Use when you need to look up what happened in a parent session or any other session. The sessionPath should be the full path to a .jsonl session file.",
+
+		parameters: Type.Object({
+			sessionPath: Type.String({
+				description:
+					"Full path to the session file (e.g., /home/user/.pi/agent/sessions/.../session.jsonl)",
+			}),
+			question: Type.String({
+				description:
+					"What you want to know about that session (e.g., 'What files were modified?' or 'What approach was chosen?')",
+			}),
+		}),
+
+		renderResult(result, _options, theme) {
+			const container = new Container();
+
+			if (result.content && result.content[0]?.text) {
+				const text = result.content[0].text;
+
+				// Check for error format
+				if (result.details?.error) {
+					container.addChild(new Text(theme.fg("error", text), 0, 0));
+					return container;
+				}
+
+				// Parse structured response: **Query:** question\n\n---\n\nanswer
+				const match = text.match(/\*\*Query:\*\* (.+?)\n\n---\n\n([\s\S]+)/);
+
+				if (match) {
+					const [, query, answer] = match;
+					container.addChild(new Text(theme.bold("Query: ") + theme.fg("accent", query), 0, 0));
+					container.addChild(new Spacer(1));
+					// Render the answer as markdown
+					container.addChild(
+						new Markdown(answer.trim(), 0, 0, getMarkdownTheme(), {
+							color: (text: string) => theme.fg("toolOutput", text),
+						}),
+					);
+				} else {
+					// Fallback for other formats
+					container.addChild(new Text(theme.fg("toolOutput", text), 0, 0));
+				}
+
+				// Show metadata if available
+				if (result.details?.messageCount) {
+					const truncNote = result.details.truncated ? ", truncated" : "";
+					container.addChild(new Spacer(1));
+					container.addChild(
+						new Text(
+							theme.fg("dim", `(${result.details.messageCount} messages in session${truncNote})`),
+							0,
+							0,
+						),
+					);
+				}
+			}
+
+			return container;
+		},
+
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			const { sessionPath, question } = params;
+
+			// Helper for error returns
+			const errorResult = (text: string) => ({
+				content: [{ type: "text" as const, text }],
+				details: { error: true },
+			});
+
+			// Validate session path
+			if (!sessionPath.endsWith(".jsonl")) {
+				return errorResult(
+					`Error: Invalid session path. Expected a .jsonl file, got: ${sessionPath}`,
+				);
+			}
+
+			// Check if file exists
+			if (!fs.existsSync(sessionPath)) {
+				return errorResult(`Error: Session file not found: ${sessionPath}`);
+			}
+
+			onUpdate?.({
+				content: [
+					{
+						type: "text",
+						text: `Querying session: ${question}`,
+					},
+				],
+				details: { status: "loading", question },
+			});
+
+			// Load the session
+			let sessionManager: SessionManager;
+			try {
+				sessionManager = SessionManager.open(sessionPath);
+			} catch (err) {
+				return errorResult(`Error loading session: ${err}`);
+			}
+
+			// Get conversation from the session
+			const branch = sessionManager.getBranch();
+			const messages = branch
+				.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
+				.map((entry) => entry.message);
+
+			if (messages.length === 0) {
+				return {
+					content: [{ type: "text" as const, text: "Session is empty - no messages found." }],
+					details: { empty: true },
+				};
+			}
+
+			// Serialize the conversation, truncating if too large
+			const llmMessages = convertToLlm(messages);
+			let conversationText = serializeConversation(llmMessages);
+			let truncated = false;
+
+			if (conversationText.length > MAX_SESSION_CHARS) {
+				// Keep the tail (most recent context) — more likely to be relevant
+				conversationText = "…[earlier messages truncated]…\n\n"
+					+ conversationText.slice(-MAX_SESSION_CHARS);
+				truncated = true;
+			}
+
+			// Use LLM to answer the question
+			if (!ctx.model) {
+				return errorResult("Error: No model available to analyze the session.");
+			}
+
+			try {
+				const apiKey = await ctx.modelRegistry.getApiKey(ctx.model);
+
+				const userMessage: Message = {
+					role: "user",
+					content: [
+						{
+							type: "text",
+							text: `## Session Conversation\n\n${conversationText}\n\n## Question\n\n${question}`,
+						},
+					],
+					timestamp: Date.now(),
+				};
+
+				const response = await complete(
+					ctx.model,
+					{ systemPrompt: QUERY_SYSTEM_PROMPT, messages: [userMessage] },
+					{ apiKey, signal },
+				);
+
+				if (response.stopReason === "aborted") {
+					return {
+						content: [{ type: "text" as const, text: "Query was cancelled." }],
+						details: { cancelled: true },
+					};
+				}
+
+				const answer = response.content
+					.filter((c): c is { type: "text"; text: string } => c.type === "text")
+					.map((c) => c.text)
+					.join("\n");
+
+				return {
+					content: [{ type: "text" as const, text: `**Query:** ${question}\n\n---\n\n${answer}` }],
+					details: {
+						sessionPath,
+						question,
+						messageCount: messages.length,
+						truncated,
+					},
+				};
+			} catch (err) {
+				return errorResult(`Error querying session: ${err}`);
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@ssweens/pi-compaxxt",
+  "version": "1.0.0",
+  "description": "Enhanced compaction for pi — session context and LLM-ranked important files",
+  "keywords": [
+    "pi-package"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "author": "ssweens",
+  "files": [
+    "extensions/",
+    "skills/",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "extensions"
+    ],
+    "skills": [
+      "skills"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  }
+}

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

@@ -0,0 +1,58 @@
+---
+name: pi-session-query
+description: Query previous pi sessions to retrieve context, decisions, code changes, or other information. Use when you need to look up what happened in a parent session or any other session file.
+disable-model-invocation: true
+---
+
+# Pi Session Query
+
+Query pi session files to retrieve context from past conversations.
+
+This skill is automatically invoked in handed-off sessions when you need to look up details from the parent session.
+
+## When to Use
+
+- 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 or an ancestor session
+- When you need file paths or code snippets from earlier work
+
+## Usage
+
+Use the `session_query` tool:
+
+```
+session_query(sessionPath, question)
+```
+
+**Parameters:**
+- `sessionPath`: Full path to the session file (provided in the "Parent session:" line)
+- `question`: Specific question about that session
+
+## Examples
+
+```typescript
+// Find what files were changed
+session_query("/path/to/session.jsonl", "What files were modified?")
+
+// Get approach details
+session_query("/path/to/session.jsonl", "What approach was chosen for authentication?")
+
+// Get specific code decisions
+session_query("/path/to/session.jsonl", "What error handling pattern was used?")
+
+// Summarize key decisions
+session_query("/path/to/session.jsonl", "Summarize the key decisions made")
+```
+
+## Best Practices
+
+1. **Be specific** - Ask targeted questions for better results
+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
+
+The tool loads the referenced session file, extracts the conversation history, and uses the LLM to answer your question based on its contents. This allows context retrieval without loading the full parent session into your context window.