@maxiaochao/pi-toolkit 0.12.2 → 0.13.0

package/packages/background-tasks/src/background-tasks.ts

@@ -0,0 +1,240 @@
+import { randomUUID } from "node:crypto";
+import { mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import type { BashOperations } from "@earendil-works/pi-coding-agent";
+import { TaskLog, type LogWrite, type OutputView } from "./output.ts";
+
+export interface Clock {
+	now(): number;
+	setTimeout(callback: () => void, delay: number): unknown;
+	clearTimeout(handle: unknown): void;
+}
+export const systemClock: Clock = {
+	now: () => Date.now(),
+	setTimeout: (callback, delay) => setTimeout(callback, delay),
+	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+export type TaskStatus = "running" | "succeeded" | "failed" | "cancelled" | "timed_out" | "output_limit";
+export interface TaskSnapshot {
+	id: string;
+	status: TaskStatus;
+	description: string;
+	cwd: string;
+	started_at: number;
+	ended_at?: number;
+	timeout: number;
+	elapsed_seconds: number;
+	log_path: string;
+	bytes: number;
+	capture_complete: boolean;
+	exit_code?: number;
+	reason?: string;
+}
+export interface StartParams {
+	command: string;
+	description?: string;
+	cwd?: string;
+	timeout?: number;
+}
+interface Task {
+	data: TaskSnapshot;
+	log: TaskLog;
+	controller: AbortController;
+	timer?: unknown;
+	done: Promise<void>;
+	stop?: Exclude<TaskStatus, "running" | "succeeded">;
+	captureLost: boolean;
+}
+export interface TaskList {
+	tasks: TaskSnapshot[];
+	running: number;
+	total: number;
+	omitted: number;
+}
+
+export function summary(text: string, max = 200): string {
+	return Array.from(stripVTControlCharacters(text).replace(/[\x00-\x1f\x7f\uFFF9-\uFFFB]/g, " ").trim()).slice(0, max).join("");
+}
+export function errorText(error: unknown): string {
+	return summary(error instanceof Error ? error.message : String(error), 500);
+}
+
+/** Session-owned jobs; tool calls only transfer control, never own the job signal. */
+export class BackgroundTasks {
+	private readonly operations: BashOperations;
+	readonly clock: Clock;
+	private readonly onComplete: (task: TaskSnapshot) => void;
+	private readonly onChange: () => void;
+	private readonly logRoot: string;
+	private readonly logWrite?: LogWrite;
+	private readonly taskBytes: number;
+	private readonly sessionBytes: number;
+	private readonly tasks = new Map<string, Task>();
+	private directory?: string;
+	private bytes = 0;
+	private closed = false;
+	private shutdownPromise?: Promise<void>;
+
+	constructor(options: {
+		operations: BashOperations;
+		clock?: Clock;
+		onComplete?: (task: TaskSnapshot) => void;
+		onChange?: () => void;
+		logRoot?: string;
+		logWrite?: LogWrite;
+		limits?: { taskBytes: number; sessionBytes: number };
+	}) {
+		this.operations = options.operations;
+		this.clock = options.clock ?? systemClock;
+		this.onComplete = options.onComplete ?? (() => {});
+		this.onChange = options.onChange ?? (() => {});
+		this.logRoot = options.logRoot ?? tmpdir();
+		this.logWrite = options.logWrite;
+		this.taskBytes = options.limits?.taskBytes ?? 32 * 1024 * 1024;
+		this.sessionBytes = options.limits?.sessionBytes ?? 256 * 1024 * 1024;
+		if (this.taskBytes <= 0 || this.sessionBytes <= 0) throw new Error("Log limits must be positive");
+	}
+
+	start(params: StartParams, sessionCwd: string): TaskSnapshot {
+		if (this.closed) throw new Error("Background tasks session is closed");
+		if (typeof params.command !== "string" || !params.command.trim()) throw new Error("start requires a non-empty command");
+		const timeout = params.timeout === undefined ? 1800 : params.timeout;
+		if (!Number.isInteger(timeout) || timeout < 1 || timeout > 7200) throw new Error("timeout must be an integer from 1 to 7200 seconds (default 1800)");
+		if (params.description !== undefined && typeof params.description !== "string") throw new Error("description must be a string");
+		if (params.cwd !== undefined && (typeof params.cwd !== "string" || !params.cwd.trim())) throw new Error("cwd must be a non-empty directory path");
+		const cwd = resolve(sessionCwd, params.cwd ?? ".");
+		try {
+			if (!statSync(cwd).isDirectory()) throw new Error("not a directory");
+		} catch (error) { throw new Error(`Invalid working directory: ${errorText(error)}`); }
+		if (this.running() >= 2) throw new Error("At most two background tasks may be running; cancel one or wait for completion");
+		if (this.bytes >= this.sessionBytes) throw new Error("Session log budget exhausted; start a new session to reset it");
+		this.directory ??= mkdtempSync(join(this.logRoot, "pi-background-tasks-"));
+		let id: string;
+		do { id = `bg-${randomUUID().replace(/-/g, "").slice(0, 12)}`; } while (this.tasks.has(id));
+		const log = new TaskLog(join(this.directory, `${id}.log`), this.logWrite);
+		const task: Task = {
+			data: {
+				id, status: "running", description: summary(params.description || params.command.split("\n", 1)[0]), cwd,
+				started_at: this.clock.now(), timeout, elapsed_seconds: 0, log_path: log.path,
+				bytes: 0, capture_complete: false,
+			},
+			log, controller: new AbortController(), done: Promise.resolve(), captureLost: false,
+		};
+		// This path is synchronous: reserve the slot before any execution can await.
+		this.tasks.set(id, task);
+		task.timer = this.clock.setTimeout(() => this.stop(task, "timed_out", `Runtime limit of ${timeout} seconds reached`), timeout * 1000);
+		const accepted = this.snapshot(task);
+		task.done = this.run(task, params.command);
+		this.changed();
+		return accepted;
+	}
+
+	get(id: string): TaskSnapshot { return this.snapshot(this.find(id)); }
+
+	list(): TaskList {
+		const all = [...this.tasks.values()];
+		const active = all.filter((task) => task.data.status === "running");
+		const ended = all.filter((task) => task.data.status !== "running").reverse().slice(0, 20);
+		return { tasks: [...active, ...ended].map((task) => this.snapshot(task)), running: active.length, total: all.length, omitted: all.length - active.length - ended.length };
+	}
+
+	output(id: string): TaskSnapshot & OutputView {
+		const task = this.find(id);
+		try { return { ...this.snapshot(task), ...task.log.read() }; }
+		catch (error) {
+			this.captureFailure(task, `Cannot read task log: ${errorText(error)}`);
+			throw new Error(`Cannot read task log: ${errorText(error)}`);
+		}
+	}
+
+	async cancel(id: string): Promise<TaskSnapshot> {
+		const task = this.find(id);
+		this.stop(task, "cancelled", "Cancelled by request");
+		await task.done;
+		return this.snapshot(task);
+	}
+
+	shutdown(): Promise<void> {
+		if (this.shutdownPromise) return this.shutdownPromise;
+		this.closed = true;
+		for (const task of this.tasks.values()) this.stop(task, "cancelled", "Session closed");
+		this.shutdownPromise = Promise.all([...this.tasks.values()].map((task) => task.done)).then(() => {
+			if (this.directory) rmSync(this.directory, { recursive: true, force: true });
+		});
+		return this.shutdownPromise;
+	}
+
+	private async run(task: Task, command: string): Promise<void> {
+		try {
+			const { exitCode } = await this.operations.exec(command, task.data.cwd, {
+				signal: task.controller.signal,
+				onData: (data) => this.append(task, data),
+			});
+			if (exitCode !== null) task.data.exit_code = exitCode;
+			if (!task.stop && exitCode !== 0) this.stop(task, "failed", `Command exited with ${exitCode === null ? "no exit code" : `code ${exitCode}`}`);
+		} catch (error) {
+			this.stop(task, "failed", errorText(error));
+		} finally {
+			if (task.timer !== undefined) this.clock.clearTimeout(task.timer);
+			task.timer = undefined;
+			try { task.log.finish(); }
+			catch (error) {
+				this.captureFailure(task, `Cannot close task log: ${errorText(error)}`);
+			}
+			task.data.status = task.stop ?? "succeeded";
+			task.data.ended_at = this.clock.now();
+			task.data.capture_complete = !task.captureLost;
+			this.changed();
+			if (!this.closed) {
+				try { this.onComplete(this.snapshot(task)); }
+				catch (error) { console.error(`Background completion notification failed: ${errorText(error)}`); }
+			}
+		}
+	}
+
+	private append(task: Task, data: Buffer): void {
+		if (task.captureLost || task.data.status !== "running" || data.length === 0) return;
+		const remaining = Math.max(0, Math.min(this.taskBytes - task.log.bytes, this.sessionBytes - this.bytes));
+		const before = task.log.bytes;
+		try { if (remaining > 0) task.log.append(data.subarray(0, remaining)); }
+		catch (error) {
+			this.captureFailure(task, `Cannot write task log: ${errorText(error)}`);
+		} finally { this.bytes += task.log.bytes - before; }
+		if (data.length >= remaining) {
+			task.captureLost = true;
+			this.stop(task, "output_limit", `Log output limit reached (task ${this.taskBytes} bytes; session ${this.sessionBytes} bytes)`);
+		}
+	}
+
+	private captureFailure(task: Task, reason: string): void {
+		task.captureLost = true;
+		if (task.stop || task.data.status !== "running") {
+			task.data.reason = summary(`${task.data.reason ? `${task.data.reason}; ` : ""}${reason}`, 500);
+		}
+		this.stop(task, "failed", reason);
+	}
+
+	private stop(task: Task, status: NonNullable<Task["stop"]>, reason: string): void {
+		if (task.data.status !== "running" || task.stop) return;
+		task.stop = status;
+		task.data.reason = summary(reason, 500);
+		task.controller.abort();
+	}
+
+	private running(): number { return [...this.tasks.values()].filter((task) => task.data.status === "running").length; }
+	private find(id: string): Task {
+		const task = this.tasks.get(id);
+		if (!task) throw new Error("Unknown background task ID in this session");
+		return task;
+	}
+	private snapshot(task: Task): TaskSnapshot {
+		return { ...task.data, capture_complete: task.data.capture_complete && !task.captureLost, bytes: task.log.bytes, elapsed_seconds: Math.max(0, ((task.data.ended_at ?? this.clock.now()) - task.data.started_at) / 1000) };
+	}
+	private changed(): void {
+		if (this.closed) return;
+		try { this.onChange(); }
+		catch (error) { console.error(`Background task display failed: ${errorText(error)}`); }
+	}
+}

package/packages/background-tasks/src/output.ts

@@ -0,0 +1,128 @@
+import { closeSync, openSync, readSync, writeSync } from "node:fs";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateTail, type TruncationResult } from "@earendil-works/pi-coding-agent";
+
+const PROGRAM_BYTES = 1024 * 1024;
+export type LogWrite = (fd: number, data: Buffer) => number;
+
+export interface OutputView {
+	text: string;
+	output: string;
+	truncated: boolean;
+	truncation: TruncationResult;
+}
+
+/** Owns one log. Reads are range-limited even when the on-disk log is large. */
+export class TaskLog {
+	readonly path: string;
+	bytes = 0;
+	private fd: number;
+	private closed = false;
+	private readonly write: LogWrite;
+	private decoder = new TextDecoder();
+	private decodedBytes = 0;
+	private lines = 0;
+	private openLine = false;
+	private lastLineBytes = 0;
+
+	constructor(path: string, write: LogWrite = (fd, data) => writeSync(fd, data)) {
+		this.path = path;
+		this.write = write;
+		this.fd = openSync(path, "wx", 0o600);
+	}
+
+	append(data: Buffer): void {
+		if (this.closed) throw new Error("Log is closed");
+		let offset = 0;
+		while (offset < data.length) {
+			const remaining = data.subarray(offset);
+			const count = this.write(this.fd, remaining);
+			if (!Number.isInteger(count) || count <= 0 || count > remaining.length) throw new Error("Log write made invalid progress");
+			this.bytes += count;
+			this.countText(this.decoder.decode(remaining.subarray(0, count), { stream: true }));
+			offset += count;
+		}
+	}
+
+	finish(): void {
+		if (this.closed) return;
+		this.closed = true;
+		try { this.countText(this.decoder.decode()); }
+		finally { closeSync(this.fd); }
+	}
+
+	read(): OutputView {
+		const fd = openSync(this.path, "r");
+		try {
+			// Keep a bounded working window comparable to Bash's rolling tail. This
+			// preserves an oversized last line that ends with a newline before trimming.
+			const start = Math.max(0, this.bytes - DEFAULT_MAX_BYTES * 4 - 4);
+			const tail = this.range(fd, start, this.bytes - start);
+			let first = 0;
+			while (first < tail.length && (tail[first] & 0xc0) === 0x80) first++;
+			let snapshot = new TextDecoder().decode(tail.subarray(first), { stream: !this.closed });
+			if (start > 0) {
+				const previous = this.range(fd, start - 1, 1)[0];
+				if (first > 0 || previous !== 0x0a) {
+					const newline = snapshot.indexOf("\n");
+					if (newline !== -1) snapshot = snapshot.slice(newline + 1);
+				}
+			}
+			const truncation = truncateTail(snapshot);
+			const totalLines = this.lines + (this.openLine ? 1 : 0);
+			truncation.truncated = totalLines > DEFAULT_MAX_LINES || this.decodedBytes > DEFAULT_MAX_BYTES;
+			truncation.truncatedBy = truncation.truncated
+				? (truncation.truncatedBy ?? (this.decodedBytes > DEFAULT_MAX_BYTES ? "bytes" : "lines")) : null;
+			truncation.totalLines = totalLines;
+			truncation.totalBytes = this.decodedBytes;
+			let text = truncation.content || "(no output)";
+			if (truncation.truncated) {
+				const end = totalLines;
+				const begin = end - truncation.outputLines + 1;
+				const detail = truncation.lastLinePartial
+					? `last ${formatSize(truncation.outputBytes)} of line ${end} (line is ${formatSize(this.lastLineBytes)})`
+					: `lines ${begin}-${end} of ${end}${truncation.truncatedBy === "bytes" ? ` (${formatSize(DEFAULT_MAX_BYTES)} limit)` : ""}`;
+				text += `\n\n[Showing ${detail}. Full output: ${this.path}]`;
+			}
+			const program = this.readProgram(fd);
+			return { text, output: program.content, truncated: program.truncated, truncation };
+		} finally { closeSync(fd); }
+	}
+
+	private readProgram(fd: number): { content: string; truncated: boolean } {
+		if (this.bytes <= PROGRAM_BYTES) {
+			return { content: new TextDecoder().decode(this.range(fd, 0, this.bytes), { stream: !this.closed }), truncated: false };
+		}
+		const half = PROGRAM_BYTES / 2;
+		const head = this.range(fd, 0, half);
+		const tail = this.range(fd, this.bytes - half, half);
+		const headText = new TextDecoder().decode(head, { stream: true });
+		let first = 0;
+		while (first < tail.length && (tail[first] & 0xc0) === 0x80) first++;
+		const tailText = new TextDecoder().decode(tail.subarray(first), { stream: !this.closed });
+		return { content: `${headText}\n\n[... ${this.bytes - PROGRAM_BYTES} bytes omitted ...]\n\n${tailText}`, truncated: true };
+	}
+
+	private range(fd: number, position: number, length: number): Buffer {
+		const data = Buffer.alloc(length);
+		let offset = 0;
+		while (offset < length) {
+			const count = readSync(fd, data, offset, length - offset, position + offset);
+			if (count === 0) throw new Error("Log changed unexpectedly while reading");
+			offset += count;
+		}
+		return data;
+	}
+
+	private countText(text: string): void {
+		this.decodedBytes += Buffer.byteLength(text);
+		const last = text.lastIndexOf("\n");
+		if (last === -1) {
+			if (text.length) this.openLine = true;
+			this.lastLineBytes += Buffer.byteLength(text);
+		} else {
+			for (let index = text.indexOf("\n"); index !== -1; index = text.indexOf("\n", index + 1)) this.lines++;
+			this.lastLineBytes = Buffer.byteLength(text.slice(last + 1));
+			this.openLine = last < text.length - 1;
+		}
+	}
+}

package/packages/background-tasks/src/widget.ts

@@ -0,0 +1,54 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import type { Clock, TaskSnapshot } from "./background-tasks.ts";
+
+export const WIDGET_KEY = "background-tasks";
+export const FINISHED_VISIBLE_MS = 5000;
+
+export function visibleTasks(tasks: TaskSnapshot[], now: number): TaskSnapshot[] {
+	return tasks.filter((task) => task.status === "running" || (task.ended_at !== undefined && now < task.ended_at + FINISHED_VISIBLE_MS));
+}
+
+export function duration(seconds: number): string {
+	const value = Math.max(0, Math.floor(seconds));
+	if (value >= 3600) return `${Math.floor(value / 3600)}h${value % 3600 ? ` ${Math.floor(value % 3600 / 60)}m` : ""}`;
+	if (value >= 60) return `${Math.floor(value / 60)}m${value % 60 ? ` ${value % 60}s` : ""}`;
+	return `${value}s`;
+}
+
+export class BackgroundWidget {
+	private lines?: string[];
+	private width?: number;
+	private readonly getTasks: () => TaskSnapshot[];
+	private readonly clock: Clock;
+	private readonly theme: Theme;
+
+	constructor(getTasks: () => TaskSnapshot[], clock: Clock, theme: Theme) {
+		this.getTasks = getTasks;
+		this.clock = clock;
+		this.theme = theme;
+	}
+
+	render(width: number): string[] {
+		if (this.lines && this.width === width) return this.lines;
+		const tasks = visibleTasks(this.getTasks(), this.clock.now());
+		const active = tasks.filter((task) => task.status === "running").length;
+		const { theme } = this;
+		this.lines = [
+			truncateToWidth(theme.fg("accent", `Background tasks ${active}/2`), width),
+			...tasks.map((task) => {
+				const color = task.status === "running" ? "accent" : task.status === "succeeded" ? "success" : task.status === "cancelled" ? "muted" : "error";
+				const marker = task.status === "running" ? "●" : task.status === "succeeded" ? "✓" : task.status === "cancelled" ? "○" : "✗";
+				const elapsed = ((task.ended_at ?? this.clock.now()) - task.started_at) / 1000;
+				return truncateToWidth(`  ${theme.fg(color, marker)} ${theme.fg("accent", task.id)} · ${duration(elapsed)} / ${duration(task.timeout)} · ${theme.fg(color, task.status)} · ${theme.fg("text", task.description)}`, width);
+			}),
+		];
+		this.width = width;
+		return this.lines;
+	}
+
+	invalidate(): void {
+		this.lines = undefined;
+		this.width = undefined;
+	}
+}

package/packages/background-tasks/tests/extension.mjs

@@ -0,0 +1,192 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import register from "../extensions/background-tasks.ts";
+import { fixture, flush } from "./helpers.mjs";
+
+function harness(mode = "tui", hasUI = true) {
+	const f = fixture();
+	const handlers = new Map();
+	const commands = new Map();
+	const messages = [];
+	const notices = [];
+	const widgets = new Map([["scheduler", { render: () => ["Scheduler"] }], ["herdr-subagents", { render: () => ["Fleet"] }]]);
+	const placements = new Map();
+	const statuses = new Map();
+	let tool, renders = 0;
+	const theme = { fg: (_color, text) => text, bold: (text) => text };
+	const ctx = {
+		cwd: f.root, mode, hasUI,
+		ui: {
+			setWidget(key, factory, options) {
+				if (!factory) { widgets.delete(key); return; }
+				widgets.set(key, factory({ requestRender() { renders++; } }, theme));
+				placements.set(key, options);
+			},
+			setStatus(key, value) { if (value === undefined) statuses.delete(key); else statuses.set(key, value); },
+			notify(message, level) { notices.push({ message, level }); },
+		},
+	};
+	const pi = {
+		on(name, handler) { handlers.set(name, handler); },
+		registerTool(value) { tool = value; },
+		registerCommand(name, value) { commands.set(name, value); },
+		sendMessage(message, options) { messages.push({ message, options }); },
+	};
+	register(pi, { operations: f.operations, clock: f.clock, logRoot: f.root });
+	return {
+		...f, handlers, commands, messages, notices, widgets, placements, statuses, ctx,
+		get tool() { return tool; }, get renders() { return renders; },
+		async close() {
+			const closing = handlers.get("session_shutdown")({}, ctx);
+			for (const call of f.calls) call.resolve();
+			await closing;
+			await f.close();
+		},
+	};
+}
+
+test("registration is compact, does not inject prompt rules or start session resources", async () => {
+	const h = harness();
+	try {
+		assert.equal(h.tool.name, "background_task");
+		assert.match(h.tool.description, /return task IDs immediately/);
+		assert.ok(h.tool.description.length < 200);
+		assert.equal(h.tool.promptGuidelines, undefined);
+		assert.ok(h.tool.outputSchema);
+		assert.equal(h.tool.annotations.readOnlyHint, false);
+		assert.equal(h.tool.annotations.destructiveHint, true);
+		assert.ok(!h.handlers.has("before_agent_start"));
+		assert.equal(h.clock.timers.size, 0);
+		assert.equal(h.calls.length, 0);
+		assert.equal((await h.tool.execute("early", { action: "list" })).isError, true);
+	} finally { await h.close(); }
+});
+
+test("tools, commands, widget and followUp share the same session jobs", async () => {
+	const h = harness();
+	try {
+		await h.handlers.get("session_start")({}, h.ctx);
+		const parentSignal = new AbortController();
+		const result = await h.tool.execute("start", { action: "start", command: "sleep 60", description: "测试构建", timeout: 60 }, parentSignal.signal, undefined, h.ctx);
+		assert.equal(result.isError, false);
+		const job = result.structuredContent.task;
+		assert.equal(job.status, "running");
+		parentSignal.abort();
+		assert.equal(h.calls[0].signal.aborted, false, "parent turn cancellation does not own the accepted background job");
+		assert.deepEqual(h.placements.get("background-tasks"), { placement: "aboveEditor" });
+		h.clock.advance(1000);
+		const widget = h.widgets.get("background-tasks");
+		assert.match(widget.render(140).join("\n"), /1s \/ 1m/);
+		for (const width of [1, 8, 40, 80]) assert.ok(widget.render(width).every((line) => visibleWidth(line) <= width));
+		assert.ok(h.widgets.has("scheduler") && h.widgets.has("herdr-subagents"));
+
+		h.calls[0].onData(Buffer.from("logs only on explicit read\n"));
+		await h.commands.get("bg").handler(`output ${job.id}`, h.ctx);
+		assert.match(h.messages.at(-1).message.content, /logs only on explicit read/);
+		assert.equal(h.messages.at(-1).options.triggerTurn, false);
+		const output = await h.tool.execute("output", { action: "output", id: job.id });
+		assert.equal(output.structuredContent.output, "logs only on explicit read\n");
+		assert.equal(output.details.output, undefined);
+
+		h.calls[0].resolve(7);
+		await flush();
+		const completed = h.messages.filter((m) => m.message.customType === "background-task-finished");
+		assert.equal(completed.length, 1);
+		assert.deepEqual(completed[0].options, { triggerTurn: true, deliverAs: "followUp" });
+		assert.match(completed[0].message.content, /failed.*exit 7/);
+		assert.ok(!completed[0].message.content.includes("logs only"));
+		assert.match(h.widgets.get("background-tasks").render(140).join("\n"), /failed/);
+		h.clock.advance(4999);
+		assert.ok(h.widgets.has("background-tasks"));
+		h.clock.advance(1);
+		assert.equal(h.widgets.has("background-tasks"), false);
+		assert.equal(h.clock.timers.size, 0);
+		assert.equal((await h.tool.execute("history", { action: "output", id: job.id })).structuredContent.task.status, "failed");
+		assert.ok(h.renders > 0);
+	} finally { await h.close(); }
+});
+
+test("cancel and shutdown are idempotent; new sessions cannot receive old completions", async () => {
+	const h = harness();
+	try {
+		await h.handlers.get("session_start")({}, h.ctx);
+		const a = (await h.tool.execute("a", { action: "start", command: "first" })).structuredContent.task;
+		const b = (await h.tool.execute("b", { action: "start", command: "second" })).structuredContent.task;
+		assert.equal((await h.tool.execute("c", { action: "start", command: "third" })).isError, true);
+		const cancel = h.tool.execute("cancel", { action: "cancel", id: a.id });
+		h.calls[0].reject(new Error("aborted"));
+		assert.equal((await cancel).structuredContent.task.status, "cancelled");
+		const count = h.messages.length;
+		await h.commands.get("bg").handler(`cancel ${a.id}`, h.ctx);
+		assert.equal(h.messages.filter((m) => m.message.customType === "background-task-finished").length, 1);
+		assert.equal(h.messages.length, count + 1, "only the explicit command acknowledgement is added");
+		const shutdown = h.handlers.get("session_shutdown")({ reason: "reload" }, h.ctx);
+		assert.equal(h.calls[1].signal.aborted, true);
+		h.calls[1].resolve();
+		await shutdown;
+		await h.handlers.get("session_start")({ reason: "reload" }, h.ctx);
+		assert.equal((await h.tool.execute("old", { action: "output", id: b.id })).isError, true);
+		assert.equal(h.messages.filter((m) => m.message.customType === "background-task-finished").length, 1);
+		assert.equal(h.clock.timers.size, 0);
+		assert.ok(h.widgets.has("scheduler") && h.widgets.has("herdr-subagents"));
+	} finally { await h.close(); }
+});
+
+for (const [mode, hasUI] of [["rpc", true], ["print", false], ["json", false]]) {
+	test(`${mode}: tools work without a TUI or render timer`, async () => {
+		const h = harness(mode, hasUI);
+		try {
+			await h.handlers.get("session_start")({}, h.ctx);
+			const result = await h.tool.execute("job", { action: "start", command: "ok" });
+			assert.equal(result.structuredContent.task.status, "running");
+			assert.equal(h.widgets.has("background-tasks"), false);
+			assert.equal(h.clock.timers.size, 1, "only the execution deadline exists");
+			if (hasUI) assert.match(h.statuses.get("background-tasks"), /1\/2/);
+			h.calls[0].resolve();
+			await flush();
+			assert.equal(h.clock.timers.size, 0);
+			assert.equal(h.statuses.has("background-tasks"), false);
+			assert.equal(h.messages.at(-1).options.deliverAs, "followUp");
+		} finally { await h.close(); }
+	});
+}
+
+test("bad actions, irrelevant fields, aborted acceptance and command syntax fail visibly", async () => {
+	const h = harness();
+	try {
+		await h.handlers.get("session_start")({}, h.ctx);
+		for (const params of [
+			{ action: "other" }, { action: "start" }, { action: "list", command: "ignored" },
+			{ action: "output" }, { action: "cancel", id: "unknown" },
+			{ action: "start", command: "x", id: "irrelevant" },
+		]) {
+			const result = await h.tool.execute("bad", params);
+			assert.equal(result.isError, true);
+			assert.ok(result.structuredContent.error.length <= 500);
+		}
+		const abort = new AbortController(); abort.abort();
+		assert.equal((await h.tool.execute("abort", { action: "start", command: "x" }, abort.signal)).isError, true);
+		await h.commands.get("bg").handler("start echo hello", h.ctx);
+		assert.equal(h.notices.at(-1).level, "error");
+		assert.equal(h.calls.length, 0);
+	} finally { await h.close(); }
+});
+
+for (const reason of ["new", "resume", "fork", "quit"]) {
+	test(`${reason} shutdown suppresses old notifications, removes timers and isolates IDs`, async () => {
+		const h = harness();
+		try {
+			await h.handlers.get("session_start")({}, h.ctx);
+			const job = (await h.tool.execute("start", { action: "start", command: "pending" })).structuredContent.task;
+			const stopping = h.handlers.get("session_shutdown")({ reason }, h.ctx);
+			assert.equal(h.calls[0].signal.aborted, true);
+			h.calls[0].reject(new Error("aborted"));
+			await stopping;
+			await h.handlers.get("session_start")({ reason }, h.ctx);
+			assert.equal(h.messages.length, 0);
+			assert.equal(h.clock.timers.size, 0);
+			assert.equal((await h.tool.execute("old", { action: "output", id: job.id })).isError, true);
+		} finally { await h.close(); }
+	});
+}

package/packages/background-tasks/tests/fixtures/provider.ts

@@ -0,0 +1,63 @@
+// Offline fixture only. No network, real credentials, or nested model calls.
+import { appendFileSync } from "node:fs";
+import { createAssistantMessageEventStream, getCurrentTools } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	const record = (entry: unknown) => {
+		if (process.env.BG_SMOKE_EVENTS) appendFileSync(process.env.BG_SMOKE_EVENTS, JSON.stringify(entry) + "\n");
+	};
+	let sequence = 0;
+	pi.registerProvider("bg-fixture", {
+		name: "Offline background-task fixture", baseUrl: "http://127.0.0.1:1", api: "bg-fixture",
+		apiKey: "fixture-not-a-secret",
+		models: [{ id: "deterministic", name: "Offline fixture (no network)", reasoning: false, input: ["text"], contextWindow: 128000, maxTokens: 4096, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } }],
+		streamSimple(model, context) {
+			const stream = createAssistantMessageEventStream();
+			queueMicrotask(() => {
+				const last = context.messages.at(-1) as any;
+				const text = typeof last?.content === "string" ? last.content : (last?.content ?? []).filter((block: any) => block.type === "text").map((block: any) => block.text).join("\n");
+				record({ event: "request", lastRole: last?.role, text: text.slice(0, 2000), tools: getCurrentTools(context.messages).map((tool) => tool.name) });
+				let code: string | undefined;
+				if (last?.role !== "toolResult") {
+					if (text.includes("SMOKE_START")) code = `const a = await tools.background_task({ action: "start", command: "sleep 9; printf 'BUILD SUCCESSFUL\\\\n'", description: "Release build", timeout: 30 });
+const b = await tools.background_task({ action: "start", command: "sleep 300", description: "Cancel this task", timeout: 300 });
+const c = await tools.background_task({ action: "start", command: "printf third" });
+text({ first: a.task.id, second: b.task.id, third: c });`;
+					else if (text.includes("SMOKE_CANCEL")) code = `const list = await tools.background_task({ action: "list" });
+const task = list.tasks.find(t => t.description === "Cancel this task");
+text(await tools.background_task({ action: "cancel", id: task.id }));`;
+					else if (text.includes("SMOKE_OUTPUT")) code = `const list = await tools.background_task({ action: "list" });
+const task = list.tasks.find(t => t.description === "Release build");
+const result = await tools.background_task({ action: "output", id: task.id });
+text({ status: result.task.status, output: result.output });`;
+					else if (text.includes("SMOKE_LONG")) code = `text(await tools.background_task({ action: "start", command: "echo $$ > shell.pid; sleep 300 & echo $! > child.pid; wait", description: "Lifecycle cleanup check", timeout: 300 }));`;
+				}
+				const message: any = { role: "assistant", api: model.api, provider: model.provider, model: model.id, timestamp: Date.now(), content: [], stopReason: code ? "toolUse" : "stop",
+					usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } } };
+				stream.push({ type: "start", partial: message });
+				if (code) {
+					message.content.push({ type: "toolCall", id: `fixture-${++sequence}`, name: "codemode", arguments: { code } });
+					stream.push({ type: "toolcall_start", contentIndex: 0, partial: message });
+					stream.push({ type: "toolcall_end", contentIndex: 0, toolCall: message.content[0], partial: message });
+				} else {
+					const reply = text.includes("[Background task finished]") ? "BACKGROUND_FOLLOWUP_RECEIVED" : "Main agent is ready; accepted background tasks keep running.";
+					message.content.push({ type: "text", text: reply });
+					stream.push({ type: "text_start", contentIndex: 0, partial: message });
+					stream.push({ type: "text_delta", contentIndex: 0, delta: reply, partial: message });
+					stream.push({ type: "text_end", contentIndex: 0, content: reply, partial: message });
+				}
+				stream.push({ type: "done", reason: message.stopReason, message });
+			});
+			return stream;
+		},
+	});
+	pi.on("session_start", (_event, ctx) => {
+		record({ event: "loaded", tools: pi.getAllTools().map((tool) => tool.name) });
+		if (ctx.hasUI) ctx.ui.setTitle("Pi Background Tasks Smoke");
+	});
+	pi.on("tool_execution_end", (event) => record({ event: "tool_end", name: event.toolName, isError: event.isError, result: event.result }));
+	pi.on("message_start", (event) => {
+		if (event.message.role === "custom") record({ event: "custom", type: event.message.customType, details: event.message.details });
+	});
+}