pi-qq 0.1.4 → 0.1.6

package/README.md

@@ -4,13 +4,11 @@ Ask quick side questions about your current [pi](https://pi.dev) session without
 
 `pi-qq` adds `/qq <question>` plus an **alt+q** / **Option+Q** shortcut that toggles `/qq ` in the editor. The answer appears ephemerally in a bottom overlay, using the current session as read-only context, and nothing is added to the main conversation.
 
-![pi-qq bottom overlay answering a quick question](https://cdn.jsdelivr.net/npm/pi-qq/docs/screenshot.png)
-
 ## 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, gives the side call no tools, and keeps no `/qq` history.
+- **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
 
@@ -41,8 +39,17 @@ After installing, run `/reload` in pi or restart the session.
 
 ```text
 /qq <question>
+/qq --recent <question>
+/qq --full <question>
 ```
 
+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.
+
 ### Shortcut
 
 Press **alt+q** / **Option+Q** to toggle `/qq ` at the front of the editor:
@@ -60,7 +67,9 @@ 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.
 - The system prompt biases answers toward concise, direct responses.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-qq",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Pi extension. Ask context-aware side questions with /qq or alt+q without polluting the main transcript.",
   "keywords": [
     "pi-package",
@@ -25,7 +25,6 @@
     "qq.ts",
     "qq-ui.ts",
     "prompts/",
-    "docs/",
     "README.md",
     "LICENSE",
     "NOTICE"
@@ -33,8 +32,7 @@
   "pi": {
     "extensions": [
       "./index.ts"
-    ],
-    "image": "https://cdn.jsdelivr.net/npm/pi-qq/docs/screenshot.png"
+    ]
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

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.ts

@@ -31,15 +31,26 @@ 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 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 QqState {
 	snapshots: Map<string, { messages: Message[] }>;
 }
@@ -77,11 +88,128 @@ export function invalidateSnapshot(ctx: ExtensionContext): void {
 
 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 +220,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 +266,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,
@@ -220,8 +351,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,12 +364,12 @@ 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) {
 		overlayCtl.setAnswer(result.answer);