pi-background 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas van Dongen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# pi-background
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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">
+  <img src="https://raw.githubusercontent.com/Pringled/pi-extensions/main/assets/images/pi-background-light.gif" alt="pi-background demo">
+</picture>
+
+```bash
+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.
+- 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".
+
+## 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.
+
+## License
+
+MIT

package/extensions/background.ts

@@ -0,0 +1,245 @@
+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 { Type } from "typebox";
+
+const TAIL_LINES = 20;
+const TAIL_BYTES = 64 * 1024;
+const BASH_DEFAULT_TIMEOUT = 120;
+const BASH_MAX_TIMEOUT = 600;
+const WAKE_DEBOUNCE_MS = 1000;
+const MAX_WAKES = 10;
+
+interface Job {
+	id: string;
+	command: string;
+	log: string;
+	started: number;
+	controller: AbortController;
+	status: "running" | "exited" | "killed" | "failed";
+	exitCode?: number | null;
+	ended?: number;
+}
+
+function tail(path: string, lines: number): string {
+	try {
+		const text = readFileSync(path).subarray(-TAIL_BYTES).toString("utf8");
+		return text.trimEnd().split("\n").slice(-lines).join("\n") || "(no output)";
+	} catch {
+		return "(no output)";
+	}
+}
+
+function elapsed(job: Job): string {
+	const s = Math.round(((job.ended ?? Date.now()) - job.started) / 1000);
+	return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m${s % 60}s`;
+}
+
+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}`;
+}
+
+/** 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, ""));
+}
+
+/** Compiles wake_on, accepting Python's (?i) prefix that models often write but JavaScript only takes as a flag. */
+function wakePattern(source: string): RegExp {
+	const insensitive = source.startsWith("(?i)");
+	return new RegExp(insensitive ? source.slice(4) : source, insensitive ? "i" : "");
+}
+
+export default function (pi: ExtensionAPI) {
+	// Pi's bash has no default timeout, so a stuck or polling command blocks until interrupted; cap it like Claude Code
+	// does. A timeout SIGKILLs the command's whole process group, which would include jobs it started with &, so a
+	// command that backgrounds something is never timed out, even if the model asked for a timeout.
+	pi.on("tool_call", async (event) => {
+		if (event.toolName !== "bash") return;
+		const input = event.input as { command?: string; timeout?: number };
+		if (startsBackgroundJob(String(input.command ?? ""))) delete input.timeout;
+		else input.timeout = Math.min(input.timeout ?? BASH_DEFAULT_TIMEOUT, BASH_MAX_TIMEOUT);
+	});
+
+	const jobs = new Map<string, Job>();
+	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" });
+
+	// Wakes the agent with output lines matching pattern, batched per second and capped per job
+	const watcher = (job: Job, pattern: RegExp) => {
+		let partial = "";
+		let pending: string[] = [];
+		let timer: NodeJS.Timeout | undefined;
+		let wakes = 0;
+		const flush = () => {
+			timer = undefined;
+			// Once the job has ended, its final message carries the log tail instead
+			if (job.status !== "running") return;
+			wakes++;
+			const capped = wakes === MAX_WAKES ? `\n(Reached ${MAX_WAKES} wake-ups; further matches are ignored, use bg_status to check.)` : "";
+			wake(`Background job ${job.id} output matched /${pattern.source}/ (still running):\n${pending.slice(-TAIL_LINES).join("\n")}${capped}`, {
+				headline: `${job.id} matched /${pattern.source}/`,
+				last: pending[pending.length - 1] ?? "",
+				error: false,
+			});
+			pending = [];
+		};
+		return (data: Buffer) => {
+			if (wakes >= MAX_WAKES) return;
+			const lines = (partial + data.toString("utf8")).split(/\r?\n|\r/);
+			partial = lines.pop() ?? "";
+			const hits = lines.filter((line) => pattern.test(line));
+			if (hits.length === 0) return;
+			pending.push(...hits);
+			timer ??= setTimeout(flush, WAKE_DEBOUNCE_MS);
+		};
+	};
+
+	const find = (id: string): Job => {
+		const job = jobs.get(id);
+		if (!job) throw new Error(`No background job ${id}; known: ${[...jobs.keys()].join(", ") || "none"}`);
+		return job;
+	};
+
+	// Compact, Claude-Code-style rows instead of pi's default boxed tool and message rendering
+	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 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 note = (theme: any, result: any, expanded: boolean) => {
+		const text = result.content?.map((c: any) => c.text ?? "").join("\n") ?? "";
+		// Collapsed: first sentence only ("Started bg1"), without the log path
+		const short = text.split("\n")[0].split(";")[0];
+		return new Text(theme.fg("dim", `  └ ${(expanded ? text : short).replace(/\n/g, "\n    ")}`), 0, 0);
+	};
+
+	pi.registerTool({
+		name: "bg_run",
+		label: "Background",
+		description:
+			"Start a shell command in the background and return immediately with a job id. Output goes to a log file. " +
+			"When the command exits you automatically receive a message with its exit code and the last log lines, so do not poll or sleep waiting for it.",
+		promptSnippet: "Run long shell commands (downloads, builds, long test suites) in the background",
+		promptGuidelines: [
+			"Use bg_run instead of bash for any command that may take longer than about 30 seconds, in particular: downloading large files, datasets, dumps or model weights; " +
+				"installing heavy packages (torch, tensorflow, CUDA libraries, transformers, large requirement sets) or creating environments with them; cloning large repositories; " +
+				"builds, compiles and docker builds; full test suites of non-trivial projects; training, evaluation, benchmark and data-processing scripts; and anything that sleeps, waits or polls.",
+			"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.",
+			"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.",
+		],
+		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),
+		parameters: Type.Object({
+			command: Type.String({ description: "Shell command to run" }),
+			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.",
+				}),
+			),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const pattern = params.wake_on ? wakePattern(params.wake_on) : undefined;
+			const id = `bg${next++}`;
+			const dir = join(tmpdir(), "pi-bg");
+			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" };
+			jobs.set(id, job);
+
+			const watch = pattern ? watcher(job, pattern) : undefined;
+			const onData = (d: Buffer) => {
+				out.write(d);
+				watch?.(d);
+			};
+
+			ops.exec(params.command, params.cwd ?? ctx.cwd, { onData, signal: job.controller.signal })
+				.then(({ exitCode }) => {
+					job.status = "exited";
+					job.exitCode = exitCode;
+				})
+				.catch((err: Error) => {
+					job.status = job.controller.signal.aborted ? "killed" : "failed";
+					out.write(`\n[bg] ${err.message}\n`);
+				})
+				.finally(() => {
+					job.ended = Date.now();
+					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)}`, {
+							headline: `${id} ${job.status === "exited" ? `exited ${job.exitCode}` : job.status} · ${elapsed(job)}`,
+							last: tail(log, 1),
+							error: job.status !== "exited" || job.exitCode !== 0,
+						});
+					});
+				});
+
+			return { content: [{ type: "text", text: `Started ${id}; log: ${log}. You will be notified when it exits.` }], details: { id, log } };
+		},
+	});
+
+	pi.registerTool({
+		name: "bg_status",
+		label: "Background status",
+		description: "List background jobs, or show one job's state and the tail of its log.",
+		renderShell: "self",
+		renderCall: (args: any, theme, context) => row(theme, `Background status ${args?.id ?? "(all)"}`, context),
+		renderResult: (result, { expanded }, theme) => note(theme, result, expanded),
+		parameters: Type.Object({
+			id: Type.Optional(Type.String({ description: "Job id such as bg1; omit to list all jobs" })),
+			lines: Type.Optional(Type.Number({ description: `Log lines to show (default ${TAIL_LINES})` })),
+		}),
+		async execute(_toolCallId, params) {
+			if (!params.id) {
+				const text = [...jobs.values()].map(summary).join("\n") || "No background jobs.";
+				return { content: [{ type: "text", text }], details: {} };
+			}
+			const job = find(params.id);
+			return { content: [{ type: "text", text: `${summary(job)}\n${tail(job.log, params.lines ?? TAIL_LINES)}` }], details: {} };
+		},
+	});
+
+	pi.registerTool({
+		name: "bg_kill",
+		label: "Background kill",
+		description: "Stop a running background job and its child processes.",
+		renderShell: "self",
+		renderCall: (args: any, theme, context) => row(theme, `Background kill ${args?.id ?? ""}`, context),
+		renderResult: (result, { expanded }, theme) => note(theme, result, expanded),
+		parameters: Type.Object({ id: Type.String({ description: "Job id such as bg1" }) }),
+		async execute(_toolCallId, params) {
+			const job = find(params.id);
+			if (job.status !== "running") return { content: [{ type: "text", text: `${job.id} already ${job.status}` }], details: {} };
+			job.controller.abort();
+			return { content: [{ type: "text", text: `Stopping ${job.id}` }], details: {} };
+		},
+	});
+
+	pi.on("session_shutdown", async () => {
+		for (const job of jobs.values()) {
+			if (job.status === "running") job.controller.abort();
+		}
+		jobs.clear();
+	});
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "pi-background",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "MIT",
+  "author": "Thomas van Dongen",
+  "type": "module",
+  "homepage": "https://github.com/pringled/pi-extensions/tree/main/packages/pi-background#readme",
+  "bugs": {
+    "url": "https://github.com/pringled/pi-extensions/issues"
+  },
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "description": "Background jobs for pi that wake the agent when they finish or print what it waits for, plus a bash timeout that never kills background work, so pi doesn't hang on a command",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "background",
+    "jobs",
+    "timeout"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pringled/pi-extensions.git",
+    "directory": "packages/pi-background"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/background.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/Pringled/pi-extensions/main/assets/images/pi-background-dark.gif"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  }
+}