pi-bro 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to pi-bro are documented here.
 
+## [0.28.0] - 2026-11-05
+
+### Highlights
+
+- Simplify gains a source-focused modal with internal /simplify, /text, /file, /url, /copy, /clear and /help commands.
+- Bare /bro captures a fresh latest assistant response; /bro simplify reopens the last Simplify view without a new model call.
+- M changes explanation mode for that source without rewriting the saved default; R retries the same source.
+- Existing explicit top-level source forms and backend selection remain compatible.
+
+
 ## [0.27.0] - 2026-10-30
 
 ### Highlights

package/docs/reference/commands.md

@@ -6,7 +6,7 @@
 
 | Source | Command | What Bro does |
 | --- | --- | --- |
-| Latest assistant reply | `/bro` | Explains the latest completed reply without adding the result to the conversation. |
+| Latest assistant reply | `/bro` | Opens Simplify and explains the latest completed reply without inserting the result into Pi's conversation. |
 | Pasted text | `/bro text <text>` | Explains text supplied directly in the command. |
 | Local document | `/bro file <path>` | Extracts text from a workspace-local Markdown, text, PDF, or DOCX file. |
 | Public webpage | `/bro url <url>` | Fetches one public HTML page and extracts its main readable content. |
@@ -22,12 +22,13 @@ text directly captures a new source the same way.
 
 | Command | Description |
 | --- | --- |
-| `/bro`, `/bro simplify`, or `/bro text` | Explain the latest completed assistant response. |
+| `/bro` | Open Simplify and explain the latest completed assistant reply. |
+| `/bro simplify` | Reopen the last Simplify screen within this Pi session, without a new model call. |
 | `/bro text <text>` | Explain pasted text. |
 | `/bro <input>` | Explain it directly: a lone URL runs the webpage reader, an existing workspace file with a supported extension runs the document reader, and anything else is pasted text. A quoted path with spaces is routed too when the file exists. |
 | `/bro file <path>` | Explain a workspace-local `.md`, `.markdown`, `.txt`, `.pdf`, or `.docx` file. |
 | `/bro url <url>` | Explain one public, text-based webpage. |
-| `/bro open` | Reopen the latest explanation without calling the simplifier again. |
+| `/bro open` | Legacy compatibility shortcut to the last result. No `/open` command inside Simplify. |
 | `/bro show [n-turns] [query]` | Draw recent session turns (default last 1) as shapes instead of prose, from user and assistant conversation text only — tool calls, tool results, reasoning, and images are omitted. An optional query steers what the shapes focus on, with or without a leading turn count. |
 | `/bro doctor` | Check Bro's settings, preferences, and each selected backend, with the effective backend/model/effort per feature. |
 | `/bro mode [brief\|balanced\|faithful]` | View or choose the explanation mode. |
@@ -50,3 +51,7 @@ Giving `/bro` the input directly works the same way:
 /bro docs/report.pdf
 /bro any other text is explained as pasted text
 ```
+
+## Simplify modal (single-source explanation)
+
+Once inside Simplify, use `/simplify` for the latest completed reply; `/text <text>`, `/file <path>`, `/url <url>` for a new source; `/copy` to copy the current explanation; `/clear` to return to the empty screen; and `/help` for controls. **M** changes the one-off Brief/Balanced/Faithful mode and re-explains the captured source; **R** retries the same source. This modal is not a conversation and does not persist history across restarts. Legacy `/bro text|file|url` shortcuts keep working. The global menu consolidation is tracked separately.

package/docs/user-guide.md

@@ -163,3 +163,7 @@ See [Privacy and safety](reference/data-and-permissions.md#privacy-and-safety).
 ## Troubleshooting and current limits
 
 See [Troubleshooting and current limits](reference/troubleshooting.md#troubleshooting-and-current-limits).
+
+## Simplify modal
+
+`/bro` opens Simplify and explains the latest completed assistant reply. `/bro simplify` returns to the most recent Simplify screen without another model request. Inside, `/simplify`, `/text <text>`, `/file <path>` and `/url <url>` produce one explanation at a time; `/copy` copies the answer, `/clear` clears it, and `/help` shows controls. Press **M** with an empty composer to change the explanation mode and rerun; **R** retries. The saved default mode remains unchanged. The current screen is kept only within the Pi session. Old `/bro text|file|url|open` forms remain callable for compatibility.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-bro",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "A sidekick for you and your Pi agent: plain-language explanations, side questions, diagrams, PR review and second opinions, without cluttering the agent's context.",
   "type": "module",
   "license": "MIT",
@@ -54,6 +54,8 @@
     "src/remember-engine.ts",
     "src/remember-tool.ts",
     "src/remember.ts",
+    "src/simplify-engine.ts",
+    "src/simplify-ui.ts",
     "src/explain-modal.ts",
     "src/review.ts",
     "src/review-source.ts",
@@ -93,7 +95,7 @@
   "scripts": {
     "docs:check": "node scripts/check-docs.mjs && node --test test/docs-quality.test.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "npm run typecheck && npm run docs:check && node .github/scripts/release-utils.mjs selftest && node --test test/elevate-docs.test.mjs test/elevate.test.ts test/grill.test.ts test/remember.test.ts test/remember-modal.test.mjs test/review-ux.test.mjs test/review-doctor.test.mjs test/review-versions.test.mjs test/review-regeneration.test.mjs test/review-modal.test.mjs test/review.test.ts test/review-ui.test.mjs test/review-session.test.mjs test/helpers.test.mjs test/prompt.test.ts test/backend.test.ts test/claude.test.ts test/grok.test.ts test/codex.test.ts test/muse.test.ts test/settings.test.ts test/sources.test.ts test/release.test.ts test/show-html.test.ts test/smoke-rpc.test.ts test/ui-capabilities.test.ts test/modal-contract.test.mjs benchmark/*.test.ts && sh ./test/smoke-test.sh",
+    "test": "npm run typecheck && npm run docs:check && node .github/scripts/release-utils.mjs selftest && node --test test/elevate-docs.test.mjs test/elevate.test.ts test/simplify.test.ts test/simplify-modal.test.mjs test/grill.test.ts test/remember.test.ts test/remember-modal.test.mjs test/review-ux.test.mjs test/review-doctor.test.mjs test/review-versions.test.mjs test/review-regeneration.test.mjs test/review-modal.test.mjs test/review.test.ts test/review-ui.test.mjs test/review-session.test.mjs test/helpers.test.mjs test/prompt.test.ts test/backend.test.ts test/claude.test.ts test/grok.test.ts test/codex.test.ts test/muse.test.ts test/settings.test.ts test/sources.test.ts test/release.test.ts test/show-html.test.ts test/smoke-rpc.test.ts test/ui-capabilities.test.ts test/modal-contract.test.mjs benchmark/*.test.ts && sh ./test/smoke-test.sh",
     "benchmark:dry-run": "node benchmark/run.ts dry-run",
     "benchmark:run": "node benchmark/run.ts run",
     "benchmark:report": "node benchmark/run.ts report",

package/src/bro.ts

@@ -12,6 +12,7 @@ import { setPiHostContext } from "./backend.ts";
 import { openElevateModal } from "./elevate.ts";
 import { openGrillModal } from "./grill.ts";
 import { openRememberModal } from "./remember.ts";
+import { openSimplifyWorkflow, type SimplifyState } from "./simplify-ui.ts";
 import { registerAboutUserTool } from "./remember-tool.ts";
 import { parseGrillArguments, type GrillThread } from "./grill-engine.ts";
 import {
@@ -42,8 +43,6 @@ import {
 } from "./show.ts";
 import {
 	type BroSource,
-	extractDocumentText,
-	extractWebPage,
 	isWorkspaceFile,
 	looksLikeWebUrl,
 } from "./sources.ts";
@@ -66,9 +65,11 @@ export * from "./grill-engine.ts";
 export * from "./remember-store.ts";
 export * from "./remember-engine.ts";
 export * from "./explain-modal.ts";
+export * from "./simplify-engine.ts";
+export * from "./simplify-ui.ts";
 
 const COMMANDS = [
-	{ value: "simplify", label: "simplify", description: "Explain the latest completed assistant reply (same as /bro)" },
+	{ value: "simplify", label: "simplify", description: "Reopen the last Simplify screen without a new model call" },
 	{ value: "text", label: "text", description: "Explain pasted text, or the latest reply when text is omitted" },
 	{ value: "file", label: "file", description: "Explain a local document" },
 	{ value: "url", label: "url", description: "Explain a public webpage" },
@@ -91,6 +92,7 @@ const KNOWN_ACTIONS = new Set(COMMANDS.map((command) => command.value));
 
 export default async function bro(pi: ExtensionAPI) {
 	let lastResult: ModalResult | undefined;
+	let simplifyState: SimplifyState = {};
 	let lastShowSteering: string | undefined;
 	let btwThread: BtwThread | undefined;
 	let grillThread: GrillThread | undefined;
@@ -105,6 +107,7 @@ export default async function bro(pi: ExtensionAPI) {
 
 	pi.on("session_start", async (_event, _ctx) => {
 		lastResult = undefined;
+		simplifyState = {};
 		btwThread = undefined;
 		grillThread = undefined;
 	});
@@ -129,8 +132,10 @@ export default async function bro(pi: ExtensionAPI) {
 			let value = raw.slice(raw.split(/\s+/, 1)[0]?.length ?? 0).trim();
 
 			if (action === "simplify") {
-				if (value) { ctx.ui.notify("Use /bro simplify for the latest reply, or /bro text <text> for pasted text.", "warning"); return; }
-				action = "";
+				if (value) { ctx.ui.notify("Use /bro simplify to reopen the last Simplify view; use /text, /file or /url inside it.", "warning"); return; }
+				try { await openSimplifyWorkflow(ctx, simplifyState, {kind:"resume"}); if (simplifyState.result) remember(simplifyState.result); }
+				catch (error) { ctx.ui.notify(withDoctor(error), "error"); }
+				return;
 			}
 
 			// Removed commands must never fall through to a paid text explanation.
@@ -153,6 +158,23 @@ export default async function bro(pi: ExtensionAPI) {
 				value = raw;
 			}
 
+			// Source operations open the same single-purpose Simplify modal, not separate
+			// top-level workflows. Old /bro text|file|url commands remain valid aliases.
+			if (!action || action === "text" || action === "file" || action === "url") {
+				if ((action === "file" || action === "url") && !value) {
+					ctx.ui.notify(`Use /bro ${action} <${action === "file" ? "path" : "url"}>.`, "warning");
+					return;
+				}
+				const initial = !action || (action === "text" && !value)
+					? {kind:"latest" as const}
+					: {kind:action as "text" | "file" | "url", input:value};
+				try {
+					await openSimplifyWorkflow(ctx, simplifyState, initial);
+					if (simplifyState.result) remember(simplifyState.result);
+				} catch (error) { ctx.ui.notify(withDoctor(error), "error"); }
+				return;
+			}
+
 			if (action === "show") {
 				const { requested, steering, invalid } = parseShowArguments(value);
 				if (invalid) {
@@ -191,41 +213,6 @@ export default async function bro(pi: ExtensionAPI) {
 				return;
 			}
 
-			if (action === "file" || action === "url") {
-				if (!value) {
-					ctx.ui.notify(`Use /bro ${action} <${action === "file" ? "path" : "url"}>.`, "warning");
-					return;
-				}
-				const runInput = async (
-					signal: AbortSignal,
-					source?: BroSource,
-					onProgress?: (text: string) => void,
-					mode?: BroMode,
-				): Promise<BroResult> => {
-					const target = source ?? (action === "url"
-						? await extractWebPage(value, signal)
-						: { text: await extractDocumentText(value, ctx.cwd, signal), label: unquote(value) });
-					try {
-						return {
-							source: target,
-							...(await simplify(target.text, signal, await readSettings(), onProgress, mode)),
-						};
-					} catch (error) {
-						throw new Error(withDoctor(error));
-					}
-				};
-				try {
-					await showBroModal(ctx, {
-						loadingText: action === "url" ? "Fetching and simplifying webpage…" : "Reading and simplifying document…",
-						run: runInput,
-						onResult: remember,
-					});
-				} catch (error) {
-					ctx.ui.notify(errorMessage(error), "error");
-				}
-				return;
-			}
-
 			if (action === "doctor") {
 				if (parts.length !== 1) {
 					ctx.ui.notify("Use /bro doctor.", "warning");

package/src/explain-modal.ts

@@ -384,12 +384,13 @@ Quick reference. Full user guide: https://github.com/tranhoangnguyen03/pi-bro/bl
 
 ## Explain and show
 
-- \`/bro\` or \`/bro simplify\` — explain the latest completed assistant reply
+- \`/bro\` — open Simplify and explain the latest completed assistant reply
+- \`/bro simplify\` — reopen the current Simplify screen without another model call
 - \`/bro text [text]\` — explain pasted text, or the latest reply when text is omitted
 - \`/bro file <path>\` — explain a workspace \`.md\`, \`.markdown\`, \`.txt\`, \`.pdf\`, or \`.docx\` file
 - \`/bro url <url>\` — explain one public webpage
 - \`/bro <input>\` — a lone URL, an existing supported file, or anything else as pasted text
-- \`/bro open\` — reopen the latest explanation without a new request
+- Inside Simplify: \`/simplify\`, \`/text <text>\`, \`/file <path>\`, \`/url <url>\`, \`/copy\`, \`/clear\`, \`/help\`. **M** changes the mode and re-explains; **R** retries. One source at a time, no chat thread.\n- \`/bro open\` — legacy last-result view (retained for compatibility)
 - \`/bro show [n-turns] [query]\` — draw recent turns' conversation text as shapes; an optional query steers the focus
 
 ## Guided Review

package/src/simplify-engine.ts

@@ -0,0 +1,37 @@
+/** Pure command parser for the one-source-at-a-time Simplify modal. */
+export type SimplifyAction =
+  | { kind: "latest" | "copy" | "clear" | "help" | "retry" }
+  | { kind: "url" | "text" | "file"; input: string }
+  | { kind: "invalid"; message: string };
+
+export function parseSimplifyAction(input: string): SimplifyAction {
+  const trimmed = input.trim();
+  if (!trimmed) return { kind:"invalid", message:"Enter /simplify, /url, /text, /file, /copy, /clear or /help." };
+  const i=trimmed.indexOf(" ");
+  const cmd=(i<0?trimmed:trimmed.slice(0,i)).toLowerCase();
+  const value=i<0?"":trimmed.slice(i+1).trim();
+  if (["/simplify","/copy","/clear","/help","/retry"].includes(cmd)) {
+    if(value) return {kind:"invalid",message:cmd+" takes no arguments."};
+    return {kind:({"/simplify":"latest","/copy":"copy","/clear":"clear","/help":"help","/retry":"retry"} as Record<string,"latest"|"copy"|"clear"|"help"|"retry">)[cmd]!};
+  }
+  for (const kind of ["url","text","file"] as const) {
+    if(cmd==="/"+kind) return value ? {kind,input:value} : {kind:"invalid",message:"Use /"+kind+" <"+(kind==="url"?"url":kind==="file"?"path":"text")+">."};
+  }
+  return {kind:"invalid",message:"Unknown Simplify command. Use /help. Ordinary chat belongs to /bro btw."};
+}
+
+export const SIMPLIFY_MODAL_HELP = [
+  "## Simplify · Commands",
+  "",
+  "Bro explains one source in plain language. Every new explanation replaces the last one. This is not a chat.",
+  "",
+  "- \`/simplify\` — explain the latest completed assistant reply",
+  "- \`/url <url>\` — explain a public webpage",
+  "- \`/text <text>\` — explain pasted text",
+  "- \`/file <path>\` — explain a workspace document",
+  "- \`/copy\` — copy the current explanation",
+  "- \`/clear\` — clear the explanation and source",
+  "- \`/help\` — show these commands",
+  "",
+  "With an empty composer, **M** changes explanation mode and re-explains the captured source; **R** retries. Both keep the backend configured for Explain. **Esc** closes; /bro simplify reopens this view in the current Pi session.",
+].join("\n");

package/src/simplify-ui.ts

@@ -0,0 +1,156 @@
+/** Source-focused Simplify modal. No chat thread, durable draft or new backend boundary. */
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { stripVTControlCharacters } from "node:util";
+import { copyToClipboard } from "@earendil-works/pi-coding-agent";
+import { matchesKey } from "@earendil-works/pi-tui";
+import { BtwModal } from "./btw.ts";
+import { latestAssistant, simplify, type BroResult } from "./explain-modal.ts";
+import { openBroOverlay } from "./modal-kit.ts";
+import { nextBroMode, type BroMode } from "./prompt.ts";
+import { readSettings } from "./settings.ts";
+import { extractDocumentText, extractWebPage, type BroSource } from "./sources.ts";
+import { hasBroCustomUi } from "./ui-capabilities.ts";
+import { errorMessage, unquote } from "./util.ts";
+import { parseSimplifyAction, SIMPLIFY_MODAL_HELP, type SimplifyAction } from "./simplify-engine.ts";
+
+export type SimplifyState = {
+  result?: BroResult;
+  view?: "result" | "help" | "empty";
+  draft?: string;
+  error?: string;
+};
+export type SimplifyStart =
+  | { kind:"resume" }
+  | { kind:"latest" }
+  | { kind:"text"|"file"|"url"; input:string };
+
+async function resolveSource(ctx: ExtensionCommandContext, request: SimplifyStart | SimplifyAction,
+  signal: AbortSignal, retained?: BroSource): Promise<BroSource> {
+  if (retained) return retained;
+  switch (request.kind) {
+    case "latest": {
+      await ctx.waitForIdle();
+      if (signal.aborted) throw new Error("Cancelled.");
+      const source=latestAssistant(ctx);
+      if (!source) throw new Error("No completed assistant reply to simplify.");
+      return {text:source.text,label:"Latest assistant reply"};
+    }
+    case "text": return {text:request.input,label:"Pasted text"};
+    case "file": return {text:await extractDocumentText(request.input,ctx.cwd,signal),label:unquote(request.input)};
+    case "url": return await extractWebPage(request.input,signal);
+    default: throw new Error("Choose a source with /simplify, /text, /file or /url.");
+  }
+}
+
+/** The state belongs to the parent /bro extension instance and resets on session_start. */
+export async function openSimplifyWorkflow(
+  ctx: ExtensionCommandContext,
+  state: SimplifyState,
+  initial: SimplifyStart,
+): Promise<void> {
+  if (!hasBroCustomUi(ctx)) {
+    if (initial.kind==="resume") { ctx.ui.notify("Simplify's interactive view requires Pi TUI.", "warning"); return; }
+    const controller=new AbortController();
+    const source=await resolveSource(ctx,initial,controller.signal);
+    const result=await simplify(source.text,controller.signal,await readSettings());
+    state.result={source,...result};
+    state.view="result"; state.error=undefined;
+    return;
+  }
+
+  await openBroOverlay<void>(ctx,(tui,theme,_keys,done)=>{
+    let closed=false;
+    let controller:AbortController|undefined;
+    let running=false;
+    const close=()=>{if(closed)return; closed=true;state.draft=modal.getComposerText();controller?.abort();done(undefined);};
+    const modal=new BtwModal(tui,theme,close,submit,()=>{
+      closed=true;state.draft=modal.getComposerText();controller?.abort();
+    },{
+      title:"Bro · simplify",
+      commands:"",
+      inputLabel:"Simplify command",
+      idleHint:"Enter run · M change mode · R retry · /copy · /help · Esc close",
+    });
+    const display=()=>{
+      modal.setCustomMode(state.result?.mode ? state.result.mode+(state.result.preferences ? " · prefs" : "") : "one source · one explanation");
+      modal.setModel(state.result?.model ?? "");
+      if(state.view==="help")modal.setText(SIMPLIFY_MODAL_HELP);
+      else if(state.view==="result"&&state.result)modal.setText((state.result.source.label ? "**Source:** "+stripVTControlCharacters(state.result.source.label).replace(/[\r\n]/g," ")+"\n\n---\n\n" : "")+state.result.text);
+      else modal.setText("## Simplify\n\nUse /simplify for the latest reply, /text, /file or /url for another source. Type /help for all commands.");
+      // Notices describe the currently shown state, not an earlier request.
+      modal.setNotice(state.error ?? "",state.error ? "error" : "info");
+      modal.scrollToEnd();
+    };
+    const run=async (request:SimplifyStart|SimplifyAction, retained?:BroSource, mode?:BroMode, submitted?:string)=>{
+      if(running||closed)return;
+      const attempt=new AbortController();
+      controller=attempt; running=true;
+      modal.setRunning(true);modal.setNotice("Simplifying…");
+      const previous=state.result,previousView=state.view;
+      try {
+        const source=await resolveSource(ctx,request,attempt.signal,retained);
+        if(closed||attempt.signal.aborted)return;
+        const currentSettings=await readSettings();
+        const result=await simplify(source.text,attempt.signal,currentSettings,text=>{
+          if(!closed&&!attempt.signal.aborted)modal.setText(text);
+        },mode);
+        if(closed||attempt.signal.aborted)return;
+        state.result={source,...result};
+        state.view="result";state.error=undefined;
+        display();
+        if(mode && mode !== currentSettings.mode)modal.setNotice("Mode: "+mode+" (not saved)");
+      } catch(error){
+        if(closed||attempt.signal.aborted)return;
+        state.result=previous;state.view=previousView;
+        state.error=errorMessage(error);
+        display();
+        // Failed replacement is editable and retryable. Do not overwrite text the user
+        // entered while this request was running. Preserve it on modal close as well.
+        if(submitted && !modal.getComposerText().trim()) {
+          modal.setComposerText(submitted);
+          state.draft=submitted;
+        }
+      } finally {
+        if(controller===attempt)controller=undefined;
+        running=false;
+        if(!closed)modal.setRunning(false);
+      }
+    };
+    const retry=(switchMode=false)=>{
+      if(running||!state.result)return;
+      const next=switchMode?nextBroMode(state.result.mode??"balanced"):state.result.mode;
+      void run({kind:"latest"},state.result.source,next);
+    };
+    const copy=()=>{
+      if(!state.result?.text){modal.setNotice("Nothing to copy yet.","warning");return;}
+      void copyToClipboard(state.result.text)
+        .then(()=>{if(!closed)modal.setNotice("Explanation copied.","success");})
+        .catch(error=>{if(!closed)modal.setNotice("Copy failed: "+errorMessage(error),"error");});
+    };
+    function submit(raw:string):void {
+      if(running||closed)return;
+      const action=parseSimplifyAction(raw);
+      if(action.kind==="invalid"){modal.setNotice(action.message,"warning");return;}
+      modal.clearComposer();state.draft=undefined;
+      if(action.kind==="copy"){copy();return;}
+      if(action.kind==="clear"){
+        state.result=undefined;state.view="empty";state.error=undefined;display();return;
+      }
+      if(action.kind==="help"){state.view="help";state.error=undefined;display();return;}
+      if(action.kind==="retry"){retry();return;}
+      void run(action,undefined,undefined,raw);
+    }
+    modal.onKey=(data:string)=>{
+      if(running||modal.getComposerText().trim())return false;
+      if(matchesKey(data,"m")||matchesKey(data,"shift+m")){retry(true);return Boolean(state.result);}
+      if(matchesKey(data,"r")||matchesKey(data,"shift+r")){retry();return Boolean(state.result);}
+      if(matchesKey(data,"c")||matchesKey(data,"shift+c")){copy();return true;}
+      return false;
+    };
+    display();
+    if(state.draft)modal.setComposerText(state.draft);
+    if(initial.kind!=="resume")queueMicrotask(()=>{if(!closed)void run(initial,undefined,undefined,
+      initial.kind==="latest" ? "/simplify" : "/"+initial.kind+" "+initial.input);});
+    return modal;
+  },{mouse:true});
+}