pi-qq 0.1.5 → 0.1.7

package/README.md

@@ -7,8 +7,8 @@ Ask quick side questions about your current [pi](https://pi.dev) session without
 ## Why try it?
 
 - **A real side channel:** ask `/qq why are we changing this file?` while the main agent keeps working. The answer shows in a bottom overlay and does not enter the main transcript.
-- **Context-aware, intentionally constrained:** `/qq` passes a read-only clone of the main session, treats ambiguous references like “this”, “that”, “we”, and “the plan” as references to the active session, gives the side call no tools, and keeps no `/qq` history.
-- **Fast, low-friction UX:** press **alt+q** / **Option+Q** to toggle `/qq `, submit your question, then use **Esc** to cancel/dismiss or **↑/↓** to scroll longer answers.
+- **Context-aware, intentionally constrained:** `/qq` passes read-only main-session context, treats ambiguous references like “this”, “that”, “we”, and “the plan” as references to the active session, and gives the side call no tools. Previous `/qq` answers are available only through `/qq-history`; they are not fed back into future `/qq` calls.
+- **Fast, low-friction UX:** `/qq` uses recent context by default, automatically switches to broader context for retrospective questions, and supports explicit `--recent` / `--full` modes. Press **alt+q** / **Option+Q** to toggle `/qq `, then use **Esc** to cancel/dismiss or **↑/↓** to scroll longer answers.
 
 ## Demo
 
@@ -23,7 +23,7 @@ Another common flow:
 1. Press **alt+q** / **Option+Q**.
 2. Type `what's the risk with this plan?`.
 3. Hit Enter.
-4. Read the concise overlay answer; press **Esc** to dismiss.
+4. Read the concise overlay answer; press **Esc** to dismiss. If you close it too soon, run `/qq-history` to reopen recent answers.
 
 ## Install
 
@@ -39,8 +39,20 @@ After installing, run `/reload` in pi or restart the session.
 
 ```text
 /qq <question>
+/qq --recent <question>
+/qq --full <question>
+/qq-history
 ```
 
+By default, `/qq` chooses a context mode automatically:
+
+- **Recent mode** for immediate questions like `what did we do in the last turn?`, `what are we doing right now?`, or `why are we changing this?`.
+- **Full mode** for retrospective questions like `summarize this session`, `what did we decide so far?`, or `what did we try earlier?`.
+
+Use `--recent` when you want the fastest answer from the latest messages. Use `--full` when you explicitly want broader session context.
+
+Use `/qq-history` to reopen recent `/qq` answers from the current session. History is view-only and is not included as context for future `/qq` model calls.
+
 ### Shortcut
 
 Press **alt+q** / **Option+Q** to toggle `/qq ` at the front of the editor:
@@ -58,9 +70,12 @@ Press **alt+q** / **Option+Q** to toggle `/qq ` at the front of the editor:
 ## Design constraints
 
 - The main transcript is never polluted by `/qq` questions or answers.
-- The side call receives the current session as read-only context.
+- The side call receives read-only main-session context.
+- Recent mode sends only the latest messages for speed; full mode sends broader bounded context.
+- Large text parts are clipped, thinking blocks are removed, and images are omitted from the side-call context for speed.
 - The side call has no tools.
-- `/qq` stores no quick-question history; each call is independent except for the main-session context.
+- Recent `/qq` answers are kept in memory only so `/qq-history` can reopen them after dismissal.
+- `/qq-history` is view-only; it is not used as context for future `/qq` model calls.
 - The system prompt biases answers toward concise, direct responses.
 
 ## License

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-qq",
-  "version": "0.1.5",
-  "description": "Pi extension. Ask context-aware side questions with /qq or alt+q without polluting the main transcript.",
+  "version": "0.1.7",
+  "description": "Pi extension. Ask context-aware side questions with /qq or alt+q, then reopen answers with /qq-history.",
   "keywords": [
     "pi-package",
     "pi-extension",
@@ -9,7 +9,7 @@
     "side-question",
     "context-aware",
     "transcript-safe",
-    "no-history",
+    "history",
     "question",
     "shortcut",
     "keybinding",

package/prompts/qq-system.txt

@@ -2,7 +2,7 @@ You answer quick questions about the user's main pi session.
 
 Default ambiguous references to the main session. "This", "that", "it", "we", "the plan", "the code", "the issue", and "what you were doing" refer to the primary conversation unless the user clearly says otherwise.
 
-Treat the primary conversation as background only. Do not continue prior work, resume tool calls, or start a task. Answer only the quick question.
+Treat the primary conversation as background only. You may receive recent context or broader bounded context. Do not continue prior work, resume tool calls, or start a task. Answer only the quick question.
 
 Optimize for speed and brevity. Answer in one short sentence by default. Use up to 3 terse bullets only when necessary. No preamble. No restating the question. No summary. If uncertain or missing context, say so in one short sentence.
 

package/qq-ui.ts

@@ -12,7 +12,7 @@
  *   Esc → abort in-flight call + dismiss
  *   ↑/↓ → scroll when content exceeds terminal
  *
- * Does not keep quick-question history.
+ * Used for both live /qq answers and view-only /qq-history.
  */
 
 import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
@@ -49,6 +49,7 @@ export interface ShowQqOverlayParams {
 	ctx: ExtensionCommandContext;
 	question: string;
 	controller: AbortController;
+	commandLabel?: string;
 }
 
 export interface ShowQqOverlayResult {
@@ -68,6 +69,7 @@ export class QqOverlayController implements Component {
 		private readonly tui: TUI,
 		private readonly done: (result?: undefined) => void,
 		private readonly controller: AbortController,
+		private readonly commandLabel: string = QQ_LITERAL,
 	) {}
 
 	setAnswer(text: string): void {
@@ -128,7 +130,7 @@ export class QqOverlayController implements Component {
 	}
 
 	private renderBanner(width: number): string {
-		const prefix = `${SIDE_PAD}${QQ_LITERAL} `;
+		const prefix = `${SIDE_PAD}${this.commandLabel} `;
 		const prefixWidth = visibleWidth(prefix);
 		const questionWidth = Math.max(0, width - prefixWidth);
 		const truncatedQuestion = truncateToWidth(this.question, questionWidth, "…", false);
@@ -170,7 +172,14 @@ export function showQqOverlay(params: ShowQqOverlayParams): ShowQqOverlayResult
 
 	const overlayPromise = params.ctx.ui.custom<void>(
 		(tui, theme, _keybindings, done) => {
-			const controller = new QqOverlayController(params.question, theme, tui, done, params.controller);
+			const controller = new QqOverlayController(
+				params.question,
+				theme,
+				tui,
+				done,
+				params.controller,
+				params.commandLabel,
+			);
 			resolveReady(controller);
 			return controller;
 		},

package/qq.ts

@@ -5,7 +5,7 @@
  * conversation as read-only context. The answer is rendered ephemerally in a
  * bottom-slot overlay and never enters the main session transcript.
  *
- * Does not keep quick-question history.
+ * Keeps in-memory, view-only answer history for /qq-history.
  */
 
 import { readFileSync } from "node:fs";
@@ -27,21 +27,42 @@ import {
 import { showQqOverlay } from "./qq-ui.js";
 
 export const QQ_COMMAND_NAME = "qq";
+export const QQ_HISTORY_COMMAND_NAME = "qq-history";
 export const QQ_PREFIX = `/${QQ_COMMAND_NAME} `;
 export const QQ_STATE_KEY = Symbol.for("pi-qq:qq");
 
 const MSG_REQUIRES_INTERACTIVE = "/qq requires interactive mode";
-const MSG_USAGE = "Usage: /qq <question>";
+const MSG_USAGE = "Usage: /qq [--recent|--full] <question>";
 const MSG_NO_MODEL = "/qq requires an active model";
 const ERR_EMPTY_RESPONSE = "/qq returned no text content.";
+const MSG_NO_HISTORY = "No /qq history for this session yet";
+const QQ_HISTORY_LIMIT = 20;
+const RECENT_CONTEXT_MESSAGE_LIMIT = 12;
+const FULL_CONTEXT_HEAD_MESSAGE_LIMIT = 4;
+const FULL_CONTEXT_TAIL_MESSAGE_LIMIT = 80;
+const MAX_TEXT_CHARS_PER_PART = 4_000;
 
 const errMisconfigured = (label: string, err: string) => `/qq model (${label}) is misconfigured: ${err}`;
 const errNoApiKey = (label: string) => `/qq model (${label}) has no API key available.`;
 const errCallFailed = (err: string | undefined) => `/qq call failed: ${err ?? "unknown error"}`;
 const errCallThrew = (msg: string) => `/qq call threw: ${msg}`;
 
+type QqContextMode = "recent" | "full";
+
+interface ParsedQqArgs {
+	question: string;
+	mode: QqContextMode;
+}
+
+interface QqHistoryEntry {
+	question: string;
+	answer: string;
+	timestamp: number;
+}
+
 interface QqState {
 	snapshots: Map<string, { messages: Message[] }>;
+	histories: Map<string, QqHistoryEntry[]>;
 }
 
 export const QQ_SYSTEM_PROMPT = readFileSync(
@@ -53,7 +74,7 @@ function getState(): QqState {
 	const globalState = globalThis as unknown as { [k: symbol]: QqState | undefined };
 	let state = globalState[QQ_STATE_KEY];
 	if (!state) {
-		state = { snapshots: new Map() };
+		state = { snapshots: new Map(), histories: new Map() };
 		globalState[QQ_STATE_KEY] = state;
 	}
 	return state;
@@ -71,17 +92,169 @@ function setSnapshot(ctx: ExtensionContext, snapshot: { messages: Message[] }):
 	getState().snapshots.set(getSessionFile(ctx), snapshot);
 }
 
+function getSessionHistory(ctx: ExtensionContext): QqHistoryEntry[] {
+	const key = getSessionFile(ctx);
+	const state = getState();
+	let history = state.histories.get(key);
+	if (!history) {
+		history = [];
+		state.histories.set(key, history);
+	}
+	return history;
+}
+
+function pushSessionHistory(ctx: ExtensionContext, entry: QqHistoryEntry): void {
+	const history = getSessionHistory(ctx);
+	history.push(entry);
+	if (history.length > QQ_HISTORY_LIMIT) {
+		history.splice(0, history.length - QQ_HISTORY_LIMIT);
+	}
+}
+
 export function invalidateSnapshot(ctx: ExtensionContext): void {
 	getState().snapshots.delete(getSessionFile(ctx));
 }
 
+function formatHistoryTimestamp(timestamp: number): string {
+	return new Date(timestamp).toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" });
+}
+
+function formatQqHistory(entries: QqHistoryEntry[]): string {
+	return entries
+		.slice()
+		.reverse()
+		.map((entry, index) => {
+			const question = entry.question.replace(/\s+/g, " ").trim();
+			const answer = entry.answer.trim();
+			return `${index + 1}. ${formatHistoryTimestamp(entry.timestamp)} — /qq ${question}\n${answer}`;
+		})
+		.join("\n\n");
+}
+
 export function assistantMessageText(msg: AssistantMessage): string {
 	return msg.content
-		.filter((c): c is { type: "text"; text: string } => c.type === "text")
-		.map((c) => c.text)
+		.filter((content): content is { type: "text"; text: string } => content.type === "text")
+		.map((content) => content.text)
 		.join("\n");
 }
 
+function clipText(text: string): string {
+	if (text.length <= MAX_TEXT_CHARS_PER_PART) return text;
+	return `${text.slice(0, MAX_TEXT_CHARS_PER_PART)}\n[…truncated for /qq speed…]`;
+}
+
+function trimContentArray<T extends Array<{ type: string }>>(content: T): T {
+	return content
+		.filter((part) => part.type !== "thinking")
+		.map((part) => {
+			if (part.type === "text" && "text" in part && typeof part.text === "string") {
+				return { ...part, text: clipText(part.text) };
+			}
+			if (part.type === "image") {
+				return { type: "text", text: "[image omitted for /qq speed]" };
+			}
+			return part;
+		}) as T;
+}
+
+function trimUserContent(content: UserMessage["content"]): UserMessage["content"] {
+	if (typeof content === "string") return clipText(content);
+	return trimContentArray(content);
+}
+
+function trimMessageForContext(message: Message): Message {
+	if (message.role === "assistant") {
+		return { ...message, content: trimContentArray(message.content) };
+	}
+	if (message.role === "user") {
+		return { ...message, content: trimUserContent(message.content) };
+	}
+	return { ...message, content: trimContentArray(message.content) };
+}
+
+function selectRecentContextMessages(messages: Message[]): Message[] {
+	return messages.slice(-RECENT_CONTEXT_MESSAGE_LIMIT).map(trimMessageForContext);
+}
+
+function selectFullContextMessages(messages: Message[]): Message[] {
+	if (messages.length <= FULL_CONTEXT_HEAD_MESSAGE_LIMIT + FULL_CONTEXT_TAIL_MESSAGE_LIMIT) {
+		return messages.map(trimMessageForContext);
+	}
+	return [
+		...messages.slice(0, FULL_CONTEXT_HEAD_MESSAGE_LIMIT),
+		...messages.slice(-FULL_CONTEXT_TAIL_MESSAGE_LIMIT),
+	].map(trimMessageForContext);
+}
+
+function selectContextMessages(messages: Message[], mode: QqContextMode): Message[] {
+	return mode === "full" ? selectFullContextMessages(messages) : selectRecentContextMessages(messages);
+}
+
+function parseQqArgs(args: string): ParsedQqArgs {
+	const trimmed = args.trim();
+	if (trimmed.startsWith("--recent ")) {
+		return { mode: "recent", question: trimmed.slice("--recent ".length).trim() };
+	}
+	if (trimmed === "--recent") {
+		return { mode: "recent", question: "" };
+	}
+	if (trimmed.startsWith("--full ")) {
+		return { mode: "full", question: trimmed.slice("--full ".length).trim() };
+	}
+	if (trimmed === "--full") {
+		return { mode: "full", question: "" };
+	}
+	return { mode: detectContextMode(trimmed), question: trimmed };
+}
+
+function includesAny(text: string, phrases: string[]): boolean {
+	return phrases.some((phrase) => text.includes(phrase));
+}
+
+function detectContextMode(question: string): QqContextMode {
+	const normalized = question.toLowerCase();
+
+	const recentPhrases = [
+		"last turn",
+		"previous turn",
+		"last message",
+		"latest",
+		"just now",
+		"what did we just",
+		"right now",
+		"current",
+		"currently",
+		"most recent",
+		"the last thing",
+	];
+	if (includesAny(normalized, recentPhrases)) {
+		return "recent";
+	}
+
+	const fullPhrases = [
+		"entire session",
+		"whole session",
+		"this session",
+		"from the beginning",
+		"full context",
+		"so far",
+		"overall",
+		"earlier",
+		"previously",
+		"at the start",
+		"originally",
+		"what have we done",
+		"what did we decide",
+		"summarize",
+		"recap",
+	];
+	if (includesAny(normalized, fullPhrases)) {
+		return "full";
+	}
+
+	return "recent";
+}
+
 export interface QqExecResult {
 	ok: boolean;
 	answer?: string;
@@ -92,23 +265,26 @@ export interface QqExecResult {
 	aborted?: boolean;
 }
 
-function readBranchMessages(ctx: ExtensionContext): Message[] {
+function readBranchMessages(ctx: ExtensionContext, mode: QqContextMode): Message[] {
 	const cached = getSnapshot(ctx);
-	if (cached) return cached.messages;
+	if (cached) return selectContextMessages(cached.messages, mode);
 
 	const branch = ctx.sessionManager.getBranch() as SessionEntry[];
-	const agentMessages = branch
-		.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
-		.map((entry) => entry.message);
-	return convertToLlm(agentMessages);
+	const messageEntries = branch.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message");
+	const selectedEntries = mode === "recent" ? messageEntries.slice(-RECENT_CONTEXT_MESSAGE_LIMIT) : messageEntries;
+	return selectContextMessages(
+		convertToLlm(selectedEntries.map((entry) => entry.message)),
+		mode,
+	);
 }
 
-function buildQqMessages(ctx: ExtensionContext, userMessage: UserMessage): Message[] {
-	return [...readBranchMessages(ctx), userMessage];
+function buildQqMessages(ctx: ExtensionContext, userMessage: UserMessage, mode: QqContextMode): Message[] {
+	return [...readBranchMessages(ctx, mode), userMessage];
 }
 
 export async function executeQq(
 	question: string,
+	mode: QqContextMode,
 	ctx: ExtensionContext,
 	controller: AbortController,
 ): Promise<QqExecResult> {
@@ -135,7 +311,7 @@ export async function executeQq(
 	try {
 		const response = await completeSimple(
 			model,
-			{ systemPrompt: QQ_SYSTEM_PROMPT, messages: buildQqMessages(ctx, userMessage), tools: [] },
+			{ systemPrompt: QQ_SYSTEM_PROMPT, messages: buildQqMessages(ctx, userMessage, mode), tools: [] },
 			{
 				apiKey: auth.apiKey,
 				headers: auth.headers,
@@ -213,6 +389,10 @@ export function registerQqCommand(pi: ExtensionAPI): void {
 		description: "Ask a quick question without polluting the main conversation",
 		handler: (args: string, ctx: ExtensionCommandContext) => handleQqCommand(args, ctx),
 	});
+	pi.registerCommand(QQ_HISTORY_COMMAND_NAME, {
+		description: "Show recent /qq answers for this session",
+		handler: (_args: string, ctx: ExtensionCommandContext) => handleQqHistoryCommand(ctx),
+	});
 }
 
 async function handleQqCommand(args: string, ctx: ExtensionCommandContext): Promise<void> {
@@ -220,8 +400,8 @@ async function handleQqCommand(args: string, ctx: ExtensionCommandContext): Prom
 		ctx.ui.notify(MSG_REQUIRES_INTERACTIVE, "error");
 		return;
 	}
-	const question = args.trim();
-	if (!question) {
+	const parsedArgs = parseQqArgs(args);
+	if (!parsedArgs.question) {
 		ctx.ui.notify(MSG_USAGE, "warning");
 		return;
 	}
@@ -233,14 +413,19 @@ async function handleQqCommand(args: string, ctx: ExtensionCommandContext): Prom
 	const controller = new AbortController();
 	const { overlayPromise, controllerReady } = showQqOverlay({
 		ctx,
-		question,
+		question: parsedArgs.question,
 		controller,
 	});
 
 	const overlayCtl = await controllerReady;
-	const result = await executeQq(question, ctx, controller);
+	const result = await executeQq(parsedArgs.question, parsedArgs.mode, ctx, controller);
 
 	if (result.ok && result.answer) {
+		pushSessionHistory(ctx, {
+			question: parsedArgs.question,
+			answer: result.answer,
+			timestamp: Date.now(),
+		});
 		overlayCtl.setAnswer(result.answer);
 	} else if (result.aborted) {
 		// User Esc'd — overlay already dismissed via done(); no further action.
@@ -250,3 +435,27 @@ async function handleQqCommand(args: string, ctx: ExtensionCommandContext): Prom
 
 	await overlayPromise;
 }
+
+async function handleQqHistoryCommand(ctx: ExtensionCommandContext): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify(MSG_REQUIRES_INTERACTIVE, "error");
+		return;
+	}
+	const history = getSessionHistory(ctx);
+	if (history.length === 0) {
+		ctx.ui.notify(MSG_NO_HISTORY, "info");
+		return;
+	}
+
+	const controller = new AbortController();
+	const { overlayPromise, controllerReady } = showQqOverlay({
+		ctx,
+		question: `${history.length} recent answer${history.length === 1 ? "" : "s"}`,
+		controller,
+		commandLabel: "/qq-history",
+	});
+
+	const overlayCtl = await controllerReady;
+	overlayCtl.setAnswer(formatQqHistory(history));
+	await overlayPromise;
+}