pi-bro 0.1.1 → 0.4.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.
@@ -299,6 +299,8 @@ pi -e npm:pi-bro
 | `/bro` | Create a new plain-language explanation of the latest completed assistant response. |
 | `/bro simplify` | Same as `/bro`. |
 | `/bro open` | Reopen the latest explanation without calling the simplifier again. |
+| `/bro usage` | Show current Agy resource limits. |
+| `/bro usage --provider agy` | Same as `/bro usage`, with the provider stated explicitly. |
 | `/bro help` | Open the built-in guide. |
 
 ### Modal controls
@@ -341,14 +343,16 @@ PI_BRO_MODEL=gemini-3.7-flash-low pi
 
 - **External requests**: Bro sends the latest completed assistant response to
   Agy and its configured model provider.
+- **Usage checks**: `/bro usage` checks your authenticated Agy limits without
+  sending an assistant response or running a model turn.
 - **Context isolation**: Bro does not add explanations to Pi's conversation
   history, session files, or main-agent context.
 - **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
@@ -356,10 +360,14 @@ PI_BRO_MODEL=gemini-3.7-flash-low pi
 
 ## Current limits
 
-- Supports only Agy/Gemini in v0.1.
+- Uses Agy as its only provider.
 - 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,16 +22,78 @@ 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 ModalResult = { 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" },
 	{ value: "open", label: "open", description: "Reopen the last explanation" },
+	{ value: "usage", label: "usage", description: "Show current Agy usage" },
 	{ value: "help", label: "help", description: "Learn what Bro does and what it can access" },
 ];
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+export function formatAgyUsage(value: unknown): string {
+	if (!isRecord(value) || value.status !== "SUCCESS" || typeof value.response !== "string") {
+		throw new Error("Agy returned invalid usage data.");
+	}
+
+	const groups = new Map<string, string[]>();
+	for (const line of value.response.trim().split("\n")) {
+		const [group, limit, remaining, resetTime] = line.split("\t");
+		if (!group || !limit || !remaining) throw new Error("Agy returned invalid usage data.");
+		const reset = resetTime ? new Date(resetTime) : undefined;
+		const resetText = reset && !Number.isNaN(reset.getTime()) ? ` — resets ${reset.toLocaleString()}` : "";
+		const items = groups.get(group) ?? [];
+		items.push(`- **${limit}:** ${remaining}${resetText}`);
+		groups.set(group, items);
+	}
+	if (!groups.size) throw new Error("Agy returned no usage information.");
+
+	const sections = [...groups].map(([group, items]) => `## ${group}\n\n${items.join("\n")}`);
+	return `# Agy usage\n\n${sections.join("\n\n")}`;
+}
+
+async function checkAgyUsage(pi: ExtensionAPI, signal: AbortSignal): Promise<string> {
+	const runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+	try {
+		const result = await pi.exec(
+			"agy",
+			["-p", "/usage", "--output-format", "json", "--print-timeout", "30s", "--sandbox"],
+			{ cwd: runDirectory, signal, timeout: 35_000 },
+		);
+		if (signal.aborted) throw new Error("Canceled.");
+		if (result.killed) throw new Error("Agy usage check timed out.");
+		if (result.code !== 0) throw new Error(result.stderr.trim() || `Agy exited with code ${result.code}.`);
+		try {
+			return formatAgyUsage(JSON.parse(result.stdout));
+		} catch (error) {
+			if (error instanceof SyntaxError) throw new Error("Agy returned invalid usage data.");
+			throw error;
+		}
+	} finally {
+		await rm(runDirectory, { recursive: true, force: true });
+	}
+}
+
 function latestAssistant(ctx: ExtensionCommandContext): AssistantSource | undefined {
 	const branch = ctx.sessionManager.getBranch();
 
@@ -62,20 +126,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 +176,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 });
 	}
 }
@@ -107,23 +257,29 @@ Bro turns the latest completed assistant response into a clear, plain-language e
 
 - \`/bro\` or \`/bro simplify\` — create a new explanation
 - \`/bro open\` — reopen the last explanation
+- \`/bro usage\` or \`/bro usage --provider agy\` — show current Agy usage
 - \`/bro help\` — show this guide
 
 ## 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.
 
 Bro sends the assistant response to an external simplifier (currently Agy with a Gemini model). Agy and the model provider may retain request data or logs under their own policies.
 
+\`/bro usage\` checks your authenticated Agy limits without sending an assistant response or running a model turn.
+
 Pressing **C** copies the explanation to your system clipboard, where your operating system or clipboard manager may retain it.
 
 ## Custom prompt
@@ -159,8 +315,12 @@ class BroModal implements Focusable {
 		private readonly onDispose: () => void,
 	) {}
 
-	setLoading(): void {
-		this.setContent("loading", `**${LOADING_TEXT}**`, "", false, false);
+	setLoading(text = LOADING_TEXT): void {
+		this.setContent("loading", `**${text}**`, "", false, false);
+	}
+
+	setStreaming(text: string): void {
+		this.setContent("streaming", text, "", false, false);
 	}
 
 	setResult(text: string, retryable: boolean, notice = ""): void {
@@ -172,7 +332,7 @@ class BroModal implements Focusable {
 	}
 
 	setError(message: string): void {
-		this.setContent("error", `# Bro could not simplify this\n\n${message}`, "", false, true);
+		this.setContent("error", `# Bro ran into a problem\n\n${message}`, "", false, true);
 	}
 
 	private setContent(
@@ -188,7 +348,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,7 +371,10 @@ class BroModal implements Focusable {
 
 	private controls(): string {
 		if (this.kind === "loading") return "Esc cancel";
-		if (this.kind === "result") return "↑/↓ scroll · C copy · R simplify again · Esc close";
+		if (this.kind === "streaming") return "Simplifying… · ↑/↓ scroll · Esc cancel";
+		if (this.kind === "result") {
+			return `↑/↓ scroll · C copy${this.retryable ? " · 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";
 		return "Esc close";
@@ -257,8 +420,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();
@@ -302,9 +465,15 @@ interface BroModalOptions {
 	text?: string;
 	kind?: "help" | "empty";
 	copyable?: boolean;
-	result?: BroResult;
-	run?: (signal: AbortSignal, source?: AssistantSource) => Promise<BroResult>;
-	onResult?: (result: BroResult) => void;
+	result?: ModalResult;
+	run?: (
+		signal: AbortSignal,
+		source?: AssistantSource,
+		onProgress?: (text: string) => void,
+	) => Promise<ModalResult>;
+	onResult?: (result: ModalResult) => void;
+	loadingText?: string;
+	retryable?: boolean;
 }
 
 async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptions): Promise<void> {
@@ -346,22 +515,25 @@ async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptio
 				const previous = current;
 				const nextController = new AbortController();
 				controller = nextController;
-				modal.setLoading();
+				modal.setLoading(options.loadingText);
 
 				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;
 						options.onResult?.(result);
-						modal.setResult(result.text, true);
+						modal.setResult(result.text, options.retryable ?? true);
 					})
 					.catch((error) => {
 						if (closed || nextController.signal.aborted) return;
 						const message = error instanceof Error ? error.message : String(error);
 						if (previous) {
 							current = previous;
-							modal.setResult(previous.text, true, `Retry failed: ${message}`);
+							modal.setResult(previous.text, options.retryable ?? true, `Retry failed: ${message}`);
 						} else {
 							modal.setError(message);
 						}
@@ -374,7 +546,7 @@ async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptio
 			if (options.text !== undefined) {
 				modal.setStatic(options.kind ?? "help", options.text, options.copyable ?? false);
 			} else if (current) {
-				modal.setResult(current.text, Boolean(options.run));
+				modal.setResult(current.text, options.retryable ?? Boolean(options.run));
 			} else {
 				execute();
 			}
@@ -396,36 +568,64 @@ async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptio
 
 export default function bro(pi: ExtensionAPI) {
 	let lastResult: BroResult | undefined;
+	const remember = (result: ModalResult) => {
+		if (result.source) lastResult = { source: result.source, text: result.text };
+	};
 
 	pi.on("session_start", async () => {
 		lastResult = undefined;
 	});
 
 	pi.registerCommand("bro", {
-		description: "Simplify, reopen, or learn about Bro explanations",
+		description: "Simplify responses, reopen explanations, or show Agy usage",
 		getArgumentCompletions: (prefix) => {
 			const normalized = prefix.trim().toLowerCase();
 			const matches = COMMANDS.filter((command) => command.value.startsWith(normalized));
 			return matches.length ? matches : null;
 		},
 		handler: async (args, ctx) => {
-			const action = args.trim().toLowerCase();
-			if (action === "help") {
+			const normalized = args.trim().toLowerCase();
+			const parts = normalized ? normalized.split(/\s+/) : [];
+			const action = parts[0] ?? "";
+
+			if (action === "usage") {
+				const valid = parts.length === 1 || (parts.length === 3 && parts[1] === "--provider" && parts[2] === "agy");
+				if (!valid) {
+					ctx.ui.notify("Use /bro usage or /bro usage --provider agy.", "warning");
+					return;
+				}
+				try {
+					await showBroModal(ctx, {
+						loadingText: "Checking Agy usage…",
+						retryable: false,
+						run: async (signal) => ({ text: await checkAgyUsage(pi, signal) }),
+					});
+				} catch (error) {
+					ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				}
+				return;
+			}
+
+			if (normalized === "help") {
 				await showBroModal(ctx, { text: helpText(), kind: "help", copyable: true });
 				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") {
+			if (normalized === "open") {
 				if (!lastResult) {
 					await showBroModal(ctx, {
 						text: "# Nothing to open yet\n\nRun `/bro` after an assistant response.",
@@ -437,24 +637,20 @@ export default function bro(pi: ExtensionAPI) {
 				await showBroModal(ctx, {
 					result: lastResult,
 					run,
-					onResult: (result) => {
-						lastResult = result;
-					},
+					onResult: remember,
 				});
 				return;
 			}
 
-			if (action && action !== "simplify") {
-				ctx.ui.notify(`Unknown action "${action}". Use simplify, open, or help.`, "warning");
+			if (normalized && normalized !== "simplify") {
+				ctx.ui.notify(`Unknown action "${normalized}". Use simplify, open, usage, or help.`, "warning");
 				return;
 			}
 
 			try {
 				await showBroModal(ctx, {
 					run,
-					onResult: (result) => {
-						lastResult = result;
-					},
+					onResult: remember,
 				});
 			} catch (error) {
 				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");

package/package.json

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