pi-bro 0.1.1 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ adding extra messages to your conversation context.
 `pi-bro` is a small extension for
 [Earendil Pi](https://github.com/earendil-works/pi). It uses the
 [Google Antigravity CLI](https://antigravity.google/docs/cli-install) (`agy`)
-and a Gemini model to create plain-language explanations.
+and a Gemini model to stream plain-language explanations.
 
 ## Bro in action
 
@@ -265,7 +265,7 @@ cached files, not your source code or dependencies.
 
 - Earendil Pi `>=0.78.1 <1` (tested on `0.84.2`)
 - Node.js `>=22.19.0`
-- `agy` installed, authenticated, and on your `PATH` (tested on `1.1.13`)
+- `agy >=1.1.8` installed, authenticated, and on your `PATH` (tested on `1.1.13`)
 - Pi's interactive terminal UI
 
 Run `agy` once in your terminal to complete sign-in before using Bro.
@@ -346,9 +346,9 @@ PI_BRO_MODEL=gemini-3.7-flash-low pi
 - **Memory cache**: The latest explanation is stored only in process memory for
   `/bro open`. It clears when you switch Pi sessions, reload extensions, or quit
   Pi.
-- **File safety**: Bro does not modify project files. It runs Agy in plan and
-  sandbox modes inside a temporary empty folder. This reduces project access,
-  but it is not a security boundary.
+- **File safety**: Bro does not modify project files. It runs Agy in sandbox
+  mode inside a temporary empty folder. This reduces project access, but it is
+  not a security boundary.
 - **Provider data**: Agy and your model provider may retain logs and request data
   according to their own settings and privacy policies.
 - **Clipboard**: Pressing **C** copies the text to your system clipboard, where
@@ -359,7 +359,11 @@ PI_BRO_MODEL=gemini-3.7-flash-low pi
 - Supports only Agy/Gemini in v0.1.
 - Keeps only the latest explanation in memory.
 - Does not store history or export directly to files.
-- Mouse scrolling is disabled; use the arrow keys to scroll and **C** to copy.
+- Mouse-wheel and trackpad scrolling work in Pi's fullscreen mode
+  (`pi --tui-mode fullscreen`). In regular mode, use the arrow keys so Bro does
+  not interfere with your terminal's native text selection.
+- In fullscreen mode, mouse text selection may visually extend outside the Bro
+  window. Press **C** to copy the full explanation instead.
 
 ## Development
 

package/bro.ts

@@ -1,6 +1,8 @@
+import { spawn } from "node:child_process";
 import { mkdtemp, readFile, rm } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
+import { createInterface } from "node:readline";
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { copyToClipboard, getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import { Markdown, matchesKey, truncateToWidth, visibleWidth, type Focusable } from "@earendil-works/pi-tui";
@@ -20,9 +22,22 @@ Quoted response as a JSON string:
 
 type Theme = ExtensionCommandContext["ui"]["theme"];
 type TuiLike = { requestRender(): void };
-type ModalKind = "loading" | "result" | "help" | "empty" | "error";
+type ModalKind = "loading" | "streaming" | "result" | "help" | "empty" | "error";
 type AssistantSource = { id: string; text: string };
 type BroResult = { source: AssistantSource; text: string };
+type AgyEvent = {
+	event?: string;
+	step_update?: { step_type?: string; text_delta?: unknown };
+	result?: { status?: string; response?: unknown };
+};
+
+export function wheelDelta(data: string): number {
+	const match = /^\x1b\[<(\d+);\d+;\d+[Mm]$/.exec(data);
+	if (!match) return 0;
+	const button = Number.parseInt(match[1], 10);
+	if ((button & 64) === 0) return 0;
+	return (button & 3) === 0 ? -3 : (button & 3) === 1 ? 3 : 0;
+}
 
 const COMMANDS = [
 	{ value: "simplify", label: "simplify", description: "Simplify the latest assistant response" },
@@ -62,20 +77,49 @@ async function promptFor(response: string): Promise<string> {
 	return parts.join(JSON.stringify(response));
 }
 
-async function simplify(pi: ExtensionAPI, response: string, signal: AbortSignal): Promise<string> {
+function parseAgyLine(line: string): { delta?: string; result?: string } {
+	let event: AgyEvent;
+	try {
+		event = JSON.parse(line) as AgyEvent;
+	} catch {
+		throw new Error("Agy returned invalid streaming data.");
+	}
+
+	if (
+		event.event === "step_update" &&
+		event.step_update?.step_type === "agent_response" &&
+		typeof event.step_update.text_delta === "string"
+	) {
+		return { delta: event.step_update.text_delta };
+	}
+
+	if (event.event === "result") {
+		if (event.result?.status !== "SUCCESS" || typeof event.result.response !== "string") {
+			throw new Error("Agy did not complete the explanation successfully.");
+		}
+		return { result: event.result.response };
+	}
+
+	return {};
+}
+
+async function simplify(
+	response: string,
+	signal: AbortSignal,
+	onProgress?: (text: string) => void,
+): Promise<string> {
 	const prompt = await promptFor(response);
 	const runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+	let updateTimer: ReturnType<typeof setTimeout> | undefined;
 
 	try {
-		const result = await pi.exec(
+		const child = spawn(
 			"agy",
 			[
-				"--mode",
-				"plan",
 				"--sandbox",
 				"--disable-slash-commands",
 				"--output-format",
-				"text",
+				"stream-json",
 				"--model",
 				MODEL,
 				"--print-timeout",
@@ -83,17 +127,74 @@ async function simplify(pi: ExtensionAPI, response: string, signal: AbortSignal)
 				"--print",
 				prompt,
 			],
-			{ cwd: runDirectory, signal, timeout: 125_000 },
+			{
+				cwd: runDirectory,
+				signal,
+				timeout: 125_000,
+				stdio: ["ignore", "pipe", "pipe"],
+				windowsHide: true,
+			},
 		);
 
-		if (result.killed) throw new Error(signal.aborted ? "Canceled." : "Simplification timed out.");
-		const text = result.stdout.trim();
-		if (result.code !== 0 || !text) {
-			throw new Error(result.stderr.trim() || "No explanation was generated.");
+		let processError: Error | undefined;
+		let stderr = "";
+		let partial = "";
+		let final = "";
+		let parseError: Error | undefined;
+
+		child.stderr.setEncoding("utf8");
+		child.stderr.on("data", (chunk: string) => {
+			stderr += chunk;
+		});
+		child.once("error", (error) => {
+			processError = error;
+		});
+
+		const closed = new Promise<{ code: number | null; exitSignal: NodeJS.Signals | null }>((resolve) => {
+			child.once("close", (code, exitSignal) => resolve({ code, exitSignal }));
+		});
+
+		const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+		try {
+			for await (const line of lines) {
+				if (!line.trim()) continue;
+				try {
+					const event = parseAgyLine(line);
+					if (event.delta) {
+						partial += event.delta;
+						if (onProgress && !updateTimer) {
+							updateTimer = setTimeout(() => {
+								updateTimer = undefined;
+								if (!signal.aborted) onProgress(partial);
+							}, 75);
+						}
+					}
+					if (event.result !== undefined) final = event.result;
+				} catch (error) {
+					parseError = error instanceof Error ? error : new Error(String(error));
+					child.kill();
+					break;
+				}
+			}
+		} finally {
+			lines.close();
+		}
+
+		const { code, exitSignal } = await closed;
+		if (signal.aborted) throw new Error("Canceled.");
+		if (parseError) throw parseError;
+		if (processError) throw processError;
+		if (exitSignal || code === null) throw new Error("Simplification timed out.");
+		if (code !== 0) throw new Error(stderr.trim() || `Agy exited with code ${code}.`);
+
+		const text = final.trim();
+		if (!text) {
+			throw new Error(stderr.trim() || "Agy returned no final explanation.");
 		}
 
 		return text;
 	} finally {
+		if (updateTimer) clearTimeout(updateTimer);
 		await rm(runDirectory, { recursive: true, force: true });
 	}
 }
@@ -111,14 +212,17 @@ Bro turns the latest completed assistant response into a clear, plain-language e
 
 ## Controls
 
-- **↑ / ↓** — scroll
+- **Mouse wheel / trackpad** — scroll in Pi's fullscreen mode
+- **↑ / ↓** — scroll in any mode
 - **C** — copy the full explanation
 - **R** — simplify the same response again
 - **Esc** — close the window, or cancel while Bro is working
 
+Mouse text selection may extend outside the Bro window. Press **C** to copy the complete explanation instead.
+
 ## Privacy and file safety
 
-Bro does not modify your project files. It runs the simplifier in plan and sandbox modes inside a temporary empty folder. This reduces project access, but it is not a security boundary.
+Bro does not modify your project files. It runs the simplifier in sandbox mode inside a temporary empty folder. This reduces project access, but it is not a security boundary.
 
 Bro does not add explanations to Pi's conversation history, session files, or main-agent context. The latest explanation is kept in process memory only so \`/bro open\` can reopen it. It is cleared when you change sessions, reload extensions, or exit Pi.
 
@@ -163,6 +267,10 @@ class BroModal implements Focusable {
 		this.setContent("loading", `**${LOADING_TEXT}**`, "", false, false);
 	}
 
+	setStreaming(text: string): void {
+		this.setContent("streaming", text, "", false, false);
+	}
+
 	setResult(text: string, retryable: boolean, notice = ""): void {
 		this.setContent("result", text, text, true, retryable, notice);
 	}
@@ -188,7 +296,7 @@ class BroModal implements Focusable {
 		this.copyable = copyable;
 		this.retryable = retryable;
 		this.notice = notice;
-		this.offset = 0;
+		if (kind !== "streaming") this.offset = 0;
 		this.markdown.setText(text);
 		this.tui.requestRender();
 	}
@@ -211,6 +319,7 @@ class BroModal implements Focusable {
 
 	private controls(): string {
 		if (this.kind === "loading") return "Esc cancel";
+		if (this.kind === "streaming") return "Simplifying… · ↑/↓ scroll · Esc cancel";
 		if (this.kind === "result") return "↑/↓ scroll · C copy · R simplify again · Esc close";
 		if (this.kind === "help") return "↑/↓ scroll · C copy · Esc close";
 		if (this.kind === "error") return "R try again · Esc close";
@@ -257,8 +366,8 @@ class BroModal implements Focusable {
 			return;
 		}
 
-		if (matchesKey(data, "up") || matchesKey(data, "down")) {
-			const delta = matchesKey(data, "up") ? -1 : 1;
+		const delta = wheelDelta(data) || (matchesKey(data, "up") ? -1 : matchesKey(data, "down") ? 1 : 0);
+		if (delta) {
 			this.offset = Math.max(0, Math.min(this.offset + delta, this.maxOffset));
 			this.notice = "";
 			this.tui.requestRender();
@@ -303,7 +412,11 @@ interface BroModalOptions {
 	kind?: "help" | "empty";
 	copyable?: boolean;
 	result?: BroResult;
-	run?: (signal: AbortSignal, source?: AssistantSource) => Promise<BroResult>;
+	run?: (
+		signal: AbortSignal,
+		source?: AssistantSource,
+		onProgress?: (text: string) => void,
+	) => Promise<BroResult>;
 	onResult?: (result: BroResult) => void;
 }
 
@@ -349,7 +462,10 @@ async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptio
 				modal.setLoading();
 
 				void options
-					.run(nextController.signal, source)
+					.run(nextController.signal, source, (text) => {
+						if (closed || nextController.signal.aborted || controller !== nextController) return;
+						modal.setStreaming(text);
+					})
 					.then((result) => {
 						if (closed || nextController.signal.aborted) return;
 						current = result;
@@ -415,14 +531,18 @@ export default function bro(pi: ExtensionAPI) {
 				return;
 			}
 
-			const run = async (signal: AbortSignal, source?: AssistantSource): Promise<BroResult> => {
+			const run = async (
+				signal: AbortSignal,
+				source?: AssistantSource,
+				onProgress?: (text: string) => void,
+			): Promise<BroResult> => {
 				let target = source;
 				if (!target) {
 					await ctx.waitForIdle();
 					target = latestAssistant(ctx);
 				}
 				if (!target) throw new Error("No completed assistant response found.");
-				return { source: target, text: await simplify(pi, target.text, signal) };
+				return { source: target, text: await simplify(target.text, signal, onProgress) };
 			};
 
 			if (action === "open") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-bro",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "An Earendil Pi extension that simplifies the latest assistant response in a separate, context-isolated window.",
   "type": "module",
   "license": "MIT",