pi-agent-extensions 0.3.3 → 0.3.5

package/README.md

@@ -32,6 +32,7 @@ Original repository: https://github.com/mitsuhiko/agent-stuff
 | **control** | RPC | Inter-session communication & control | ⚙️ Beta |
 | **answer** | Tool | Structured Q&A for complex queries | ⚙️ Beta |
 | **cwd_history** | Tracker | Tracks directory changes in context | ✅ Stable |
+| **btw** | Command | Quick side questions without history | ✅ Stable |
 | **nvidia-nim** | Command | Nvidia NIM auth & config | ✅ Stable |
 
 ## Install
@@ -98,6 +99,10 @@ pi
 
 You'll see a loader while context is extracted, then an editor to review the handoff prompt.
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
 ## Update
 
 ```bash
@@ -267,6 +272,36 @@ A personality engine for Pi that makes waiting fun.
 
 See [extensions/whimsical/README.md](extensions/whimsical/README.md) for details.
 
+### BTW
+
+Ask quick "by the way" side questions without polluting your conversation history. Inspired by Claude Code's `/btw` command.
+
+**Usage:**
+
+```bash
+/btw what's the syntax for useEffect cleanup?
+/btw which files did we modify just now?
+/btw why did you choose Zustand over Redux?
+```
+
+**Features:**
+- ✅ Full conversation context visibility
+- ✅ No tool access (lightweight, read-only)
+- ✅ Ephemeral overlay — nothing enters session history
+- ✅ Zero context cost — no tokens wasted
+- ✅ Scrollable answer (↑↓/j/k, PgUp/PgDn)
+- ✅ Prefers cheap/fast models (Codex mini → Haiku → current)
+- ✅ Non-UI fallback (prints to stdout)
+
+**When to use `/btw` vs normal prompts:**
+
+| Use `/btw` | Use normal prompts |
+|---|---|
+| Quick syntax checks | Requests needing tool access |
+| Confirming earlier decisions | Changes you want tracked |
+| Recalling context details | Complex multi-step tasks |
+| "One and done" lookups | Follow-up conversations |
+
 ### Productivity Tools
 
 **Files (`/files`)**

package/docs/mitsuhiko-integration-analysis.md

@@ -458,8 +458,8 @@ pi.on("tool_result", (event, ctx) => {
 ```typescript
 // Store extension state in session
 pi.appendEntry<StateType>(CUSTOM_TYPE, stateData);
-// Restore on session switch
-pi.on("session_switch", (event, ctx) => {
+// Restore on session start (covers startup, switch, fork, etc.)
+pi.on("session_start", (event, ctx) => {
   applyState(ctx);
 });
 ```

package/extensions/btw/btw.ts

@@ -0,0 +1,70 @@
+/**
+ * Testable logic for the /btw extension.
+ *
+ * Separated from index.ts so pure functions can be unit-tested
+ * without importing pi-coding-agent or pi-tui.
+ */
+
+/**
+ * System prompt for BTW side questions.
+ * Instructs the LLM to answer concisely from conversation context only.
+ */
+export const BTW_SYSTEM_PROMPT = `You are answering a quick "by the way" side question during a coding session.
+
+Rules:
+- Answer concisely and directly based on the conversation context provided.
+- You have NO tool access — you cannot read files, run commands, or make changes.
+- Only answer based on information already present in the conversation.
+- Keep your response brief and to the point.
+- Use markdown formatting where helpful (code blocks, lists, bold).
+- If the conversation context doesn't contain enough information to answer, say so honestly.`;
+
+/**
+ * Build the user message for the BTW LLM call.
+ * Includes the serialized conversation as context and the user's question.
+ */
+export function buildBtwUserMessage(
+  conversationText: string,
+  question: string,
+): string {
+  return `<conversation_context>
+${conversationText}
+</conversation_context>
+
+<side_question>
+${question}
+</side_question>
+
+Answer the side question above based on the conversation context. Be concise.`;
+}
+
+/**
+ * Validate the /btw command arguments.
+ * Returns the question text or an error message.
+ */
+export function validateBtwArgs(args: string | undefined): {
+  valid: boolean;
+  question?: string;
+  error?: string;
+} {
+  const question = args?.trim();
+  if (!question || question.length === 0) {
+    return {
+      valid: false,
+      error: "Usage: /btw <question> — Ask a quick side question without polluting conversation history.",
+    };
+  }
+  return { valid: true, question };
+}
+
+/**
+ * Extract text content from an LLM response content array.
+ */
+export function extractResponseText(
+  content: Array<{ type: string; text?: string }>,
+): string {
+  return content
+    .filter((c): c is { type: "text"; text: string } => c.type === "text" && typeof c.text === "string")
+    .map((c) => c.text)
+    .join("\n");
+}

package/extensions/btw/index.ts

@@ -0,0 +1,400 @@
+/**
+ * BTW Extension
+ *
+ * Provides a `/btw` command for quick side questions that don't pollute
+ * the conversation history. The answer appears in a temporary overlay
+ * and is fully ephemeral — nothing is persisted to the session.
+ *
+ * Usage:
+ *   /btw what's the syntax for useEffect cleanup?
+ *   /btw which files did we modify?
+ *   /btw why did you choose that approach?
+ *
+ * Key behaviors:
+ * - Full visibility into current conversation context
+ * - No tool access (lightweight, read-only)
+ * - Answer displayed in dismissable overlay
+ * - Zero context cost — no tokens wasted on history
+ */
+
+import { complete, type Model, type Api, type UserMessage } from "@mariozechner/pi-ai";
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
+import {
+  BorderedLoader,
+  convertToLlm,
+  serializeConversation,
+} from "@mariozechner/pi-coding-agent";
+import {
+  type Component,
+  Container,
+  Key,
+  matchesKey,
+  Text,
+  wrapTextWithAnsi,
+  visibleWidth,
+  type TUI,
+} from "@mariozechner/pi-tui";
+
+import { getRequestAuth, hasRequestAuth } from "../shared/auth.js";
+import {
+  BTW_SYSTEM_PROMPT,
+  buildBtwUserMessage,
+  validateBtwArgs,
+  extractResponseText,
+} from "./btw.js";
+
+const HAIKU_MODEL_ID = "claude-haiku-4-5";
+const CODEX_MODEL_ID = "gpt-5.1-codex-mini";
+
+/**
+ * Select a cheap/fast model for BTW side questions.
+ * Prefers Codex mini → Haiku → current model.
+ */
+async function selectBtwModel(
+  currentModel: Model<Api>,
+  modelRegistry: {
+    find: (provider: string, modelId: string) => Model<Api> | undefined;
+    getApiKeyAndHeaders: (
+      model: Model<Api>,
+    ) => Promise<
+      | { ok: true; apiKey?: string; headers?: Record<string, string> }
+      | { ok: false; error: string }
+    >;
+  },
+): Promise<Model<Api>> {
+  // Try Codex mini first (cheapest)
+  const codexModel = modelRegistry.find("openai-codex", CODEX_MODEL_ID);
+  if (codexModel && (await hasRequestAuth(modelRegistry, codexModel))) {
+    return codexModel;
+  }
+
+  // Try Haiku (fast & cheap)
+  const haikuModel = modelRegistry.find("anthropic", HAIKU_MODEL_ID);
+  if (haikuModel && (await hasRequestAuth(modelRegistry, haikuModel))) {
+    return haikuModel;
+  }
+
+  // Fallback to current model
+  return currentModel;
+}
+
+/**
+ * Overlay component that displays the BTW answer.
+ * Supports scrolling for long answers.
+ */
+class BtwOverlay implements Component {
+  private tui: TUI;
+  private theme: any;
+  private question: string;
+  private answer: string;
+  private onDone: () => void;
+  private scrollOffset = 0;
+  private cachedWidth?: number;
+  private cachedLines?: string[];
+
+  constructor(
+    tui: TUI,
+    theme: any,
+    question: string,
+    answer: string,
+    onDone: () => void,
+  ) {
+    this.tui = tui;
+    this.theme = theme;
+    this.question = question;
+    this.answer = answer;
+    this.onDone = onDone;
+  }
+
+  handleInput(data: string): void {
+    // Dismiss overlay
+    if (
+      matchesKey(data, Key.escape) ||
+      matchesKey(data, Key.ctrl("c")) ||
+      data === " " ||
+      data.toLowerCase() === "q"
+    ) {
+      this.onDone();
+      return;
+    }
+
+    // Scroll
+    if (matchesKey(data, Key.up) || data === "k") {
+      if (this.scrollOffset > 0) {
+        this.scrollOffset--;
+        this.invalidate();
+        this.tui.requestRender();
+      }
+      return;
+    }
+    if (matchesKey(data, Key.down) || data === "j") {
+      this.scrollOffset++;
+      this.invalidate();
+      this.tui.requestRender();
+      return;
+    }
+
+    // Page up/down
+    if (matchesKey(data, Key.pageUp)) {
+      this.scrollOffset = Math.max(0, this.scrollOffset - 10);
+      this.invalidate();
+      this.tui.requestRender();
+      return;
+    }
+    if (matchesKey(data, Key.pageDown)) {
+      this.scrollOffset += 10;
+      this.invalidate();
+      this.tui.requestRender();
+      return;
+    }
+  }
+
+  invalidate(): void {
+    this.cachedWidth = undefined;
+    this.cachedLines = undefined;
+  }
+
+  render(width: number): string[] {
+    if (this.cachedLines && this.cachedWidth === width) {
+      return this.cachedLines;
+    }
+
+    const theme = this.theme;
+    const boxWidth = Math.min(width - 2, 120);
+    const contentWidth = boxWidth - 6; // padding on each side
+
+    const horizontalLine = (count: number) => "─".repeat(count);
+
+    const boxLine = (content: string, leftPad: number = 2): string => {
+      const paddedContent = " ".repeat(leftPad) + content;
+      const contentLen = visibleWidth(paddedContent);
+      const rightPad = Math.max(0, boxWidth - contentLen - 2);
+      return theme.fg("border", "│") + paddedContent + " ".repeat(rightPad) + theme.fg("border", "│");
+    };
+
+    const emptyBoxLine = (): string => {
+      return theme.fg("border", "│") + " ".repeat(boxWidth - 2) + theme.fg("border", "│");
+    };
+
+    const padToWidth = (line: string): string => {
+      const len = visibleWidth(line);
+      return line + " ".repeat(Math.max(0, width - len));
+    };
+
+    const lines: string[] = [];
+
+    // Top border
+    lines.push(padToWidth(theme.fg("accent", "╭" + horizontalLine(boxWidth - 2) + "╮")));
+
+    // Title
+    const title = theme.fg("accent", theme.bold("btw"));
+    lines.push(padToWidth(boxLine(title)));
+
+    // Separator
+    lines.push(padToWidth(theme.fg("accent", "├" + horizontalLine(boxWidth - 2) + "┤")));
+
+    // Question
+    const questionLabel = theme.fg("muted", "Q: ") + theme.fg("text", this.question);
+    const wrappedQuestion = wrapTextWithAnsi(questionLabel, contentWidth);
+    for (const line of wrappedQuestion) {
+      lines.push(padToWidth(boxLine(line)));
+    }
+
+    lines.push(padToWidth(emptyBoxLine()));
+
+    // Separator between question and answer
+    lines.push(padToWidth(theme.fg("border", "├" + horizontalLine(boxWidth - 2) + "┤")));
+    lines.push(padToWidth(emptyBoxLine()));
+
+    // Answer — wrap and apply scroll
+    const answerLines: string[] = [];
+    for (const paragraph of this.answer.split("\n")) {
+      if (paragraph.trim() === "") {
+        answerLines.push("");
+      } else {
+        const wrapped = wrapTextWithAnsi(paragraph, contentWidth);
+        answerLines.push(...wrapped);
+      }
+    }
+
+    // Clamp scroll offset
+    const termHeight = this.tui.height ?? 24;
+    const headerLines = lines.length;
+    const footerLines = 3; // separator + hint + bottom border
+    const maxVisibleAnswerLines = Math.max(1, termHeight - headerLines - footerLines - 2);
+
+    if (this.scrollOffset > Math.max(0, answerLines.length - maxVisibleAnswerLines)) {
+      this.scrollOffset = Math.max(0, answerLines.length - maxVisibleAnswerLines);
+    }
+
+    const visibleAnswerLines = answerLines.slice(
+      this.scrollOffset,
+      this.scrollOffset + maxVisibleAnswerLines,
+    );
+
+    for (const line of visibleAnswerLines) {
+      lines.push(padToWidth(boxLine(line)));
+    }
+
+    // Scroll indicator
+    if (answerLines.length > maxVisibleAnswerLines) {
+      const scrollInfo = theme.fg("dim", `[${this.scrollOffset + 1}-${Math.min(this.scrollOffset + maxVisibleAnswerLines, answerLines.length)}/${answerLines.length}]`);
+      lines.push(padToWidth(boxLine(scrollInfo)));
+    }
+
+    lines.push(padToWidth(emptyBoxLine()));
+
+    // Footer
+    lines.push(padToWidth(theme.fg("accent", "├" + horizontalLine(boxWidth - 2) + "┤")));
+    const hint = theme.fg("dim", "Esc/Space/q to dismiss · ↑↓/j/k scroll · PgUp/PgDn");
+    lines.push(padToWidth(boxLine(hint)));
+    lines.push(padToWidth(theme.fg("accent", "╰" + horizontalLine(boxWidth - 2) + "╯")));
+
+    this.cachedWidth = width;
+    this.cachedLines = lines;
+    return lines;
+  }
+}
+
+/**
+ * Main /btw command handler
+ */
+async function runBtwCommand(
+  args: string | undefined,
+  ctx: ExtensionCommandContext,
+): Promise<void> {
+  // Validate args
+  const validation = validateBtwArgs(args);
+  if (!validation.valid) {
+    if (ctx.hasUI) {
+      ctx.ui.notify(validation.error!, "error");
+    } else {
+      console.error(validation.error);
+    }
+    return;
+  }
+  const question = validation.question!;
+
+  // Check for model
+  if (!ctx.model) {
+    const errorMsg = "No model selected. Use /model to select a model first.";
+    if (ctx.hasUI) {
+      ctx.ui.notify(errorMsg, "error");
+    } else {
+      console.error(errorMsg);
+    }
+    return;
+  }
+
+  // Build conversation context
+  const sessionContext = ctx.sessionManager.buildSessionContext();
+  const messages = sessionContext.messages;
+
+  let conversationText = "";
+  if (messages.length > 0) {
+    const llmMessages = convertToLlm(messages);
+    conversationText = serializeConversation(llmMessages);
+  }
+
+  // Select model (prefer cheap models)
+  const btwModel = await selectBtwModel(ctx.model, ctx.modelRegistry);
+
+  // Build LLM messages
+  const userMessage: UserMessage = {
+    role: "user",
+    content: [{ type: "text", text: buildBtwUserMessage(conversationText, question) }],
+    timestamp: Date.now(),
+  };
+
+  if (!ctx.hasUI) {
+    // Non-interactive mode: print answer to stdout
+    const requestAuth = await getRequestAuth(ctx.modelRegistry, btwModel);
+    const response = await complete(
+      btwModel,
+      { systemPrompt: BTW_SYSTEM_PROMPT, messages: [userMessage] },
+      { ...requestAuth },
+    );
+
+    if (response.stopReason === "error") {
+      console.error(response.errorMessage ?? "LLM error");
+      return;
+    }
+
+    const answerText = extractResponseText(response.content);
+    console.log(`\n> btw: ${question}\n`);
+    console.log(answerText);
+    return;
+  }
+
+  // Interactive mode: show loader, then overlay
+
+  // Step 1: Get the answer with a loading spinner
+  const answerResult = await ctx.ui.custom<string | null>((tui, theme, _kb, done) => {
+    const loader = new BorderedLoader(
+      tui,
+      theme,
+      `Thinking (${btwModel.id})...`,
+    );
+    loader.onAbort = () => done(null);
+
+    const doQuery = async () => {
+      const requestAuth = await getRequestAuth(ctx.modelRegistry, btwModel);
+      const response = await complete(
+        btwModel,
+        { systemPrompt: BTW_SYSTEM_PROMPT, messages: [userMessage] },
+        { ...requestAuth, signal: loader.signal },
+      );
+
+      if (response.stopReason === "aborted") {
+        return null;
+      }
+
+      if (response.stopReason === "error") {
+        return null;
+      }
+
+      return extractResponseText(response.content);
+    };
+
+    doQuery()
+      .then(done)
+      .catch((err) => {
+        console.error("BTW query failed:", err);
+        done(null);
+      });
+
+    return loader;
+  });
+
+  if (answerResult === null) {
+    ctx.ui.notify("Cancelled", "info");
+    return;
+  }
+
+  if (answerResult.trim() === "") {
+    ctx.ui.notify("No answer received", "warning");
+    return;
+  }
+
+  // Step 2: Show the answer in an overlay
+  await ctx.ui.custom<void>((tui, theme, _kb, done) => {
+    return new BtwOverlay(tui, theme, question, answerResult, done);
+  });
+
+  // Nothing persisted — fully ephemeral
+}
+
+/**
+ * Main extension entry point
+ */
+export default function btwExtension(pi: ExtensionAPI) {
+  pi.registerCommand("btw", {
+    description: "Ask a quick side question without polluting conversation history",
+    handler: async (args, ctx) => {
+      await runBtwCommand(args, ctx);
+    },
+  });
+}

package/extensions/files/index.ts

@@ -25,7 +25,7 @@ import { DynamicBorder } from "@mariozechner/pi-coding-agent";
 import {
 	Container,
 	fuzzyFilter,
-	getEditorKeybindings,
+	getKeybindings,
 	Input,
 	matchesKey,
 	type SelectItem,
@@ -938,16 +938,16 @@ const showFileSelector = async (
 					}
 				}
 
-				const kb = getEditorKeybindings();
+				const kb = getKeybindings();
 				if (
-					kb.matches(data, "selectUp") ||
-					kb.matches(data, "selectDown") ||
-					kb.matches(data, "selectConfirm") ||
-					kb.matches(data, "selectCancel")
+					kb.matches(data, "tui.select.up") ||
+					kb.matches(data, "tui.select.down") ||
+					kb.matches(data, "tui.select.confirm") ||
+					kb.matches(data, "tui.select.cancel")
 				) {
 					if (selectList) {
 						selectList.handleInput(data);
-					} else if (kb.matches(data, "selectCancel")) {
+					} else if (kb.matches(data, "tui.select.cancel")) {
 						done(null);
 					}
 					tui.requestRender();

package/extensions/sessions/index.ts

@@ -67,7 +67,7 @@ async function listSessions(ctx: ExtensionCommandContext): Promise<SessionInfoLi
     container.addChild(new DynamicBorder(borderColor));
     container.addChild(loader);
     container.addChild(new Spacer(1));
-    container.addChild(new Text(keyHint("selectCancel", "cancel"), 1, 0));
+    container.addChild(new Text(keyHint("tui.select.cancel", "cancel"), 1, 0));
     container.addChild(new Spacer(1));
     container.addChild(new DynamicBorder(borderColor));
 

package/extensions/todos/index.ts

@@ -48,7 +48,7 @@ import {
 	Text,
 	TUI,
 	fuzzyMatch,
-	getEditorKeybindings,
+	getKeybindings,
 	matchesKey,
 	truncateToWidth,
 	visibleWidth,
@@ -397,25 +397,25 @@ class TodoSelectorComponent extends Container implements Focusable {
 	}
 
 	handleInput(keyData: string): void {
-		const kb = getEditorKeybindings();
-		if (kb.matches(keyData, "selectUp")) {
+		const kb = getKeybindings();
+		if (kb.matches(keyData, "tui.select.up")) {
 			if (this.filteredTodos.length === 0) return;
 			this.selectedIndex = this.selectedIndex === 0 ? this.filteredTodos.length - 1 : this.selectedIndex - 1;
 			this.updateList();
 			return;
 		}
-		if (kb.matches(keyData, "selectDown")) {
+		if (kb.matches(keyData, "tui.select.down")) {
 			if (this.filteredTodos.length === 0) return;
 			this.selectedIndex = this.selectedIndex === this.filteredTodos.length - 1 ? 0 : this.selectedIndex + 1;
 			this.updateList();
 			return;
 		}
-		if (kb.matches(keyData, "selectConfirm")) {
+		if (kb.matches(keyData, "tui.select.confirm")) {
 			const selected = this.filteredTodos[this.selectedIndex];
 			if (selected) this.onSelectCallback(selected);
 			return;
 		}
-		if (kb.matches(keyData, "selectCancel")) {
+		if (kb.matches(keyData, "tui.select.cancel")) {
 			this.onCancelCallback();
 			return;
 		}
@@ -573,28 +573,28 @@ class TodoDetailOverlayComponent {
 	}
 
 	handleInput(keyData: string): void {
-		const kb = getEditorKeybindings();
-		if (kb.matches(keyData, "selectCancel")) {
+		const kb = getKeybindings();
+		if (kb.matches(keyData, "tui.select.cancel")) {
 			this.onAction("back");
 			return;
 		}
-		if (kb.matches(keyData, "selectConfirm")) {
+		if (kb.matches(keyData, "tui.select.confirm")) {
 			this.onAction("work");
 			return;
 		}
-		if (kb.matches(keyData, "selectUp")) {
+		if (kb.matches(keyData, "tui.select.up")) {
 			this.scrollBy(-1);
 			return;
 		}
-		if (kb.matches(keyData, "selectDown")) {
+		if (kb.matches(keyData, "tui.select.down")) {
 			this.scrollBy(1);
 			return;
 		}
-		if (kb.matches(keyData, "selectPageUp")) {
+		if (kb.matches(keyData, "tui.select.pageUp")) {
 			this.scrollBy(-this.viewHeight || -1);
 			return;
 		}
-		if (kb.matches(keyData, "selectPageDown")) {
+		if (kb.matches(keyData, "tui.select.pageDown")) {
 			this.scrollBy(this.viewHeight || 1);
 			return;
 		}
@@ -1256,7 +1256,7 @@ function renderTodoDetail(theme: Theme, todo: TodoRecord, expanded: boolean): st
 }
 
 function appendExpandHint(theme: Theme, text: string): string {
-	return `${text}\n${theme.fg("dim", `(${keyHint("expandTools", "to expand")})`)}`;
+	return `${text}\n${theme.fg("dim", `(${keyHint("app.tools.expand", "to expand")})`)}`;
 }
 
 async function ensureTodoExists(filePath: string, id: string): Promise<TodoRecord | null> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-extensions",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Collection of extensions for pi coding agent",
   "type": "module",
   "repository": {
@@ -46,7 +46,8 @@
       "./extensions/session-breakdown/index.ts",
       "./extensions/todos/index.ts",
       "./extensions/whimsical/index.ts",
-      "./extensions/nvidia-nim/index.ts"
+      "./extensions/nvidia-nim/index.ts",
+      "./extensions/btw/index.ts"
     ],
     "themes": [
       "./themes/nightowl.json",