pi-bro 0.3.0 → 0.5.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 stream plain-language explanations.
+and your selected Agy 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 >=1.1.8` installed, authenticated, and on your `PATH` (tested on `1.1.13`)
+- `agy >=1.1.11` 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,15 +299,54 @@ 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 model` | Choose from the models currently available through Agy. |
+| `/bro model <id>` | Set an available Agy model directly. |
+| `/bro effort` | Choose an effort supported by the current model. |
+| `/bro effort <low\|medium\|high>` | Set a supported reasoning effort directly. |
 | `/bro help` | Open the built-in guide. |
 
 ### Modal controls
 
+- **Mouse wheel / trackpad**: Scroll in Pi's fullscreen mode
 - **↑ / ↓**: 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
 
+In Pi's regular terminal mode, the Bro title warns that mouse-wheel scrolling
+needs fullscreen mode. Arrow-key scrolling still works.
+
+## Settings
+
+Bro creates this user-editable settings file when the extension loads:
+
+```text
+~/.pi/agent/bro-settings.json
+```
+
+```json
+{
+  "model": "gemini-3.7-flash",
+  "effort": "low"
+}
+```
+
+Use `/bro model` and `/bro effort` to update it from Pi, or edit it directly.
+Bro reads the file again before each explanation, so manual changes apply to
+the next `/bro`. Use a model ID shown by `/bro model`; `effort` must be
+one of the levels shown by `/bro effort`. Models without adjustable effort use
+`default`. The choices remain active across Pi restarts until you change them.
+`/bro help` shows the active settings and the exact file path.
+
+If `PI_CODING_AGENT_DIR` is set, the file lives there instead. `PI_BRO_MODEL`
+chooses the initial model only when Bro creates a missing settings file:
+
+```sh
+PI_BRO_MODEL=gemini-3.7-flash-low pi
+```
+
 ## Custom prompt
 
 Bro uses a built-in prompt by default. To use your own, create:
@@ -329,18 +368,12 @@ Assistant 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.
+- **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
@@ -348,7 +381,8 @@ PI_BRO_MODEL=gemini-3.7-flash-low pi
   Pi.
 - **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.
+  not a security boundary. Bro only writes its own user settings file described
+  above.
 - **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,12 +390,13 @@ 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-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.
+  (`pi --tui-mode fullscreen`). In regular mode, Bro shows a warning in its
+  title; 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.
 
@@ -370,11 +405,12 @@ PI_BRO_MODEL=gemini-3.7-flash-low pi
 ```sh
 npm install
 npm test
-pi -e ./bro.ts
+pi --tui-mode fullscreen -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.
+verifies command routing, settings, custom prompt handling, and context
+isolation.
 
 ## License
 

package/bro.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { createInterface } from "node:readline";
@@ -7,8 +7,11 @@ import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-c
 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 AGENT_DIR = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+const ENV_MODEL = process.env.PI_BRO_MODEL?.trim();
+const DEFAULT_MODEL = ENV_MODEL || "gemini-3.7-flash";
+const PROMPT_FILE = join(AGENT_DIR, "bro-prompt.md");
+const SETTINGS_FILE = join(AGENT_DIR, "bro-settings.json");
 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.
@@ -21,10 +24,21 @@ Quoted response as a JSON string:
 {{response}}`;
 
 type Theme = ExtensionCommandContext["ui"]["theme"];
-type TuiLike = { requestRender(): void };
+type TuiLike = { readonly mode: "regular" | "fullscreen"; requestRender(): void };
 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 };
+const EFFORTS = ["default", "low", "medium", "high"] as const;
+type BroEffort = (typeof EFFORTS)[number];
+type AgyEffort = Exclude<BroEffort, "default">;
+type BroSettings = { model: string; effort: BroEffort };
+type AgyModelFamily = {
+	id: string;
+	label: string;
+	efforts: AgyEffort[];
+	variants: Array<{ id: string; effort?: AgyEffort }>;
+};
 type AgyEvent = {
 	event?: string;
 	step_update?: { step_type?: string; text_delta?: unknown };
@@ -42,9 +56,172 @@ export function wheelDelta(data: string): number {
 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: "model", label: "model", description: "Choose the Agy model" },
+	{ value: "effort", label: "effort", description: "Choose the Agy reasoning effort" },
 	{ 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 parseBroSettings(value: unknown): BroSettings {
+	if (
+		!isRecord(value) ||
+		typeof value.model !== "string" ||
+		!value.model.trim() ||
+		!EFFORTS.some((effort) => effort === value.effort)
+	) {
+		throw new Error('Settings must contain a model and effort set to "default", "low", "medium", or "high".');
+	}
+	return { model: value.model.trim(), effort: value.effort as BroSettings["effort"] };
+}
+
+async function ensureSettingsFile(): Promise<void> {
+	await mkdir(AGENT_DIR, { recursive: true });
+	try {
+		await writeFile(
+			SETTINGS_FILE,
+			`${JSON.stringify({ model: DEFAULT_MODEL, effort: ENV_MODEL ? "default" : "low" }, null, 2)}\n`,
+			{ encoding: "utf8", flag: "wx", mode: 0o600 },
+		);
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+	}
+}
+
+async function readSettings(): Promise<BroSettings> {
+	await ensureSettingsFile();
+	try {
+		return parseBroSettings(JSON.parse(await readFile(SETTINGS_FILE, "utf8")));
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new Error(`${SETTINGS_FILE} is not valid JSON.`);
+		if (error instanceof Error) throw new Error(`${SETTINGS_FILE}: ${error.message}`);
+		throw error;
+	}
+}
+
+async function writeSettings(settings: BroSettings): Promise<void> {
+	// ponytail: last writer wins across concurrent Pi processes; add locking only if that becomes a common workflow.
+	await writeFile(SETTINGS_FILE, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+}
+
+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")}`;
+}
+
+export function parseAgyModels(output: string): AgyModelFamily[] {
+	// ponytail: Agy 1.1.13 exposes a tab-separated variant list; use structured catalog data when available here.
+	const families = new Map<string, AgyModelFamily>();
+	for (const line of output.split(/\r?\n/)) {
+		const [rawId, ...rawLabel] = line.split("\t");
+		if (!rawId?.trim() || !rawLabel.length) continue;
+		const id = rawId.trim();
+		const label = rawLabel.join(" ").trim();
+		const effort = (["low", "medium", "high"] as const).find(
+			(value) => id.endsWith(`-${value}`) && label.endsWith(`(${value[0].toUpperCase()}${value.slice(1)})`),
+		);
+		const familyId = effort ? id.slice(0, -effort.length - 1) : id;
+		const family = families.get(familyId) ?? {
+			id: familyId,
+			label: effort ? label.replace(/\s+\((Low|Medium|High)\)$/, "") : label,
+			efforts: [],
+			variants: [],
+		};
+		if (effort && !family.efforts.includes(effort)) family.efforts.push(effort);
+		family.variants.push({ id, effort });
+		families.set(familyId, family);
+	}
+	if (!families.size) throw new Error("Agy returned no available models.");
+	for (const family of families.values()) {
+		family.efforts.sort((a, b) => EFFORTS.indexOf(a) - EFFORTS.indexOf(b));
+	}
+	return [...families.values()];
+}
+
+async function listAgyModels(pi: ExtensionAPI): Promise<AgyModelFamily[]> {
+	const runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
+	try {
+		const result = await pi.exec("agy", ["models"], { cwd: runDirectory, timeout: 30_000 });
+		if (result.killed) throw new Error("Agy model check timed out.");
+		if (result.code !== 0) throw new Error(result.stderr.trim() || `Agy exited with code ${result.code}.`);
+		return parseAgyModels(result.stdout);
+	} finally {
+		await rm(runDirectory, { recursive: true, force: true });
+	}
+}
+
+function resolveCatalogSettings(
+	settings: BroSettings,
+	families: AgyModelFamily[],
+): { settings: BroSettings; family?: AgyModelFamily } {
+	const family = families.find(
+		(item) => item.id === settings.model || item.variants.some((variant) => variant.id === settings.model),
+	);
+	if (!family) return { settings };
+	const variant = family.variants.find((item) => item.id === settings.model);
+	return {
+		family,
+		settings: {
+			model: family.id,
+			effort: settings.effort === "default" && variant?.effort ? variant.effort : settings.effort,
+		},
+	};
+}
+
+function preferredEffort(family: AgyModelFamily): BroEffort {
+	return family.efforts.includes("low") ? "low" : (family.efforts[0] ?? "default");
+}
+
+export function agySelection(settings: BroSettings): { model: string; effort?: AgyEffort } {
+	if (settings.effort === "default") return { model: settings.model };
+	const suffix = (["low", "medium", "high"] as const).find((effort) => settings.model.endsWith(`-${effort}`));
+	return {
+		model: suffix ? settings.model.slice(0, -suffix.length - 1) : settings.model,
+		effort: settings.effort,
+	};
+}
+
+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();
 
@@ -106,9 +283,11 @@ function parseAgyLine(line: string): { delta?: string; result?: string } {
 async function simplify(
 	response: string,
 	signal: AbortSignal,
+	settings: BroSettings,
 	onProgress?: (text: string) => void,
 ): Promise<string> {
 	const prompt = await promptFor(response);
+	const selection = agySelection(settings);
 	const runDirectory = await mkdtemp(join(tmpdir(), "pi-bro-"));
 	let updateTimer: ReturnType<typeof setTimeout> | undefined;
 
@@ -121,7 +300,8 @@ async function simplify(
 				"--output-format",
 				"stream-json",
 				"--model",
-				MODEL,
+				selection.model,
+				...(selection.effort ? ["--effort", selection.effort] : []),
 				"--print-timeout",
 				"2m",
 				"--print",
@@ -199,7 +379,7 @@ async function simplify(
 	}
 }
 
-function helpText(): string {
+function helpText(settings: BroSettings): string {
 	return `# Bro
 
 Bro turns the latest completed assistant response into a clear, plain-language explanation.
@@ -208,8 +388,22 @@ 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 model\` — choose the Agy model
+- \`/bro effort\` — choose the Agy reasoning effort
 - \`/bro help\` — show this guide
 
+## Current simplifier settings
+
+- **Model:** \`${settings.model}\`
+- **Reasoning effort:** ${settings.effort === "default" ? "built into the selected model" : settings.effort}
+
+These choices are saved in:
+
+\`${SETTINGS_FILE}\`
+
+Use the slash commands or edit that file directly. Changes apply to future explanations and remain active across Pi restarts until you change them. Use a model ID shown by \`/bro model\`. Use an effort shown by \`/bro effort\`; fixed-effort models use \`default\`.
+
 ## Controls
 
 - **Mouse wheel / trackpad** — scroll in Pi's fullscreen mode
@@ -218,15 +412,19 @@ Bro turns the latest completed assistant response into a clear, plain-language e
 - **R** — simplify the same response again
 - **Esc** — close the window, or cancel while Bro is working
 
+In Pi's regular terminal mode, the Bro title warns that mouse-wheel scrolling needs fullscreen mode. Arrow-key scrolling still works.
+
 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 sandbox mode inside a temporary empty folder. This reduces project access, but it is not a security boundary.
+Bro does not modify your project files. It creates and updates only its user settings file shown above. 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 sends the assistant response to an external simplifier (currently Agy with your selected 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.
 
@@ -238,7 +436,7 @@ You can create or edit:
 
 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.`;
+When the settings file does not exist yet, \`PI_BRO_MODEL\` can choose its initial model.`;
 }
 
 // The overlay framing pattern is adapted from pi-btw (MIT); see THIRD_PARTY_NOTICES.md.
@@ -263,8 +461,8 @@ 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 {
@@ -280,7 +478,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(
@@ -320,7 +518,9 @@ 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 === "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";
@@ -338,12 +538,13 @@ class BroModal implements Focusable {
 		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 modeHint = this.tui.mode === "regular" ? " · mouse wheel needs fullscreen" : "";
 		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.frameLine(this.theme.fg("accent", this.theme.bold(`Bro${modeHint}${scroll}`)), innerWidth),
 			this.ruleLine(innerWidth),
 		];
 
@@ -411,13 +612,15 @@ interface BroModalOptions {
 	text?: string;
 	kind?: "help" | "empty";
 	copyable?: boolean;
-	result?: BroResult;
+	result?: ModalResult;
 	run?: (
 		signal: AbortSignal,
 		source?: AssistantSource,
 		onProgress?: (text: string) => void,
-	) => Promise<BroResult>;
-	onResult?: (result: BroResult) => void;
+	) => Promise<ModalResult>;
+	onResult?: (result: ModalResult) => void;
+	loadingText?: string;
+	retryable?: boolean;
 }
 
 async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptions): Promise<void> {
@@ -459,7 +662,7 @@ 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, (text) => {
@@ -470,14 +673,14 @@ async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptio
 						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);
 						}
@@ -490,7 +693,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();
 			}
@@ -510,24 +713,164 @@ async function showBroModal(ctx: ExtensionCommandContext, options: BroModalOptio
 	);
 }
 
-export default function bro(pi: ExtensionAPI) {
+export default async function bro(pi: ExtensionAPI) {
+	await ensureSettingsFile();
 	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 and manage Bro",
 		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 });
+			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 (action === "model") {
+				if (parts.length > 2) {
+					ctx.ui.notify("Use /bro model or /bro model <id>.", "warning");
+					return;
+				}
+				try {
+					const settings = await readSettings();
+					const models = await listAgyModels(pi);
+					const current = resolveCatalogSettings(settings, models);
+					const requested = parts[1];
+					let selected: AgyModelFamily | undefined;
+					let selectedEffort: BroEffort | undefined;
+					if (requested) {
+						selected = models.find((item) => item.id.toLowerCase() === requested);
+						if (!selected) {
+							for (const family of models) {
+								const variant = family.variants.find((item) => item.id.toLowerCase() === requested);
+								if (variant) {
+									selected = family;
+									selectedEffort = variant.effort ?? "default";
+									break;
+								}
+							}
+						}
+						if (!selected) {
+							ctx.ui.notify(`Unknown Agy model "${requested}". Run /bro model to see available choices.`, "warning");
+							return;
+						}
+					} else {
+						if (ctx.mode !== "tui") {
+							ctx.ui.notify("Use /bro model <id> outside Pi's interactive UI.", "warning");
+							return;
+						}
+						const ordered = [...models].sort((a, b) => Number(b.id === current.family?.id) - Number(a.id === current.family?.id));
+						const choices = ordered.map(
+							(item) =>
+								`${item.id} — ${item.label} · ${item.efforts.length ? item.efforts.join("/") : "fixed effort"}${item.id === current.family?.id ? " (current)" : ""}`,
+						);
+						const choice = await ctx.ui.select(`Agy model (current: ${current.settings.model})`, choices);
+						if (!choice) return;
+						selected = ordered[choices.indexOf(choice)];
+					}
+					if (!selectedEffort) {
+						const currentEffort = current.settings.effort;
+						const canKeepCurrent =
+							current.family?.id === selected.id &&
+							(currentEffort === "default" ? !selected.efforts.length : selected.efforts.includes(currentEffort));
+						selectedEffort = canKeepCurrent ? currentEffort : preferredEffort(selected);
+					}
+					await writeSettings({ model: selected.id, effort: selectedEffort });
+					ctx.ui.notify(
+						`Bro model: ${selected.id}${selectedEffort === "default" ? "" : ` (${selectedEffort})`}`,
+						"info",
+					);
+				} catch (error) {
+					ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				}
+				return;
+			}
+
+			if (action === "effort") {
+				const requested = parts[1];
+				if (parts.length > 2 || (requested && !EFFORTS.some((effort) => effort === requested))) {
+					ctx.ui.notify("Use /bro effort, or choose low, medium, or high.", "warning");
+					return;
+				}
+				try {
+					const settings = await readSettings();
+					const current = resolveCatalogSettings(settings, await listAgyModels(pi));
+					if (!current.family) {
+						ctx.ui.notify(`Model "${settings.model}" is not in Agy's current model list. Run /bro model first.`, "warning");
+						return;
+					}
+					if (!current.family.efforts.length) {
+						if (requested && requested !== "default") {
+							ctx.ui.notify(`${current.family.label} uses a fixed effort level.`, "warning");
+							return;
+						}
+						await writeSettings({ model: current.family.id, effort: "default" });
+						ctx.ui.notify(`${current.family.label} uses its built-in effort level.`, "info");
+						return;
+					}
+					if (requested === "default" || (requested && !current.family.efforts.includes(requested as AgyEffort))) {
+						ctx.ui.notify(
+							`${current.family.label} supports ${current.family.efforts.join(" or ")} effort.`,
+							"warning",
+						);
+						return;
+					}
+					let selected = requested as AgyEffort | undefined;
+					if (!selected) {
+						if (ctx.mode !== "tui") {
+							ctx.ui.notify("Use /bro effort <low|medium|high> outside Pi's interactive UI.", "warning");
+							return;
+						}
+						const efforts = [...current.family.efforts].sort(
+							(a, b) => Number(b === current.settings.effort) - Number(a === current.settings.effort),
+						);
+						const choices = efforts.map((effort) => `${effort}${effort === current.settings.effort ? " (current)" : ""}`);
+						const choice = await ctx.ui.select(`Agy reasoning effort (current: ${current.settings.effort})`, choices);
+						if (!choice) return;
+						selected = efforts[choices.indexOf(choice)];
+					}
+					await writeSettings({ model: current.family.id, effort: selected });
+					ctx.ui.notify(`Bro reasoning effort: ${selected}`, "info");
+				} catch (error) {
+					ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				}
+				return;
+			}
+
+			if (normalized === "help") {
+				try {
+					await showBroModal(ctx, { text: helpText(await readSettings()), kind: "help", copyable: true });
+				} catch (error) {
+					ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+				}
 				return;
 			}
 
@@ -542,10 +885,14 @@ export default function bro(pi: ExtensionAPI) {
 					target = latestAssistant(ctx);
 				}
 				if (!target) throw new Error("No completed assistant response found.");
-				return { source: target, text: await simplify(target.text, signal, onProgress) };
+				const settings = await readSettings();
+				return {
+					source: target,
+					text: await simplify(target.text, signal, settings, onProgress),
+				};
 			};
 
-			if (action === "open") {
+			if (normalized === "open") {
 				if (!lastResult) {
 					await showBroModal(ctx, {
 						text: "# Nothing to open yet\n\nRun `/bro` after an assistant response.",
@@ -557,24 +904,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, model, effort, 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.3.0",
+  "version": "0.5.0",
   "description": "An Earendil Pi extension that simplifies the latest assistant response in a separate, context-isolated window.",
   "type": "module",
   "license": "MIT",