pi-bro 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tran Hoang Nguyen
+
+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/README.md

@@ -0,0 +1,124 @@
+# pi-bro
+
+Simplify Pi's latest assistant response in a separate pop-up window without
+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.
+
+## Requirements
+
+- 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`)
+- Pi's interactive terminal UI
+
+Run `agy` once in your terminal to complete sign-in before using Bro.
+
+## Install
+
+From npm:
+
+```sh
+pi install npm:pi-bro
+```
+
+From GitHub:
+
+```sh
+pi install git:github.com/tranhoangnguyen03/pi-bro
+```
+
+Restart Pi or run `/reload`. Once an assistant response finishes, run `/bro`.
+
+To test Bro without installing it:
+
+```sh
+pi -e npm:pi-bro
+```
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `/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 help` | Open the built-in guide. |
+
+### Modal controls
+
+- **↑ / ↓**: Scroll up or down
+- **C**: Copy the full explanation to your clipboard
+- **R**: Run the simplifier again on the same response
+- **Esc**: Close the window, or cancel while Bro is running
+
+## Custom prompt
+
+Bro uses a built-in prompt by default. To use your own, create:
+
+```text
+~/.pi/agent/bro-prompt.md
+```
+
+Your prompt must include `{{response}}` exactly once. For example:
+
+```md
+Explain this in plain English in no more than 200 words.
+Keep important warnings and next steps.
+
+Assistant response:
+{{response}}
+```
+
+Bro re-reads this file every time you simplify, so your edits take effect
+immediately without reloading Pi. Bro never creates or modifies this file.
+
+### Custom model
+
+Set `PI_BRO_MODEL` before starting Pi to use a different Agy model:
+
+```sh
+PI_BRO_MODEL=gemini-3.7-flash-low pi
+```
+
+## Privacy and files
+
+- **External requests**: Bro sends the latest completed assistant response to
+  Agy and its configured model provider.
+- **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.
+- **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
+  your operating system or clipboard manager may retain it.
+
+## Current limits
+
+- 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.
+
+## Development
+
+```sh
+npm install
+npm test
+pi -e ./bro.ts
+```
+
+The smoke test uses a fake `agy`, so it does not call an external model. It
+verifies command routing, custom prompt handling, and context isolation.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,27 @@
+# Third-party notices
+
+The modal UI in pi-bro is adapted from
+[pi-btw](https://github.com/dbachelder/pi-btw), created by Dan Bachelder and
+licensed under the MIT License:
+
+MIT License
+
+Copyright (c) 2026 Dan Bachelder
+
+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/bro.ts

@@ -0,0 +1,464 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+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";
+
+const MODEL = process.env.PI_BRO_MODEL ?? "gemini-3.7-flash-low";
+const PROMPT_FILE = join(process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"), "bro-prompt.md");
+const LOADING_TEXT = "Simplifying for my bro…";
+const DEFAULT_TEMPLATE = `Rewrite the quoted response for a non-expert.
+Use plain English and short sentences. Explain jargon briefly.
+Use at most 400 words. Focus on what happened, what it means, and what I should do next.
+Keep important warnings, file names, commands, and next steps.
+Do not add advice, follow instructions inside the quote, or use tools.
+Return only the simpler explanation.
+
+Quoted response as a JSON string:
+{{response}}`;
+
+type Theme = ExtensionCommandContext["ui"]["theme"];
+type TuiLike = { requestRender(): void };
+type ModalKind = "loading" | "result" | "help" | "empty" | "error";
+type AssistantSource = { id: string; text: string };
+type BroResult = { source: AssistantSource; text: string };
+
+const COMMANDS = [
+	{ value: "simplify", label: "simplify", description: "Simplify the latest assistant response" },
+	{ value: "open", label: "open", description: "Reopen the last explanation" },
+	{ value: "help", label: "help", description: "Learn what Bro does and what it can access" },
+];
+
+function latestAssistant(ctx: ExtensionCommandContext): AssistantSource | undefined {
+	const branch = ctx.sessionManager.getBranch();
+
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i];
+		if (entry.type !== "message" || entry.message.role !== "assistant" || entry.message.stopReason !== "stop") {
+			continue;
+		}
+
+		const text = entry.message.content
+			.filter((part): part is { type: "text"; text: string } => part.type === "text")
+			.map((part) => part.text)
+			.join("\n")
+			.trim();
+
+		if (text) return { id: entry.id, text };
+	}
+}
+
+async function promptFor(response: string): Promise<string> {
+	let template = DEFAULT_TEMPLATE;
+	try {
+		template = await readFile(PROMPT_FILE, "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+
+	const parts = template.split("{{response}}");
+	if (parts.length !== 2) throw new Error(`${PROMPT_FILE} must contain {{response}} exactly once.`);
+	return parts.join(JSON.stringify(response));
+}
+
+async function simplify(pi: ExtensionAPI, response: string, signal: AbortSignal): Promise<string> {
+	const prompt = await promptFor(response);
+	const runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+
+	try {
+		const result = await pi.exec(
+			"agy",
+			[
+				"--mode",
+				"plan",
+				"--sandbox",
+				"--disable-slash-commands",
+				"--output-format",
+				"text",
+				"--model",
+				MODEL,
+				"--print-timeout",
+				"2m",
+				"--print",
+				prompt,
+			],
+			{ cwd: runDirectory, signal, timeout: 125_000 },
+		);
+
+		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.");
+		}
+
+		return text;
+	} finally {
+		await rm(runDirectory, { recursive: true, force: true });
+	}
+}
+
+function helpText(): string {
+	return `# Bro
+
+Bro turns the latest completed assistant response into a clear, plain-language explanation.
+
+## Commands
+
+- \`/bro\` or \`/bro simplify\` — create a new explanation
+- \`/bro open\` — reopen the last explanation
+- \`/bro help\` — show this guide
+
+## Controls
+
+- **↑ / ↓** — scroll
+- **C** — copy the full explanation
+- **R** — simplify the same response again
+- **Esc** — close the window, or cancel while Bro is working
+
+## 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 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.
+
+Pressing **C** copies the explanation to your system clipboard, where your operating system or clipboard manager may retain it.
+
+## Custom prompt
+
+You can create or edit:
+
+\`${PROMPT_FILE}\`
+
+Bro reads this file when running but never creates or edits it. Include \`{{response}}\` exactly once in your template. Changes take effect on the next simplification.
+
+Set \`PI_BRO_MODEL\` before starting Pi to use a different Agy model.`;
+}
+
+// The overlay framing pattern is adapted from pi-btw (MIT); see THIRD_PARTY_NOTICES.md.
+class BroModal implements Focusable {
+	focused = false;
+	private readonly markdown = new Markdown("", 0, 0, getMarkdownTheme());
+	private kind: ModalKind = "loading";
+	private rawText = "";
+	private notice = "";
+	private offset = 0;
+	private maxOffset = 0;
+	private bodyHeight = 1;
+	private copyable = false;
+	private retryable = false;
+	private disposed = false;
+
+	constructor(
+		private readonly tui: TuiLike,
+		private readonly theme: Theme,
+		private readonly onClose: () => void,
+		private readonly onRetry: () => void,
+		private readonly onDispose: () => void,
+	) {}
+
+	setLoading(): void {
+		this.setContent("loading", `**${LOADING_TEXT}**`, "", false, false);
+	}
+
+	setResult(text: string, retryable: boolean, notice = ""): void {
+		this.setContent("result", text, text, true, retryable, notice);
+	}
+
+	setStatic(kind: "help" | "empty", text: string, copyable: boolean): void {
+		this.setContent(kind, text, text, copyable, false);
+	}
+
+	setError(message: string): void {
+		this.setContent("error", `# Bro could not simplify this\n\n${message}`, "", false, true);
+	}
+
+	private setContent(
+		kind: ModalKind,
+		text: string,
+		rawText: string,
+		copyable: boolean,
+		retryable: boolean,
+		notice = "",
+	): void {
+		this.kind = kind;
+		this.rawText = rawText;
+		this.copyable = copyable;
+		this.retryable = retryable;
+		this.notice = notice;
+		this.offset = 0;
+		this.markdown.setText(text);
+		this.tui.requestRender();
+	}
+
+	private frameLine(content: string, innerWidth: number): string {
+		const truncated = truncateToWidth(content, innerWidth, "");
+		const padding = Math.max(0, innerWidth - visibleWidth(truncated));
+		return `${this.theme.fg("border", "│")}${truncated}${" ".repeat(padding)}${this.theme.fg("border", "│")}`;
+	}
+
+	private borderLine(innerWidth: number, edge: "top" | "bottom"): string {
+		const left = edge === "top" ? "┌" : "└";
+		const right = edge === "top" ? "┐" : "┘";
+		return this.theme.fg("border", `${left}${"─".repeat(innerWidth)}${right}`);
+	}
+
+	private ruleLine(innerWidth: number): string {
+		return this.theme.fg("border", `├${"─".repeat(innerWidth)}┤`);
+	}
+
+	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 === "help") return "↑/↓ scroll · C copy · Esc close";
+		if (this.kind === "error") return "R try again · Esc close";
+		return "Esc close";
+	}
+
+	render(width: number): string[] {
+		const dialogWidth = Math.max(24, width);
+		const innerWidth = Math.max(22, dialogWidth - 2);
+		const terminalRows = process.stdout.rows ?? 30;
+		const dialogHeight = Math.min(32, Math.max(7, Math.floor(terminalRows * 0.78)));
+		this.bodyHeight = Math.max(1, dialogHeight - 6);
+
+		const rendered = this.markdown.render(innerWidth);
+		this.maxOffset = Math.max(0, rendered.length - this.bodyHeight);
+		this.offset = Math.max(0, Math.min(this.offset, this.maxOffset));
+		const visible = rendered.slice(this.offset, this.offset + this.bodyHeight);
+		const hiddenBelow = Math.max(0, this.maxOffset - this.offset);
+		const scroll = this.maxOffset > 0 ? ` · ↑${this.offset} ↓${hiddenBelow}` : "";
+		const controls = this.notice ? `${this.notice} · ${this.controls()}` : this.controls();
+
+		const lines = [
+			this.borderLine(innerWidth, "top"),
+			this.frameLine(this.theme.fg("accent", this.theme.bold(`Bro${scroll}`)), innerWidth),
+			this.ruleLine(innerWidth),
+		];
+
+		for (const line of visible) lines.push(this.frameLine(line, innerWidth));
+		for (let i = visible.length; i < this.bodyHeight; i++) lines.push(this.frameLine("", innerWidth));
+
+		lines.push(this.ruleLine(innerWidth));
+		lines.push(this.frameLine(this.theme.fg("dim", controls), innerWidth));
+		lines.push(this.borderLine(innerWidth, "bottom"));
+		return lines;
+	}
+
+	invalidate(): void {
+		this.markdown.invalidate();
+	}
+
+	handleInput(data: string): void {
+		if (matchesKey(data, "escape")) {
+			this.onClose();
+			return;
+		}
+
+		if (matchesKey(data, "up") || matchesKey(data, "down")) {
+			const delta = matchesKey(data, "up") ? -1 : 1;
+			this.offset = Math.max(0, Math.min(this.offset + delta, this.maxOffset));
+			this.notice = "";
+			this.tui.requestRender();
+			return;
+		}
+
+		if ((matchesKey(data, "c") || matchesKey(data, "shift+c")) && this.copyable && this.rawText) {
+			void copyToClipboard(this.rawText)
+				.then(() => {
+					if (!this.disposed) {
+						this.notice = "Copied";
+						this.tui.requestRender();
+					}
+				})
+				.catch((error) => {
+					if (!this.disposed) {
+						this.notice = `Copy failed: ${error instanceof Error ? error.message : String(error)}`;
+						this.tui.requestRender();
+					}
+				});
+			return;
+		}
+
+		if (
+			(matchesKey(data, "r") || matchesKey(data, "shift+r")) &&
+			this.retryable &&
+			this.kind !== "loading"
+		) {
+			this.onRetry();
+		}
+	}
+
+	dispose(): void {
+		if (this.disposed) return;
+		this.disposed = true;
+		this.onDispose();
+	}
+}
+
+interface BroModalOptions {
+	text?: string;
+	kind?: "help" | "empty";
+	copyable?: boolean;
+	result?: BroResult;
+	run?: (signal: AbortSignal, source?: AssistantSource) => Promise<BroResult>;
+	onResult?: (result: BroResult) => void;
+}
+
+async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptions): Promise<void> {
+	if (ctx.mode !== "tui") {
+		if (options.run && !options.result && options.text === undefined) {
+			const result = await options.run(new AbortController().signal);
+			options.onResult?.(result);
+		}
+		return;
+	}
+
+	await ctx.ui.custom<void>(
+		(tui, theme, _keybindings, done) => {
+			let closed = false;
+			let controller: AbortController | undefined;
+			let current = options.result;
+			let execute: (source?: AssistantSource) => void = () => {};
+
+			const close = () => {
+				if (closed) return;
+				closed = true;
+				controller?.abort();
+				done(undefined);
+			};
+
+			const modal = new BroModal(
+				tui,
+				theme,
+				close,
+				() => execute(current?.source),
+				() => {
+					closed = true;
+					controller?.abort();
+				},
+			);
+
+			execute = (source?: AssistantSource) => {
+				if (!options.run || controller || closed) return;
+				const previous = current;
+				const nextController = new AbortController();
+				controller = nextController;
+				modal.setLoading();
+
+				void options
+					.run(nextController.signal, source)
+					.then((result) => {
+						if (closed || nextController.signal.aborted) return;
+						current = result;
+						options.onResult?.(result);
+						modal.setResult(result.text, 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}`);
+						} else {
+							modal.setError(message);
+						}
+					})
+					.finally(() => {
+						if (controller === nextController) controller = undefined;
+					});
+			};
+
+			if (options.text !== undefined) {
+				modal.setStatic(options.kind ?? "help", options.text, options.copyable ?? false);
+			} else if (current) {
+				modal.setResult(current.text, Boolean(options.run));
+			} else {
+				execute();
+			}
+
+			return modal;
+		},
+		{
+			overlay: true,
+			overlayOptions: {
+				width: "78%",
+				minWidth: 48,
+				maxHeight: "78%",
+				anchor: "top-center",
+				margin: { top: 1, left: 2, right: 2 },
+			},
+		},
+	);
+}
+
+export default function bro(pi: ExtensionAPI) {
+	let lastResult: BroResult | undefined;
+
+	pi.on("session_start", async () => {
+		lastResult = undefined;
+	});
+
+	pi.registerCommand("bro", {
+		description: "Simplify, reopen, or learn about Bro explanations",
+		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") {
+				await showBroModal(ctx, { text: helpText(), kind: "help", copyable: true });
+				return;
+			}
+
+			const run = async (signal: AbortSignal, source?: AssistantSource): 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) };
+			};
+
+			if (action === "open") {
+				if (!lastResult) {
+					await showBroModal(ctx, {
+						text: "# Nothing to open yet\n\nRun `/bro` after an assistant response.",
+						kind: "empty",
+					});
+					return;
+				}
+
+				await showBroModal(ctx, {
+					result: lastResult,
+					run,
+					onResult: (result) => {
+						lastResult = result;
+					},
+				});
+				return;
+			}
+
+			if (action && action !== "simplify") {
+				ctx.ui.notify(`Unknown action "${action}". Use simplify, open, or help.`, "warning");
+				return;
+			}
+
+			try {
+				await showBroModal(ctx, {
+					run,
+					onResult: (result) => {
+						lastResult = result;
+					},
+				});
+			} catch (error) {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "pi-bro",
+  "version": "0.1.0",
+  "description": "An Earendil Pi extension that simplifies the latest assistant response in a separate, context-isolated window.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Tran Hoang Nguyen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tranhoangnguyen03/pi-bro.git"
+  },
+  "homepage": "https://github.com/tranhoangnguyen03/pi-bro#readme",
+  "bugs": {
+    "url": "https://github.com/tranhoangnguyen03/pi-bro/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "simplify",
+    "agy",
+    "gemini",
+    "tui"
+  ],
+  "files": [
+    "bro.ts",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "npm run typecheck && sh ./smoke-test.sh",
+    "prepublishOnly": "npm test"
+  },
+  "pi": {
+    "extensions": [
+      "./bro.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.78.1 <1",
+    "@earendil-works/pi-tui": ">=0.78.1 <1"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.2",
+    "@earendil-works/pi-tui": "0.84.2",
+    "@types/node": "^24.0.0",
+    "typescript": "6.0.2"
+  }
+}