pi-background-tasks 0.3.0 → 0.4.0

package/PUBLISHING.md

@@ -32,8 +32,8 @@ npm publish --access public
 Pi install smoke after publish:
 
 ```bash
-pi -e npm:pi-background-tasks@0.3.0 --offline --no-tools --no-session -p "/jobs"
-pi install npm:pi-background-tasks@0.3.0
+pi -e npm:pi-background-tasks@0.4.0 --offline --no-tools --no-session -p "/jobs"
+pi install npm:pi-background-tasks@0.4.0
 ```
 
 ## Publish to git
@@ -48,15 +48,15 @@ git commit -m "Release pi-background-tasks"
 git branch -M main
 git remote add origin git@github.com:ismailsaleekh/pi-background-tasks.git
 git push -u origin main
-git tag v0.3.0
-git push origin v0.3.0
+git tag v0.4.0
+git push origin v0.4.0
 ```
 
 Pi install smoke after git tag:
 
 ```bash
-pi -e git:github.com/ismailsaleekh/pi-background-tasks@v0.3.0 --offline --no-tools --no-session -p "/jobs"
-pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.3.0
+pi -e git:github.com/ismailsaleekh/pi-background-tasks@v0.4.0 --offline --no-tools --no-session -p "/jobs"
+pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.4.0
 ```
 
 ## pi.dev/packages

package/README.md

@@ -9,19 +9,19 @@ This package adds named, tracked background shell jobs with durable output files
 From npm after publish:
 
 ```bash
-pi install npm:pi-background-tasks@0.3.0
+pi install npm:pi-background-tasks@0.4.0
 ```
 
 From git after pushing this package to its standalone repository and tagging:
 
 ```bash
-pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.3.0
+pi install git:github.com/ismailsaleekh/pi-background-tasks@v0.4.0
 ```
 
 For project-local install:
 
 ```bash
-pi install -l npm:pi-background-tasks@0.3.0
+pi install -l npm:pi-background-tasks@0.4.0
 ```
 
 ## Commands
@@ -32,6 +32,7 @@ pi install -l npm:pi-background-tasks@0.3.0
 - `/kill <id>` — stop a running task.
 - `/tasks` or `/bg-tasks` — fallback command to open the task manager UI.
 - `/bg-clear` — clear finished background-task footer notices.
+- `/bg-update` — print update instructions when a newer published version exists (instruct-only; never self-installs).
 
 ## Footer dock UX
 
@@ -65,6 +66,19 @@ Dock controls:
 | `R` | Rerun selected command |
 | `c` | Show copyable output path |
 | `x` / `Esc` / `q` | Close dock |
+| `/bg-update` | Print update instructions when a newer version is published |
+
+### Update-available notice
+
+When a newer version of `pi-background-tasks` has been published to npm, the footer appends a compact, instruct-only segment after the entry hint:
+
+```text
+bg 1 running · 1 failed · Shift↓ · /bg-clear · ⬆ v0.5.0 /bg-update
+```
+
+When no tasks are active, the notice still appears on its own (`bg ⬆ v0.5.0 /bg-update`) so the update hint is visible. The segment is rendered only when a strictly newer published version exists; `/bg-update` prints the npm and git update commands and never installs or self-updates.
+
+The lookup runs at most once per session on `session_start`, is time-boxed, and is fully offline-safe: it never blocks or errors the footer/session, and on an offline or failed lookup it simply renders no segment (it never pins a misleading version). The check is skipped entirely when `PI_OFFLINE=1`, and can be disabled explicitly with `PI_BG_DISABLE_UPDATE_CHECK=1`. Set `PI_BG_REGISTRY_URL` to point the check at a registry mirror instead of `https://registry.npmjs.org`.
 
 ## LLM tools
 

package/TESTING.md

@@ -71,7 +71,8 @@ Tests must not use the user's real `~/.pi/agent`.
 Implemented coverage includes:
 
 - tools: `bg_run`, `bg_status`, `bg_logs`, `bg_kill`, including required `isAgent` schema/runtime validation, unknown/ambiguous IDs, completed-kill failure, legacy no-name preparation, head/tail truncation, and notification on/off behavior
-- commands: `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks`, `/bg-clear` discovery, happy paths, `/bg --agent` parsing, finished-notice clearing, malformed `/bg`, unknown/ambiguous IDs, completed-task `/kill`, byte-limit normalization, and RPC no-hang fallback behavior
+- commands: `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks`, `/bg-clear`, `/bg-update` discovery, happy paths, `/bg --agent` parsing, finished-notice clearing, malformed `/bg`, unknown/ambiguous IDs, completed-task `/kill`, byte-limit normalization, and RPC no-hang fallback behavior
+- update-available notice: semver parse/compare/precedence, `formatUpdateSegment`, npm/`package.json` payload narrowing, and injected-fetch success/404/throw/timeout (unit); localhost-registry footer segment (idle + appended to an active footer), `/bg-update` non-installing instructions, and opt-out/offline/already-current/registry-failure no-segment-and-no-throw paths (SDK); `/bg-update` discovery and offline instructions (RPC). The check is one-shot on `session_start`, time-boxed, offline-safe, gated by `PI_OFFLINE`/`PI_BG_DISABLE_UPDATE_CHECK`, and `PI_BG_REGISTRY_URL` overrides the registry endpoint
 - shortcut/UI: component coverage for focused dock list/detail/key handling, empty/history/unread states, paging, close aliases, stop/stop-all/rerun/path actions, missing output files; SDK coverage for explicit `/bg-clear` finished-notice clearing, `/bg-clear` footer hinting, optional `Ctrl+Alt+C` fallback shortcut registration, and mixed failed/stopped/done/focused footer status; RPC coverage that `/bg-clear` works as a terminal-independent clear path; and PTY coverage for `/tasks`, `/bg-tasks`, real `Shift+Down`, arrows, page keys, detail/back/history/stop/stop-all/rerun/path/close, failed unread badges, and running/completed/failed/killed rerun paths
 - runtime files: output and metadata files under `.pi/tasks/`, persisted `isAgent` classification, task-owned context-window telemetry snapshots, cumulative background Pi-agent token usage, tool-use counts, agent model identifier (preferring the fully-qualified `provider/model` form), explicit `isAgent:true` telemetry wrapping for background `pi` agents, `isAgent:false` non-wrapping for scripts, real child `pi --mode json` tool-event parsing, split/large telemetry ingestion, metadata after completion/failure, local tarball install contents
 - safety: kill, already-finished kill failure, timeout failure, spawn failure, low output-cap failure, multi-task shutdown cleanup, process-group kill fallback, Windows child-kill behavior, SIGKILL escalation, duplicate finalization/notification races, metadata/notification failure handling, and pruning

package/TEST_PLAN.md

@@ -12,7 +12,7 @@ This package follows:
 |---|---|
 | Package | `pi-background-tasks` |
 | Extension entrypoint | `extensions/background-tasks.ts` |
-| Public commands | `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks`, `/bg-clear` |
+| Public commands | `/bg`, `/jobs`, `/logs`, `/kill`, `/tasks`, `/bg-tasks`, `/bg-clear`, `/bg-update` |
 | Public tools | `bg_run`, `bg_status`, `bg_logs`, `bg_kill` |
 | Shortcuts | `Shift+Down`; optional fallback `Ctrl+Alt+C` |
 | Custom UI | footer status + focused bottom dock overlay |
@@ -62,6 +62,7 @@ This package follows:
 | Dock close | `x`/`Esc`/`q` |  |  |  | yes | yes |  |  | Component + PTY. |
 | Shortcut opens dock | `Shift+Down` |  | registration |  |  | yes |  |  | PTY sends xterm `ESC [ 1 ; 2 B`. |
 | Clear finished notices | `/bg-clear`, optional `Ctrl+Alt+C` fallback |  | yes | yes |  |  |  |  | `/bg-clear` is the canonical terminal-independent path and is advertised in the footer. SDK invokes the slash-command handler and verifies fallback shortcut registration; RPC verifies `/bg-clear` clears finished notices; finished notices remain until explicit clear. |
+| Update-available footer notice | `⬆ v<latest> /bg-update` footer segment + `/bg-update` command | yes | yes | yes |  |  |  |  | Unit covers semver parse/compare/precedence, `isNewerVersion`, `formatUpdateSegment`, npm/`package.json` payload narrowing, injected-fetch success/404/throw/timeout, and `package.json` read/degrade. SDK uses a localhost registry to verify the idle and append-to-active footer segment, `/bg-update` non-installing instructions, and that opt-out (`PI_BG_DISABLE_UPDATE_CHECK=1`), offline (`PI_OFFLINE=1`), already-current, and registry-failure paths render no segment and never throw. RPC verifies `/bg-update` discovery and offline non-installing instructions. The check is one-shot per `session_start`, time-boxed, offline-safe, and never runs on the status tick. |
 | Runtime output files | `.pi/tasks/...output` | yes | yes |  |  |  |  |  | SDK asserts existence. |
 | Runtime metadata files | `.pi/tasks/...json` | yes | yes |  |  |  |  |  | SDK asserts shape/status/name/context usage; registry unit tests cover metadata failure/update ordering. |
 | Timeout kills task | `timeoutSeconds` |  | yes |  |  |  |  |  | SDK. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-background-tasks",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Claude-Code-like named background shell task manager for Pi: bg_run tools, /bg commands, Shift+Down footer dock, bounded logs, kill/timeout safety, and completion wakeups.",
   "type": "module",
   "license": "ISC",

package/src/core/common.ts

@@ -395,3 +395,75 @@ export async function boundedRead(
 export function escapeXml(value: string): string {
 	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
+
+export const UPDATE_COMMAND = "/bg-update";
+
+type ParsedSemver = {
+	major: number;
+	minor: number;
+	patch: number;
+	prerelease: string[];
+};
+
+const SEMVER_PATTERN = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+export function parseSemver(value: string): ParsedSemver | undefined {
+	if (typeof value !== "string") return undefined;
+	const match = value.trim().match(SEMVER_PATTERN);
+	if (!match) return undefined;
+	const major = Number(match[1]);
+	const minor = Number(match[2]);
+	const patch = Number(match[3]);
+	if (!Number.isInteger(major) || !Number.isInteger(minor) || !Number.isInteger(patch)) return undefined;
+	const prerelease = match[4] ? match[4].split(".") : [];
+	return { major, minor, patch, prerelease };
+}
+
+function comparePrerelease(a: string[], b: string[]): number {
+	if (a.length === 0 && b.length === 0) return 0;
+	// A version without prerelease identifiers outranks the same core with prerelease identifiers.
+	if (a.length === 0) return 1;
+	if (b.length === 0) return -1;
+	const shared = Math.min(a.length, b.length);
+	for (let i = 0; i < shared; i++) {
+		const idA = a[i];
+		const idB = b[i];
+		if (idA === undefined || idB === undefined) break;
+		if (idA === idB) continue;
+		const numericA = /^\d+$/.test(idA);
+		const numericB = /^\d+$/.test(idB);
+		if (numericA && numericB) {
+			const diff = Number(idA) - Number(idB);
+			if (diff !== 0) return diff < 0 ? -1 : 1;
+			continue;
+		}
+		// Numeric identifiers always have lower precedence than non-numeric identifiers.
+		if (numericA) return -1;
+		if (numericB) return 1;
+		return idA < idB ? -1 : 1;
+	}
+	if (a.length === b.length) return 0;
+	return a.length < b.length ? -1 : 1;
+}
+
+/** Compare two semver strings. Returns -1/0/1, or undefined when either side is not valid semver. */
+export function compareSemver(a: string, b: string): number | undefined {
+	const left = parseSemver(a);
+	const right = parseSemver(b);
+	if (!left || !right) return undefined;
+	if (left.major !== right.major) return left.major < right.major ? -1 : 1;
+	if (left.minor !== right.minor) return left.minor < right.minor ? -1 : 1;
+	if (left.patch !== right.patch) return left.patch < right.patch ? -1 : 1;
+	return comparePrerelease(left.prerelease, right.prerelease);
+}
+
+export function isNewerVersion(latest: string, current: string): boolean {
+	return compareSemver(latest, current) === 1;
+}
+
+/** Footer segment shown only when a newer published version exists; undefined otherwise. */
+export function formatUpdateSegment(latest: string | undefined, current: string): string | undefined {
+	if (!latest) return undefined;
+	if (!isNewerVersion(latest, current)) return undefined;
+	return `\u2b06 v${latest} ${UPDATE_COMMAND}`;
+}

package/src/core/update-check.ts

@@ -0,0 +1,99 @@
+import { readFileSync } from "node:fs";
+
+/**
+ * Typed, offline-safe boundary for the "update available" footer notice.
+ *
+ * All network access flows through an injectable {@link FetchLike} so unit tests
+ * never touch the real npm registry. Every failure path (offline, timeout, bad
+ * status, malformed payload) resolves to `undefined` and never throws, so the
+ * footer/session can never hang or error because of an update check.
+ */
+
+export const DEFAULT_NPM_REGISTRY_URL = "https://registry.npmjs.org";
+export const DEFAULT_UPDATE_TIMEOUT_MS = 2000;
+
+export type FetchResponseLike = {
+	readonly ok: boolean;
+	readonly status: number;
+	json(): Promise<unknown>;
+};
+
+export type FetchLike = (url: string, init: { signal: AbortSignal }) => Promise<FetchResponseLike>;
+
+export type FetchLatestVersionOptions = {
+	packageName: string;
+	registryUrl?: string;
+	timeoutMs?: number;
+	fetchImpl?: FetchLike;
+	onError?: (error: Error) => void;
+};
+
+export type PackageInfo = {
+	name?: string;
+	version?: string;
+};
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+	if (typeof value !== "object" || value === null) return undefined;
+	return value as Record<string, unknown>;
+}
+
+function readNonEmptyString(record: Record<string, unknown>, key: string): string | undefined {
+	const value = record[key];
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : undefined;
+}
+
+/** Narrow an npm registry `<pkg>/latest` JSON payload to its `version` string. */
+export function parseLatestVersionPayload(payload: unknown): string | undefined {
+	const record = asRecord(payload);
+	if (!record) return undefined;
+	return readNonEmptyString(record, "version");
+}
+
+/** Narrow a parsed `package.json` payload to the fields this extension needs. */
+export function parsePackageInfo(payload: unknown): PackageInfo {
+	const record = asRecord(payload);
+	if (!record) return {};
+	const info: PackageInfo = {};
+	const name = readNonEmptyString(record, "name");
+	const version = readNonEmptyString(record, "version");
+	if (name !== undefined) info.name = name;
+	if (version !== undefined) info.version = version;
+	return info;
+}
+
+const realFetch: FetchLike = (url, init) => fetch(url, init);
+
+/** Time-boxed, never-throwing lookup of the latest published version of a package. */
+export async function fetchLatestVersion(options: FetchLatestVersionOptions): Promise<string | undefined> {
+	const registryUrl = (options.registryUrl ?? DEFAULT_NPM_REGISTRY_URL).replace(/\/+$/, "");
+	const timeoutMs = options.timeoutMs ?? DEFAULT_UPDATE_TIMEOUT_MS;
+	const doFetch = options.fetchImpl ?? realFetch;
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const url = `${registryUrl}/${encodeURIComponent(options.packageName)}/latest`;
+		const response = await doFetch(url, { signal: controller.signal });
+		if (!response.ok) return undefined;
+		const payload = await response.json();
+		return parseLatestVersionPayload(payload);
+	} catch (error) {
+		options.onError?.(error instanceof Error ? error : new Error(String(error)));
+		return undefined;
+	} finally {
+		clearTimeout(timer);
+	}
+}
+
+/** Read `name`/`version` from a local `package.json`, returning `{}` on every failure. */
+export function readPackageInfo(packageJsonUrl: URL | string, onError?: (error: Error) => void): PackageInfo {
+	try {
+		const parsed: unknown = JSON.parse(readFileSync(packageJsonUrl, "utf8"));
+		return parsePackageInfo(parsed);
+	} catch (error) {
+		onError?.(error instanceof Error ? error : new Error(String(error)));
+		return {};
+	}
+}

package/src/extension.ts

@@ -7,6 +7,8 @@ import {
 	MAX_LOG_BYTES,
 	deriveTaskNameFromCommand,
 	formatSnapshotList,
+	formatUpdateSegment,
+	isNewerVersion,
 	normalizeMaxBytes,
 	normalizeTaskName,
 	parseBgCommandArgs,
@@ -20,6 +22,7 @@ import {
 	type BgTaskSnapshot,
 	type StartTaskOptions,
 } from "./core/common.js";
+import { fetchLatestVersion, readPackageInfo, type FetchLatestVersionOptions } from "./core/update-check.js";
 import { BackgroundTaskRegistry } from "./core/registry.js";
 import { BackgroundTasksManager, type BackgroundTaskForUi, type TaskManagerResult } from "./ui/background-tasks-manager.js";
 
@@ -35,6 +38,13 @@ import { BackgroundTasksManager, type BackgroundTaskForUi, type TaskManagerResul
 
 const STATUS_INTERVAL_MS = 1000;
 const COMMAND_PREVIEW_CHARS = 90;
+const GIT_INSTALL_TARGET = "git:github.com/ismailsaleekh/pi-background-tasks";
+
+const packageInfo = readPackageInfo(new URL("../package.json", import.meta.url), (error) => {
+	console.error(`[background-tasks] failed to read package version: ${error.message}`);
+});
+const PACKAGE_NAME = packageInfo.name ?? "pi-background-tasks";
+const PACKAGE_VERSION = packageInfo.version;
 const LIGHT_BLUE_BG = "\x1b[48;2;183;223;255m";
 const LIGHT_BLUE_FG = "\x1b[38;2;11;70;110m";
 const ANSI_RESET = "\x1b[0m";
@@ -88,6 +98,8 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 	let currentCtx: ExtensionContext | undefined;
 	let dockOpen = false;
 	let statusInterval: NodeJS.Timeout | undefined;
+	let latestKnownVersion: string | undefined;
+	let updateCheckStarted = false;
 
 	const registry = new BackgroundTaskRegistry({
 		onChange: () => updateUi(),
@@ -129,9 +141,10 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 			const unseenStopped = allTasks.filter((task) => task.status === "killed" && !seenTaskIds.has(task.id));
 			const unseenDone = allTasks.filter((task) => task.status === "completed" && !seenTaskIds.has(task.id));
 			const unseenFinishedCount = unseenFailed.length + unseenStopped.length + unseenDone.length;
+			const updateSegment = formatUpdateSegment(latestKnownVersion, PACKAGE_VERSION ?? "");
 			ctx.ui.setWidget("background-tasks", undefined);
 			if (running.length === 0 && unseenFinishedCount === 0) {
-				ctx.ui.setStatus("background-tasks", undefined);
+				ctx.ui.setStatus("background-tasks", updateSegment ? lightBlue(` bg ${updateSegment} `) : undefined);
 				return;
 			}
 
@@ -141,7 +154,9 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 			if (unseenStopped.length > 0) parts.push(`${unseenStopped.length} stopped`);
 			if (unseenDone.length > 0) parts.push(`${unseenDone.length} done`);
 			const entryHint = dockOpen ? "focused" : `Shift↓${unseenFinishedCount > 0 ? " · /bg-clear" : ""}`;
-			const label = ` bg ${parts.join(" · ")} · ${entryHint} `;
+			const segments = [...parts, entryHint];
+			if (updateSegment) segments.push(updateSegment);
+			const label = ` bg ${segments.join(" · ")} `;
 			ctx.ui.setStatus("background-tasks", lightBlue(label));
 		} catch (error) {
 			console.error(`[background-tasks] UI update failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -227,6 +242,26 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		return new Text(`${theme.fg(color, `[bg ${status}]`)} ${theme.fg("accent", name)} ${theme.fg("dim", `(${id})`)}${output}${error}`, 0, 0);
 	});
 
+	async function scheduleUpdateCheck(ctx: ExtensionContext): Promise<void> {
+		if (updateCheckStarted) return;
+		updateCheckStarted = true;
+		const env = process.env;
+		if (env["PI_BG_DISABLE_UPDATE_CHECK"] === "1") return;
+		if (env["PI_OFFLINE"] === "1") return;
+		if (!PACKAGE_VERSION) return;
+		const options: FetchLatestVersionOptions = {
+			packageName: PACKAGE_NAME,
+			onError: (error) => console.error(`[background-tasks] update check skipped: ${error.message}`),
+		};
+		const registryUrl = env["PI_BG_REGISTRY_URL"];
+		if (registryUrl) options.registryUrl = registryUrl;
+		const latest = await fetchLatestVersion(options);
+		if (latest && isNewerVersion(latest, PACKAGE_VERSION)) {
+			latestKnownVersion = latest;
+			updateUi(ctx);
+		}
+	}
+
 	pi.on("session_start", async (_event, ctx) => {
 		registry.setShuttingDown(false);
 		currentCtx = ctx;
@@ -234,6 +269,8 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		updateUi(ctx);
 		if (statusInterval) clearInterval(statusInterval);
 		statusInterval = setInterval(() => updateUi(), STATUS_INTERVAL_MS);
+		// One-shot, non-blocking: never awaited on the session-start path or the status tick.
+		void scheduleUpdateCheck(ctx);
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {
@@ -301,6 +338,28 @@ export default function backgroundTasksExtension(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerCommand("bg-update", {
+		description: "Show how to update pi-background-tasks to the latest published version",
+		handler: async (_args, ctx) => {
+			const current = PACKAGE_VERSION ?? "unknown";
+			const latest = latestKnownVersion;
+			const pinnedNpm = latest ? `${PACKAGE_NAME}@${latest}` : `${PACKAGE_NAME}@<version>`;
+			const pinnedGit = latest ? `${GIT_INSTALL_TARGET}@v${latest}` : `${GIT_INSTALL_TARGET}@<tag>`;
+			const lines = [
+				latest
+					? `pi-background-tasks ${current} is installed; ${latest} is the latest published version.`
+					: `pi-background-tasks ${current} is installed.`,
+				"Update from npm:",
+				`  pi install npm:${PACKAGE_NAME}@latest`,
+				`  pi install npm:${pinnedNpm}`,
+				"Or update from git tags:",
+				`  pi install ${pinnedGit}`,
+				"This command only prints update instructions; it does not install or self-update.",
+			];
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+
 	pi.registerShortcut("shift+down" satisfies KeyId, {
 		description: "Open focused background task footer dock",
 		handler: async (ctx) => {