pi-background 0.2.1 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-background
 
-Lets [pi](https://pi.dev) run long commands in the background instead of waiting on them. pi starts the job, carries on or hands back to you, and gets a message when the job finishes or prints something it's waiting for.
+Lets [Pi](https://pi.dev) run long commands in the background instead of waiting on them. Pi starts the job, carries on or hands back to you, and gets a message when the job finishes or prints something it's waiting for.
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Pringled/pi-extensions/main/assets/images/pi-background-dark.gif">
@@ -13,12 +13,13 @@ 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.
+- 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.
+- 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.
 
-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".
+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
 
@@ -32,7 +33,7 @@ The running jobs line has three levels. Set one in `~/.pi/agent/settings.json`,
 
 ## 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.
+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.
 
 ## License
 

package/extensions/background.ts

@@ -12,6 +12,8 @@ const BASH_MAX_TIMEOUT = 600;
 const WAKE_DEBOUNCE_MS = 1000;
 const MAX_WAKES = 10;
 const MAX_SHOWN_JOBS = 3;
+// How long finished results wait for jobs started alongside them before Pi is woken anyway
+const GROUP_HOLD_MS = 2 * 60_000;
 
 interface Job {
 	id: string;
@@ -24,6 +26,10 @@ interface Job {
 	ended?: number;
 	// The latest output line, shown while the job runs
 	lastLine?: string;
+	// The turn that started the job; jobs from the same turn are reported together
+	group: number;
+	// Started with wake_on, so it may run indefinitely and doesn't hold back the others
+	watched: boolean;
 }
 
 function tail(path: string, lines: number): string {
@@ -79,8 +85,40 @@ export default function (pi: ExtensionAPI) {
 	const ops = createLocalBashOperations();
 	let next = 1;
 
-	const wake = (content: string, details: { headline: string; last: string; error: boolean }) =>
-		pi.sendMessage({ customType: "background-job", content, display: true, details }, { triggerTurn: true, deliverAs: "followUp" });
+	const wake = (content: string, details: { headline: string; last: string; error: boolean }, triggerTurn = true) =>
+		pi.sendMessage({ customType: "background-job", content, display: true, details }, { triggerTurn, deliverAs: "followUp" });
+
+	// Jobs started in the same turn usually belong together, like several benchmarks to compare. While some of them
+	// still run, a successful one's result is added to the conversation without waking Pi, so it answers once at the
+	// end instead of after each job. A job that runs on too long doesn't hold the others back for more than GROUP_HOLD_MS.
+	let turn = 0;
+	pi.on("turn_start", async () => {
+		turn++;
+	});
+	const holds = new Map<number, NodeJS.Timeout>();
+	const runningInGroup = (job: Job) =>
+		[...jobs.values()].filter((other) => other !== job && other.group === job.group && other.status === "running" && !other.watched);
+	const report = (job: Job, content: string, details: { headline: string; last: string; error: boolean }) => {
+		const others = job.watched ? [] : runningInGroup(job);
+		// A failure wakes Pi straight away, so it can react before the rest of the group finishes
+		if (others.length === 0 || details.error) {
+			clearTimeout(holds.get(job.group));
+			holds.delete(job.group);
+			return wake(content, details);
+		}
+		wake(`${content}\n(Still running from the same turn: ${others.map((other) => other.id).join(", ")}; you'll be woken when they finish.)`, details, false);
+		if (holds.has(job.group)) return;
+		holds.set(job.group, setTimeout(() => {
+			holds.delete(job.group);
+			const still = runningInGroup(job);
+			if (still.length === 0) return;
+			wake(`Background jobs from the same turn are still running after ${GROUP_HOLD_MS / 60_000} minutes: ${still.map((other) => other.id).join(", ")}. The results of the ones that finished are above; you'll get a message when each of these finishes.`, {
+				headline: `${still.map((other) => other.id).join(", ")} still running`,
+				last: "",
+				error: false,
+			});
+		}, GROUP_HOLD_MS));
+	};
 
 	// Wakes the agent with output lines matching pattern, batched per second and capped per job
 	const watcher = (job: Job, pattern: RegExp) => {
@@ -182,11 +220,14 @@ export default function (pi: ExtensionAPI) {
 			"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.",
+			"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.",
 		],
+		// Runs after the edits in the same reply, so the job starts from the code pi just wrote
+		executionMode: "sequential",
 		renderShell: "self",
 		renderCall: (args: any, theme, context) => row(theme, `Background $ ${String(args?.command ?? "").split("\n")[0]}`, context),
 		renderResult: (result, { expanded }, theme) => note(theme, result, expanded),
@@ -206,7 +247,7 @@ export default function (pi: ExtensionAPI) {
 			mkdirSync(dir, { recursive: true });
 			const log = join(dir, `${process.pid}-${id}.log`);
 			const out = createWriteStream(log);
-			const job: Job = { id, command: params.command, log, started: Date.now(), controller: new AbortController(), status: "running" };
+			const job: Job = { id, command: params.command, log, started: Date.now(), controller: new AbortController(), status: "running", group: turn, watched: Boolean(pattern) };
 			jobs.set(id, job);
 
 			const watch = pattern ? watcher(job, pattern) : undefined;
@@ -234,7 +275,7 @@ export default function (pi: ExtensionAPI) {
 					out.end(() => {
 						// A kill from session shutdown has no session left to notify
 						if (job.status === "killed" && !jobs.has(id)) return;
-						wake(`Background job finished: ${summary(job)}\nLast lines:\n${tail(log, TAIL_LINES)}`, {
+						report(job, `Background job finished: ${summary(job)}\nLast lines:\n${tail(log, TAIL_LINES)}`, {
 							headline: `${id} ${job.status === "exited" ? `exited ${job.exitCode}` : job.status} · ${elapsed(job)}`,
 							last: tail(log, 1),
 							error: job.status !== "exited" || job.exitCode !== 0,
@@ -286,6 +327,8 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	pi.on("session_shutdown", async () => {
+		for (const timer of holds.values()) clearTimeout(timer);
+		holds.clear();
 		for (const job of jobs.values()) {
 			if (job.status === "running") job.controller.abort();
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-background",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "license": "MIT",
   "author": "Thomas van Dongen",
   "type": "module",
@@ -13,7 +13,7 @@
     "README.md",
     "LICENSE"
   ],
-  "description": "Lets pi run long commands in the background and wakes it when they finish, so it never blocks or hangs",
+  "description": "Lets Pi run long commands in the background and wakes it when they finish, so it never blocks or hangs",
   "keywords": [
     "pi-package",
     "pi",