pi-background 0.3.0 → 0.3.2

package/README.md

@@ -15,6 +15,7 @@ pi install npm:pi-background
 
 - Long commands like downloads, builds, test suites and training runs go to the background, and Pi hears back with the exit code and the end of the output when they finish.
 - While a job runs, a line above the input shows it with its elapsed time and latest output, such as `⏵ bg1 python3 train.py · 4m12s · epoch 3/10 loss 0.41`.
+- `/bg` shows a job's last 20 lines of output, updating while it runs (`/bg bg2` for a specific job). Press esc to close it.
 - Pi can wait for a specific line, such as a dev server's `listening on` or a training run's `epoch 3`, without checking again and again.
 - Jobs started together are reported together: when Pi starts several jobs at once, such as benchmarks to compare, it's woken once when the last one finishes instead of after each. You can keep chatting meanwhile, and a job that runs much longer doesn't hold the others back for more than 2 minutes.
 - Regular commands time out after 2 minutes, unless Pi asks for longer (up to 10), so Pi never hangs on a stuck command. Commands that start their own background process with `&` are left alone.

package/extensions/background.ts

@@ -1,8 +1,8 @@
 import { createWriteStream, mkdirSync, readFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
-import { createLocalBashOperations, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import { createLocalBashOperations, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, stripTerminalSequences, Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 const TAIL_LINES = 20;
@@ -46,17 +46,27 @@ function elapsed(job: Job): string {
 	return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m${s % 60}s`;
 }
 
+function state(job: Job): string {
+	return job.status === "exited" ? `exit ${job.exitCode}` : job.status;
+}
+
 function summary(job: Job): string {
-	const state = job.status === "exited" ? `exit ${job.exitCode}` : job.status;
-	return `${job.id} [${state}, ${elapsed(job)}] ${job.command}\n  log: ${job.log}`;
+	return `${job.id} [${state(job)}, ${elapsed(job)}] ${job.command}\n  log: ${job.log}`;
+}
+
+/** An output line as a terminal would last have shown it: without escape codes or control characters, and a progress bar redrawn with \r in its latest state only. */
+function cleanLine(line: string): string {
+	const shown = stripTerminalSequences(line).split("\r").filter((part) => part.trim()).at(-1) ?? "";
+	return shown.replace(/\t/g, "  ").replace(/[\x00-\x08\x0b-\x1f\x7f]/g, "").trimEnd();
 }
 
-/** The part of a command worth showing: its first line, without a leading cd and with a script path shortened to its name. */
+/** The part of a command worth showing: its first line, without a leading cd, with a script path shortened to its name and at most 50 characters. */
 function shownCommand(command: string): string {
-	return command
+	const shown = command
 		.split("\n")[0]
 		.replace(/^\s*(cd\s+("[^"]*"|'[^']*'|\S+)\s*(&&|;)\s*)+/, "")
 		.replace(/^\S*\/(?=[^\s/]+(\s|$))/, "");
+	return shown.length > 50 ? `${shown.slice(0, 49)}…` : shown;
 }
 
 /** True when a command starts a job with a bare & (not &&, 2>&1, &> or |&). */
@@ -151,34 +161,40 @@ export default function (pi: ExtensionAPI) {
 	};
 
 	// One line per running job above the input, with its elapsed time and latest output
-	let ui: ExtensionContext["ui"] | undefined;
 	const running = () => [...jobs.values()].filter((job) => job.status === "running");
+	// The job open in /bg, left out of the jobs line meanwhile so it isn't shown twice
+	let viewing: Job | undefined;
 	// "full" (the default), "compact" without the output, or "off", set with "background": { "jobs": ... } in pi's settings.json
 	const jobsLine = () => (pi.getSettings() as { background?: { jobs?: string } }).background?.jobs ?? "full";
+	// The widget is set once per session and redrawn in place: setting it again would move it below the widgets other
+	// extensions added since, while running jobs belong at the top, next to what Pi is doing now
+	let redrawJobs = () => {};
+	let ticker: NodeJS.Timeout | undefined;
 	const showJobs = () => {
-		if (!ui) return;
-		if (jobsLine() === "off" || running().length === 0) return ui.setWidget("background-jobs", undefined);
-		ui.setWidget("background-jobs", (tui, theme) => {
-			const timer = setInterval(() => tui.requestRender(), 1000);
-			return {
-				dispose: () => clearInterval(timer),
-				invalidate() {},
-				render(width: number) {
-					const live = running();
-					const lines = live.slice(0, MAX_SHOWN_JOBS).map((job) => {
-						const command = shownCommand(job.command);
-						const text =
-							theme.fg("accent", " ⏵ ") +
-							theme.fg("toolTitle", `${job.id} ${command.length > 50 ? `${command.slice(0, 49)}…` : command}`) +
-							theme.fg("dim", ` · ${elapsed(job)}${jobsLine() === "full" && job.lastLine ? ` · ${job.lastLine}` : ""}`);
-						return truncateToWidth(text, width);
-					});
-					if (live.length > MAX_SHOWN_JOBS) lines.push(theme.fg("dim", `   and ${live.length - MAX_SHOWN_JOBS} more`));
-					return lines;
-				},
-			};
-		});
+		// A running job's elapsed time and latest output change every second
+		if (running().length > 0) ticker ??= setInterval(() => redrawJobs(), 1000);
+		else {
+			clearInterval(ticker);
+			ticker = undefined;
+		}
+		redrawJobs();
 	};
+	const jobsWidget = (theme: any) => ({
+		invalidate() {},
+		render(width: number) {
+			if (jobsLine() === "off") return [];
+			const live = running().filter((job) => job !== viewing);
+			const lines = live.slice(0, MAX_SHOWN_JOBS).map((job) => {
+				const text =
+					theme.fg("accent", "⏵ ") +
+					theme.fg("toolTitle", `${job.id} ${shownCommand(job.command)}`) +
+					theme.fg("dim", ` · ${elapsed(job)}${jobsLine() === "full" && job.lastLine ? ` · ${job.lastLine}` : ""}`);
+				return truncateToWidth(text, width);
+			});
+			if (live.length > MAX_SHOWN_JOBS) lines.push(theme.fg("dim", `  and ${live.length - MAX_SHOWN_JOBS} more`));
+			return lines;
+		},
+	});
 
 	const find = (id: string): Job => {
 		const job = jobs.get(id);
@@ -186,16 +202,18 @@ export default function (pi: ExtensionAPI) {
 		return job;
 	};
 
-	// Compact, Claude-Code-style rows instead of pi's default boxed tool and message rendering
+	// Compact, Claude-Code-style rows instead of pi's default boxed tool and message rendering: quiet grey once done,
+	// with a dot only while running or when something failed
 	pi.registerMessageRenderer("background-job", (message, { expanded }, theme) => {
 		const d = (message.details ?? {}) as { headline?: string; last?: string; error?: boolean };
-		const head = theme.fg(d.error ? "error" : "success", "● ") + theme.fg("toolTitle", `Background ${d.headline ?? ""}`);
+		const title = `Background ${d.headline ?? ""}`;
+		const head = d.error ? theme.fg("error", "● ") + theme.fg("toolTitle", title) : `  ${theme.fg("dim", title)}`;
 		const body = expanded ? String(message.content) : (d.last ?? "");
 		return new Text(`${head}\n${theme.fg("dim", `  └ ${body.replace(/\n/g, "\n    ")}`)}`, 0, 0);
 	});
 	const row = (theme: any, text: string, context: any) => {
-		const color = context.isError ? "error" : context.executionStarted && context.isPartial ? "accent" : "success";
-		return new Text(theme.fg(color, "● ") + theme.fg("toolTitle", text), 0, 0);
+		const color = context.isError ? "error" : context.executionStarted && context.isPartial ? "accent" : undefined;
+		return new Text(color ? theme.fg(color, "● ") + theme.fg("toolTitle", text) : `  ${theme.fg("dim", text)}`, 0, 0);
 	};
 	const note = (theme: any, result: any, expanded: boolean) => {
 		const text = result.content?.map((c: any) => c.text ?? "").join("\n") ?? "";
@@ -218,13 +236,13 @@ export default function (pi: ExtensionAPI) {
 			"When unsure whether a command is quick, prefer bg_run: a quick job just reports back sooner, while a long bash command blocks the user until it finishes.",
 			"After bg_run, continue with independent work or end your turn; a message with the exit code and log tail arrives automatically when the job exits, so never sleep, poll or tail the log to wait for it.",
 			"Keep using bash for quick commands whose output you need right away, such as git, ls, cat, grep, find, file inspection and short checks.",
-			"To react when a bg_run job prints something specific while it keeps running (a server is ready, an epoch finished, an error appeared), pass wake_on with a regex instead of polling.",
+			"Pass wake_on only when you must act before a bg_run job ends, such as a server becoming ready to test against, or when the user asked to follow its progress. To report a job's result, leave wake_on out: the exit message already brings the exit code and last lines, so waking on every epoch or step only adds turns.",
 			"Don't redirect a bg_run command's output to a file (> file, 2>&1, nohup): bg_run already saves all of it to the job's log, and redirecting hides the job's progress from the user and from wake_on. If the output should be kept, tell the user where the job's log is.",
 			"bg_run starts only after the other tool calls in the same reply have finished, so editing a file and starting a job that uses it in one reply is safe.",
 			"Use bg_status to check progress of a bg_run job and bg_kill to stop one.",
 			`bash commands time out after ${BASH_DEFAULT_TIMEOUT / 60} minutes unless you pass timeout (at most ${BASH_MAX_TIMEOUT / 60} minutes); run anything that may take longer with bg_run instead.`,
 			"Unless the user explicitly asks for that bash command, never wait, poll or sleep in bash (while/until loops with sleep, watch, repeated status checks), not even as part of a larger command; start the wait with bg_run and pass wake_on to be woken when the awaited output appears.",
-			"Unless the user explicitly asks otherwise, start long-running processes (training or evaluation runs, servers, watchers) with bg_run, not with & or nohup in bash followed by sleep; pass wake_on matching the lines you want to see, such as results or Traceback.",
+			"Unless the user explicitly asks otherwise, start long-running processes (training or evaluation runs, servers, watchers) with bg_run, not with & or nohup in bash followed by sleep.",
 		],
 		// Runs after the edits in the same reply, so the job starts from the code pi just wrote
 		executionMode: "sequential",
@@ -236,7 +254,7 @@ export default function (pi: ExtensionAPI) {
 			cwd: Type.Optional(Type.String({ description: "Working directory (defaults to the session cwd)" })),
 			wake_on: Type.Optional(
 				Type.String({
-					description: "Regex; also wake you while the job runs whenever an output line matches, e.g. 'listening on|ready' or 'epoch \\d+'. Matches within a second are batched; at most 10 wake-ups per job.",
+					description: "Regex; also wake you while the job runs whenever an output line matches, e.g. 'listening on|ready'. Matches within a second are batched; at most 10 wake-ups per job.",
 				}),
 			),
 		}),
@@ -254,8 +272,7 @@ export default function (pi: ExtensionAPI) {
 			const onData = (d: Buffer) => {
 				out.write(d);
 				watch?.(d);
-				// Progress bars redraw with \r, so the last segment of either kind of line break is the current state
-				const last = d.toString("utf8").replace(/\x1b\[[0-9;?]*[A-Za-z]/g, "").split(/\r\n|\r|\n/).map((line) => line.trim()).filter(Boolean).at(-1);
+				const last = d.toString("utf8").split("\n").map(cleanLine).filter((line) => line.trim()).at(-1)?.trim();
 				if (last) job.lastLine = last;
 			};
 
@@ -283,7 +300,6 @@ export default function (pi: ExtensionAPI) {
 					});
 				});
 
-			if (ctx.mode === "tui") ui = ctx.ui;
 			showJobs();
 			return { content: [{ type: "text", text: `Started ${id}; log: ${log}. You will be notified when it exits.` }], details: { id, log } };
 		},
@@ -326,7 +342,80 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	// Shows a job's latest output in place of the input until esc, refreshed every second while it runs
+	pi.registerCommand("bg", {
+		description: "Show a background job's latest output",
+		getArgumentCompletions: (prefix) => {
+			const matching = [...jobs.values()].filter((job) => job.id.startsWith(prefix.trim().toLowerCase()));
+			return matching.length ? matching.map((job) => ({ value: job.id, label: job.id, description: `${shownCommand(job.command)} · ${state(job)}` })) : null;
+		},
+		handler: async (args, ctx) => {
+			if (!ctx.hasUI) return;
+			const all = [...jobs.values()].reverse();
+			if (all.length === 0) return ctx.ui.notify("No background jobs yet", "info");
+			// "/bg 2" works as well as "/bg bg2"
+			const wanted = args.trim().toLowerCase().replace(/^(\d+)$/, "bg$1");
+			let job = wanted ? jobs.get(wanted) : all.length === 1 ? all[0] : undefined;
+			if (wanted && !job) return ctx.ui.notify(`No background job ${args.trim()}; there's ${[...jobs.keys()].join(", ")}`, "warning");
+			if (!job) {
+				// Matched by position, since the elapsed time in a label changes while the list is open
+				const options = all.map((other) => `${other.id} ${shownCommand(other.command)} · ${state(other)} · ${elapsed(other)}`);
+				job = all[options.indexOf((await ctx.ui.select("Background jobs", options)) ?? "")];
+				if (!job) return;
+			}
+			const shown = job;
+			viewing = shown;
+			const log = shown.log.replace(homedir(), "~");
+			try {
+				await ctx.ui.custom<void>((tui, theme, _kb, done) => {
+					const timer = setInterval(() => tui.requestRender(), 1000);
+					return {
+						dispose: () => clearInterval(timer),
+						invalidate() {},
+						handleInput: (data: string) => {
+							if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c")) || data === "q") done();
+						},
+						render(width: number) {
+							const color = shown.status === "running" ? "accent" : shown.status === "exited" && shown.exitCode === 0 ? "success" : "error";
+							const title = theme.fg(color, " ● ") + theme.fg("toolTitle", `${shown.id} ${shownCommand(shown.command)}`);
+							const status = theme.fg("muted", `${state(shown)} · ${elapsed(shown)} `);
+							const gap = Math.max(1, width - visibleWidth(title) - visibleWidth(status));
+							// At most half the terminal, so the conversation above stays in view
+							const text = tail(shown.log, Math.max(3, Math.min(TAIL_LINES, Math.floor(tui.terminal.rows / 2))));
+							const output = text === "(no output)" ? [theme.fg("dim", theme.italic("   no output yet"))] : text.split("\n").map((line) => `   ${cleanLine(line)}`);
+							return [
+								theme.fg("borderMuted", "─".repeat(width)),
+								title + " ".repeat(gap) + status,
+								...output,
+								theme.fg("dim", ` esc to close · ${log}`),
+								theme.fg("borderMuted", "─".repeat(width)),
+							].map((line) => truncateToWidth(line, width));
+						},
+					};
+				});
+			} finally {
+				viewing = undefined;
+			}
+		},
+	});
+
+	// After /reload or a resume, carry on after the ids already in the conversation so "bg3" keeps meaning one job
+	pi.on("session_start", async (_event, ctx) => {
+		if (ctx.mode === "tui") {
+			ctx.ui.setWidget("background-jobs", (tui, theme) => {
+				redrawJobs = () => tui.requestRender();
+				return jobsWidget(theme);
+			});
+		}
+		for (const entry of ctx.sessionManager.getBranch()) {
+			const msg = entry.type === "message" ? (entry.message as any) : undefined;
+			const n = Number(/^bg(\d+)$/.exec(msg?.role === "toolResult" && msg.toolName === "bg_run" ? String(msg.details?.id) : "")?.[1]);
+			if (n >= next) next = n + 1;
+		}
+	});
+
 	pi.on("session_shutdown", async () => {
+		clearInterval(ticker);
 		for (const timer of holds.values()) clearTimeout(timer);
 		holds.clear();
 		for (const job of jobs.values()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-background",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "license": "MIT",
   "author": "Thomas van Dongen",
   "type": "module",