pi-qq 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-qq contributors
+
+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/NOTICE

@@ -0,0 +1 @@
+This package includes MIT-licensed portions copyright (c) 2026 juicesharp.

package/README.md

@@ -0,0 +1,49 @@
+# pi-qq
+
+A [pi](https://pi.dev) package that provides a self-contained `/qq` command for quick questions about the **main pi session**, plus an **alt+q** / **Option+Q** shortcut that toggles the `/qq ` prefix in the editor.
+
+Do not install this alongside another package that registers `/qq`, because command names must be unique.
+
+## What it does
+
+- Adds `/qq <question>`.
+- Sends the active model a read-only clone of the main session as context.
+- Shows the answer in a bottom overlay, without adding anything to the main transcript.
+- Uses a system prompt that assumes ambiguous questions are about the main session unless explicitly stated otherwise.
+- Gives the quick-question side call no tools.
+- Does **not** keep quick-question history. Each `/qq` call is independent except for the main-session context.
+- Adds **alt+q** / **Option+Q** to toggle `/qq ` at the front of the editor.
+
+## Install
+
+Install this package:
+
+```bash
+pi install npm:pi-qq
+```
+
+After installing, run `/reload` in pi or restart the session.
+
+## Usage
+
+```text
+/qq why are we changing this file?
+```
+
+Or press **alt+q** / **Option+Q**, type your quick question, and hit enter.
+
+Pressing **alt+q** / **Option+Q** toggles the prefix:
+
+- If the editor does not start with `/qq `, the prefix is prepended.
+- If the editor already starts with `/qq `, the prefix is removed.
+
+## Overlay keys
+
+| Key | Action |
+| --- | --- |
+| `↑` / `↓` | Scroll the panel when content overflows |
+| `Esc` | Close the panel; cancel the request if it is still running |
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,20 @@
+/**
+ * pi-qq — Pi extension entry point.
+ *
+ * Registers:
+ * - /qq command for one-off quick questions against the active model
+ * - alt+q shortcut that toggles a /qq prefix in the editor
+ * - lightweight conversation snapshot hooks used as read-only context
+ *
+ * Includes the command, shortcut, and snapshot hooks for quick questions.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerQqCommand, registerQqShortcut, registerInvalidationHooks, registerMessageEndSnapshot } from "./qq.js";
+
+export default function (pi: ExtensionAPI): void {
+	registerQqCommand(pi);
+	registerQqShortcut(pi);
+	registerMessageEndSnapshot(pi);
+	registerInvalidationHooks(pi);
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "pi-qq",
+  "version": "0.1.0",
+  "description": "Pi extension. Adds /qq for one-off quick questions about the main session, plus an alt+q shortcut to toggle the /qq prefix.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "quick-question",
+    "question",
+    "shortcut",
+    "keybinding",
+    "overlay"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "scripts": {
+    "typecheck": "tsc --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext --strict --skipLibCheck index.ts qq.ts qq-ui.ts"
+  },
+  "files": [
+    "index.ts",
+    "qq.ts",
+    "qq-ui.ts",
+    "prompts/",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}

package/prompts/qq-system.txt

@@ -0,0 +1,11 @@
+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.
+
+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.
+
+Cite files/functions/lines only when necessary to ground a claim; otherwise skip citations.
+
+You have no tools. Do not call tools. Plain text only.

package/qq-ui.ts

@@ -0,0 +1,181 @@
+/**
+ * Dynamic-height bottom-slot overlay for /qq.
+ *
+ * Layout:
+ *   banner (question summary)
+ *   blank
+ *   answer   — body wrapped at width-2
+ *   blank
+ *   footer   — key hints
+ *
+ * Keys:
+ *   Esc → abort in-flight call + dismiss
+ *   ↑/↓ → scroll when content exceeds terminal
+ *
+ * Does not keep quick-question history.
+ */
+
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { OverlayOptions } from "@earendil-works/pi-tui";
+import {
+	type Component,
+	Key,
+	matchesKey,
+	type TUI,
+	truncateToWidth,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+
+const QQ_OVERLAY_OPTIONS: OverlayOptions = {
+	anchor: "bottom-center",
+	width: "100%",
+	maxHeight: "85%",
+	margin: { left: 0, right: 0, bottom: 0 },
+};
+
+const QQ_MAX_HEIGHT_RATIO = 0.85;
+const SIDE_PAD = "  ";
+const ANSWER_PAD = "    ";
+const QQ_LITERAL = "/qq";
+const PENDING_GLYPH = "…";
+const FOOTER_SCROLL = "↑/↓ to scroll";
+const FOOTER_DISMISS = "Esc to dismiss";
+const FOOTER_SEP = " · ";
+
+type Mode = "pending" | "answer" | "error";
+
+export interface ShowQqOverlayParams {
+	ctx: ExtensionCommandContext;
+	question: string;
+	controller: AbortController;
+}
+
+export interface ShowQqOverlayResult {
+	overlayPromise: Promise<void>;
+	controllerReady: Promise<QqOverlayController>;
+}
+
+export class QqOverlayController implements Component {
+	private mode: Mode = "pending";
+	private answer = "";
+	private error = "";
+	private scrollOffset = 0;
+
+	constructor(
+		private readonly question: string,
+		private readonly theme: Theme,
+		private readonly tui: TUI,
+		private readonly done: (result?: undefined) => void,
+		private readonly controller: AbortController,
+	) {}
+
+	setAnswer(text: string): void {
+		this.mode = "answer";
+		this.answer = text;
+		this.tui.requestRender();
+	}
+
+	setError(message: string): void {
+		this.mode = "error";
+		this.error = message;
+		this.tui.requestRender();
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, Key.escape)) {
+			this.controller.abort();
+			this.done();
+			return;
+		}
+		if (matchesKey(data, Key.up)) {
+			this.scrollOffset = Math.max(0, this.scrollOffset - 1);
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, Key.down)) {
+			this.scrollOffset = this.scrollOffset + 1;
+			this.tui.requestRender();
+			return;
+		}
+	}
+
+	render(width: number): string[] {
+		const banner = this.renderBanner(width);
+		const answerLines = this.renderAnswer(width);
+		const footerAvail = Math.max(1, width - SIDE_PAD.length);
+		const footerParts: string[] = [];
+		if (this.mode !== "pending") footerParts.push(FOOTER_SCROLL);
+		footerParts.push(FOOTER_DISMISS);
+		const footer =
+			SIDE_PAD + truncateToWidth(this.theme.fg("dim", footerParts.join(FOOTER_SEP)), footerAvail, "…", false);
+
+		const natural: string[] = [banner, "", ...answerLines, "", footer];
+
+		const termRows = (this.tui.terminal as { rows?: number }).rows ?? 24;
+		const maxRows = Math.max(4, Math.floor(termRows * QQ_MAX_HEIGHT_RATIO));
+		if (natural.length <= maxRows) {
+			return natural;
+		}
+		const excess = natural.length - maxRows;
+		if (this.scrollOffset > excess) this.scrollOffset = excess;
+		const start = excess - this.scrollOffset;
+		return natural.slice(start, start + maxRows);
+	}
+
+	invalidate(): void {
+		// Render recomputes from state each cycle.
+	}
+
+	private renderBanner(width: number): string {
+		const prefix = `${SIDE_PAD}${QQ_LITERAL} `;
+		const prefixWidth = visibleWidth(prefix);
+		const questionWidth = Math.max(0, width - prefixWidth);
+		const truncatedQuestion = truncateToWidth(this.question, questionWidth, "…", false);
+		const raw = prefix + truncatedQuestion;
+		const padded = raw + " ".repeat(Math.max(0, width - visibleWidth(raw)));
+		return this.theme.bg("customMessageBg", this.theme.fg("customMessageText", padded));
+	}
+
+
+	private renderAnswer(width: number): string[] {
+		const bodyWidth = Math.max(1, width - ANSWER_PAD.length);
+		const indent = (lines: string[]) => lines.map((line) => ANSWER_PAD + line);
+
+		if (this.mode === "pending") {
+			return indent([this.theme.fg("warning", PENDING_GLYPH)]);
+		}
+		if (this.mode === "error") {
+			const out: string[] = [];
+			for (const line of this.error.split("\n")) {
+				const source = line.length === 0 ? " " : line;
+				out.push(...wrapTextWithAnsi(this.theme.fg("error", source), bodyWidth));
+			}
+			return indent(out);
+		}
+		const out: string[] = [];
+		for (const line of this.answer.split("\n")) {
+			const source = line.length === 0 ? " " : line;
+			out.push(...wrapTextWithAnsi(source, bodyWidth));
+		}
+		return indent(out);
+	}
+}
+
+export function showQqOverlay(params: ShowQqOverlayParams): ShowQqOverlayResult {
+	let resolveReady!: (controller: QqOverlayController) => void;
+	const controllerReady = new Promise<QqOverlayController>((resolve) => {
+		resolveReady = resolve;
+	});
+
+	const overlayPromise = params.ctx.ui.custom<void>(
+		(tui, theme, _keybindings, done) => {
+			const controller = new QqOverlayController(params.question, theme, tui, done, params.controller);
+			resolveReady(controller);
+			return controller;
+		},
+		{ overlay: true, overlayOptions: QQ_OVERLAY_OPTIONS },
+	);
+
+	return { overlayPromise, controllerReady };
+}

package/qq.ts

@@ -0,0 +1,252 @@
+/**
+ * /qq quick-question slash command.
+ *
+ * Asks the same primary model a one-off quick question using the cloned primary
+ * 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.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import {
+	type AssistantMessage,
+	completeSimple,
+	type Message,
+	type StopReason,
+	type UserMessage,
+} from "@earendil-works/pi-ai";
+import {
+	convertToLlm,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+	type ExtensionContext,
+	type SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+import { showQqOverlay } from "./qq-ui.js";
+
+export const QQ_COMMAND_NAME = "qq";
+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_NO_MODEL = "/qq requires an active model";
+const ERR_EMPTY_RESPONSE = "/qq returned no text content.";
+
+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}`;
+
+interface QqState {
+	snapshots: Map<string, { messages: Message[] }>;
+}
+
+export const QQ_SYSTEM_PROMPT = readFileSync(
+	fileURLToPath(new URL("./prompts/qq-system.txt", import.meta.url)),
+	"utf-8",
+).trimEnd();
+
+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() };
+		globalState[QQ_STATE_KEY] = state;
+	}
+	return state;
+}
+
+function getSessionFile(ctx: ExtensionContext): string {
+	return ctx.sessionManager.getSessionFile() ?? `memory:${ctx.sessionManager.getSessionId()}`;
+}
+
+function getSnapshot(ctx: ExtensionContext): { messages: Message[] } | undefined {
+	return getState().snapshots.get(getSessionFile(ctx));
+}
+
+function setSnapshot(ctx: ExtensionContext, snapshot: { messages: Message[] }): void {
+	getState().snapshots.set(getSessionFile(ctx), snapshot);
+}
+
+export function invalidateSnapshot(ctx: ExtensionContext): void {
+	getState().snapshots.delete(getSessionFile(ctx));
+}
+
+export function assistantMessageText(msg: AssistantMessage): string {
+	return msg.content
+		.filter((c): c is { type: "text"; text: string } => c.type === "text")
+		.map((c) => c.text)
+		.join("\n");
+}
+
+export interface QqExecResult {
+	ok: boolean;
+	answer?: string;
+	userMessage?: UserMessage;
+	assistantMessage?: AssistantMessage;
+	error?: string;
+	stopReason?: StopReason;
+	aborted?: boolean;
+}
+
+function readBranchMessages(ctx: ExtensionContext): Message[] {
+	const cached = getSnapshot(ctx);
+	if (cached) return cached.messages;
+
+	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);
+}
+
+function buildQqMessages(ctx: ExtensionContext, userMessage: UserMessage): Message[] {
+	return [...readBranchMessages(ctx), userMessage];
+}
+
+export async function executeQq(
+	question: string,
+	ctx: ExtensionContext,
+	controller: AbortController,
+): Promise<QqExecResult> {
+	const model = ctx.model;
+	if (!model) {
+		return { ok: false, error: MSG_NO_MODEL };
+	}
+	const modelLabel = `${model.provider}:${model.id}`;
+
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (!auth.ok) {
+		return { ok: false, error: errMisconfigured(modelLabel, auth.error) };
+	}
+	if (!auth.apiKey) {
+		return { ok: false, error: errNoApiKey(modelLabel) };
+	}
+
+	const userMessage: UserMessage = {
+		role: "user",
+		content: [{ type: "text", text: question }],
+		timestamp: Date.now(),
+	};
+
+	try {
+		const response = await completeSimple(
+			model,
+			{ systemPrompt: QQ_SYSTEM_PROMPT, messages: buildQqMessages(ctx, userMessage), tools: [] },
+			{
+				apiKey: auth.apiKey,
+				headers: auth.headers,
+				signal: controller.signal,
+			},
+		);
+
+		if (response.stopReason === "aborted") {
+			return { ok: false, aborted: true, stopReason: response.stopReason };
+		}
+		if (response.stopReason === "error") {
+			return {
+				ok: false,
+				error: errCallFailed(response.errorMessage),
+				stopReason: response.stopReason,
+			};
+		}
+
+		const answerText = assistantMessageText(response).trim();
+		if (!answerText) {
+			return { ok: false, error: ERR_EMPTY_RESPONSE, stopReason: response.stopReason };
+		}
+
+		return {
+			ok: true,
+			answer: answerText,
+			userMessage,
+			assistantMessage: response,
+			stopReason: response.stopReason,
+		};
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		if (controller.signal.aborted) {
+			return { ok: false, aborted: true };
+		}
+		return { ok: false, error: errCallThrew(message) };
+	}
+}
+
+export function registerMessageEndSnapshot(pi: ExtensionAPI): void {
+	pi.on("message_end", async (event, ctx) => {
+		const msg = event.message;
+		if (msg.role !== "assistant") return;
+		if ((msg as AssistantMessage).stopReason === "toolUse") return;
+		const branch = ctx.sessionManager.getBranch() as SessionEntry[];
+		const agentMessages = branch
+			.filter((entry): entry is SessionEntry & { type: "message" } => entry.type === "message")
+			.map((entry) => entry.message);
+		setSnapshot(ctx, { messages: convertToLlm(agentMessages) });
+	});
+}
+
+export function registerInvalidationHooks(pi: ExtensionAPI): void {
+	pi.on("session_compact", async (_event, ctx) => invalidateSnapshot(ctx));
+	pi.on("session_tree", async (_event, ctx) => invalidateSnapshot(ctx));
+}
+
+export function registerQqShortcut(pi: ExtensionAPI): void {
+	pi.registerShortcut("alt+q", {
+		description: "Toggle /qq quick-question prefix",
+		handler: async (ctx) => {
+			if (!ctx.hasUI) return;
+			const current = ctx.ui.getEditorText() ?? "";
+			if (current.startsWith(QQ_PREFIX)) {
+				ctx.ui.setEditorText(current.slice(QQ_PREFIX.length));
+				return;
+			}
+			ctx.ui.setEditorText(QQ_PREFIX + current);
+		},
+	});
+}
+
+export function registerQqCommand(pi: ExtensionAPI): void {
+	pi.registerCommand(QQ_COMMAND_NAME, {
+		description: "Ask a quick question without polluting the main conversation",
+		handler: (args: string, ctx: ExtensionCommandContext) => handleQqCommand(args, ctx),
+	});
+}
+
+async function handleQqCommand(args: string, ctx: ExtensionCommandContext): Promise<void> {
+	if (!ctx.hasUI) {
+		ctx.ui.notify(MSG_REQUIRES_INTERACTIVE, "error");
+		return;
+	}
+	const question = args.trim();
+	if (!question) {
+		ctx.ui.notify(MSG_USAGE, "warning");
+		return;
+	}
+	if (!ctx.model) {
+		ctx.ui.notify(MSG_NO_MODEL, "error");
+		return;
+	}
+
+	const controller = new AbortController();
+	const { overlayPromise, controllerReady } = showQqOverlay({
+		ctx,
+		question,
+		controller,
+	});
+
+	const overlayCtl = await controllerReady;
+	const result = await executeQq(question, ctx, controller);
+
+	if (result.ok && result.answer) {
+		overlayCtl.setAnswer(result.answer);
+	} else if (result.aborted) {
+		// User Esc'd — overlay already dismissed via done(); no further action.
+	} else if (result.error) {
+		overlayCtl.setError(result.error);
+	}
+
+	await overlayPromise;
+}