pi-background 0.1.1 → 0.2.1

package/README.md

@@ -14,11 +14,22 @@ pi install npm:pi-background
 ## Features
 
 - 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`.
 - 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.
 - 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.
 
 You don't need to do anything differently: pi decides when a job belongs in the background. You can also ask for it, for example "run the tests in the background and tell me when they're done".
 
+## Settings
+
+The running jobs line has three levels. Set one in `~/.pi/agent/settings.json`, for example `"background": { "jobs": "compact" }`.
+
+| `jobs` | What it shows |
+| --- | --- |
+| `full` (default) | `⏵ bg1 python3 train.py · 4m12s · epoch 3/10 loss 0.41` |
+| `compact` | `⏵ bg1 python3 train.py · 4m12s` |
+| `off` | Nothing |
+
 ## Tools
 
 pi gets three tools for this: `bg_run` starts a job, `bg_status` shows how it's doing and its latest output, and `bg_kill` stops it. Jobs run with the same environment and sandbox as pi's own shell commands, and stop when you close pi.

package/extensions/background.ts

@@ -1,8 +1,8 @@
 import { createWriteStream, mkdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { createLocalBashOperations, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import { createLocalBashOperations, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 const TAIL_LINES = 20;
@@ -11,6 +11,7 @@ const BASH_DEFAULT_TIMEOUT = 120;
 const BASH_MAX_TIMEOUT = 600;
 const WAKE_DEBOUNCE_MS = 1000;
 const MAX_WAKES = 10;
+const MAX_SHOWN_JOBS = 3;
 
 interface Job {
 	id: string;
@@ -21,6 +22,8 @@ interface Job {
 	status: "running" | "exited" | "killed" | "failed";
 	exitCode?: number | null;
 	ended?: number;
+	// The latest output line, shown while the job runs
+	lastLine?: string;
 }
 
 function tail(path: string, lines: number): string {
@@ -42,6 +45,14 @@ function summary(job: Job): string {
 	return `${job.id} [${state}, ${elapsed(job)}] ${job.command}\n  log: ${job.log}`;
 }
 
+/** The part of a command worth showing: its first line, without a leading cd and with a script path shortened to its name. */
+function shownCommand(command: string): string {
+	return command
+		.split("\n")[0]
+		.replace(/^\s*(cd\s+("[^"]*"|'[^']*'|\S+)\s*(&&|;)\s*)+/, "")
+		.replace(/^\S*\/(?=[^\s/]+(\s|$))/, "");
+}
+
 /** True when a command starts a job with a bare & (not &&, 2>&1, &> or |&). */
 function startsBackgroundJob(command: string): boolean {
 	return /&/.test(command.replace(/&&|[0-9]*>&[0-9-]*|&>>?|\|&/g, ""));
@@ -101,6 +112,36 @@ 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");
+	// "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";
+	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;
+				},
+			};
+		});
+	};
+
 	const find = (id: string): Job => {
 		const job = jobs.get(id);
 		if (!job) throw new Error(`No background job ${id}; known: ${[...jobs.keys()].join(", ") || "none"}`);
@@ -140,6 +181,7 @@ export default function (pi: ExtensionAPI) {
 			"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.",
+			"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.",
 			"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.",
@@ -171,9 +213,13 @@ 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);
+				if (last) job.lastLine = last;
 			};
 
-			ops.exec(params.command, params.cwd ?? ctx.cwd, { onData, signal: job.controller.signal })
+			// Output goes to a pipe, where Python would buffer prints until it exits; unbuffered, the latest line and wake_on stay live
+			ops.exec(`export PYTHONUNBUFFERED=1; ${params.command}`, params.cwd ?? ctx.cwd, { onData, signal: job.controller.signal })
 				.then(({ exitCode }) => {
 					job.status = "exited";
 					job.exitCode = exitCode;
@@ -184,6 +230,7 @@ export default function (pi: ExtensionAPI) {
 				})
 				.finally(() => {
 					job.ended = Date.now();
+					showJobs();
 					out.end(() => {
 						// A kill from session shutdown has no session left to notify
 						if (job.status === "killed" && !jobs.has(id)) return;
@@ -195,6 +242,8 @@ 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 } };
 		},
 	});

package/package.json

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