@maxiaochao/pi-toolkit 0.13.5 → 0.13.6

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

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import { unlinkSync } from "node:fs";
 import { test } from "node:test";
 import { visibleWidth } from "@earendil-works/pi-tui";
 import register from "../extensions/background-tasks.ts";
@@ -13,10 +14,11 @@ function harness(mode = "tui", hasUI = true) {
 	const widgets = new Map([["scheduler", { render: () => ["Scheduler"] }], ["herdr-subagents", { render: () => ["Fleet"] }]]);
 	const placements = new Map();
 	const statuses = new Map();
-	let tool, renders = 0;
+	const idleChecks = [];
+	let tool, renders = 0, idle = true;
 	const theme = { fg: (_color, text) => text, bold: (text) => text };
 	const ctx = {
-		cwd: f.root, mode, hasUI,
+		cwd: f.root, mode, hasUI, isIdle: () => { idleChecks.push(f.clock.now()); return idle; },
 		ui: {
 			setWidget(key, factory, options) {
 				if (!factory) { widgets.delete(key); return; }
@@ -35,7 +37,8 @@ function harness(mode = "tui", hasUI = true) {
 	};
 	register(pi, { operations: f.operations, clock: f.clock, logRoot: f.root });
 	return {
-		...f, handlers, commands, messages, notices, widgets, placements, statuses, ctx,
+		...f, handlers, commands, messages, notices, widgets, placements, statuses, idleChecks, ctx,
+		setIdle(value) { idle = value; },
 		get tool() { return tool; }, get renders() { return renders; },
 		async close() {
 			const closing = handlers.get("session_shutdown")({}, ctx);
@@ -46,24 +49,318 @@ function harness(mode = "tui", hasUI = true) {
 	};
 }
 
+test("completions during a synchronous tool are merged before the next model request", async () => {
+	const h = harness();
+	try {
+		await h.handlers.get("session_start")({}, h.ctx);
+		h.setIdle(false);
+		for (const command of ["first", "second"]) await h.tool.execute(command, { action: "start", command });
+		h.calls[0].resolve(1);
+		h.calls[1].resolve(2);
+		await flush();
+		assert.equal(h.messages.length, 0, "busy completions must not enter an irrevocable host queue");
+		assert.match(h.widgets.get("background-tasks").render(140).join("\n"), /failed/);
+		const existing = { type: "custom", customType: "other-extension", data: { preserved: true } };
+		const boundary = h.handlers.get("turn_end")({ entries: [existing], continue: true, outcome: "completed" }, h.ctx);
+		assert.equal(boundary.continue, true);
+		assert.equal(boundary.entries.length, 2);
+		assert.deepEqual(boundary.entries[0], existing);
+		assert.equal(boundary.entries[1].details.tasks.length, 2);
+		assert.match(boundary.entries[1].content, /Ended at: 1970-01-01T00:00:01.000Z/);
+		assert.equal(h.handlers.get("agent_before_settle")({ entries: [], outcome: "completed" }, h.ctx), undefined);
+	} finally { await h.close(); }
+});
+
+test("a completion during manual compaction wakes after idle without another agent boundary", async () => {
+	const h = harness("print", false);
+	try {
+		await h.handlers.get("session_start")({}, h.ctx);
+		await h.tool.execute("start", { action: "start", command: "first" });
+		h.setIdle(false);
+		h.calls[0].resolve();
+		await flush();
+		h.clock.advance(0);
+		h.clock.advance(1000);
+		assert.equal(h.messages.length, 0);
+		h.setIdle(true); // Manual compaction succeeds, fails or is cancelled; none emits agent_settled.
+		h.clock.advance(2000);
+		assert.equal(h.messages.length, 1);
+		assert.equal(h.clock.timers.size, 0);
+	} finally { await h.close(); }
+});
+
+test("busy notification checks back off to 30 seconds without expiring unread results", async () => {
+	const h = harness("print", false);
+	try {
+		await h.handlers.get("session_start")({}, h.ctx);
+		h.setIdle(false);
+		await h.tool.execute("start", { action: "start", command: "first" });
+		h.calls[0].resolve();
+		await flush();
+		const started = h.clock.now();
+		h.clock.advance(91000);
+		assert.deepEqual(h.idleChecks.map((time) => time - started), [0, 1000, 3000, 7000, 15000, 31000, 61000, 91000]);
+		assert.equal(h.messages.length, 0);
+		assert.equal(h.clock.timers.size, 1);
+		h.clock.advance(24 * 60 * 60 * 1000);
+		assert.equal(h.messages.length, 0, "no timeout may silently drop the unread batch");
+		assert.equal(h.clock.timers.size, 1);
+		h.setIdle(true);
+		const checks = h.idleChecks.length;
+		h.clock.advance(29999);
+		assert.equal(h.idleChecks.length, checks);
+		h.clock.advance(1);
+		assert.equal(h.messages.length, 1);
+		assert.equal(h.clock.timers.size, 0);
+	} finally { await h.close(); }
+});
+
+test("new completions share the backed-off timer, while tool boundaries deliver immediately and reset backoff", async () => {
+	const h = harness("print", false);
+	try {
+		await h.handlers.get("session_start")({}, h.ctx);
+		h.setIdle(false);
+		await h.tool.execute("start", { action: "start", command: "first" });
+		h.calls[0].resolve();
+		await flush();
+		h.clock.advance(61000);
+		await h.tool.execute("second", { action: "start", command: "second" });
+		h.calls[1].resolve();
+		await flush();
+		assert.equal(h.clock.timers.size, 1);
+		const checks = h.idleChecks.length;
+		h.clock.advance(0);
+		assert.equal(h.idleChecks.length, checks, "a new completion must not restart an active backoff");
+		const boundary = h.handlers.get("turn_end")({ entries: [], outcome: "completed" }, h.ctx);
+		assert.equal(boundary.entries[0].details.tasks.length, 2);
+		assert.equal(h.clock.timers.size, 0, "the boundary must not wait for the 30-second timer");
+		await h.tool.execute("third", { action: "start", command: "third" });
+		h.calls[2].resolve();
+		await flush();
+		h.clock.advance(0);
+		assert.equal(h.idleChecks.length, checks + 1, "a fresh batch starts with an immediate check");
+		h.clock.advance(999);
+		assert.equal(h.idleChecks.length, checks + 1);
+		h.clock.advance(1);
+		assert.equal(h.idleChecks.length, checks + 2, "a fresh batch retries after one second, not thirty");
+	} finally { await h.close(); }
+});
+
+for (const action of ["agent_before_settle", "output", "aborted", "error", "session_shutdown"]) {
+	test(`${action} clears a capped notification retry without stale wakes`, async () => {
+		const h = harness("print", false);
+		try {
+			await h.handlers.get("session_start")({}, h.ctx);
+			h.setIdle(false);
+			const task = (await h.tool.execute("start", { action: "start", command: "first" })).structuredContent.task;
+			h.calls[0].resolve();
+			await flush();
+			h.clock.advance(61000);
+			assert.equal(h.clock.timers.size, 1);
+			if (action === "output") {
+				await h.tool.execute("read", { action, id: task.id });
+			} else if (action === "session_shutdown") {
+				await h.handlers.get(action)({}, h.ctx);
+				await h.handlers.get("session_start")({}, h.ctx);
+			} else {
+				const event = { entries: [], outcome: action === "agent_before_settle" ? "completed" : action };
+				const boundary = h.handlers.get("agent_before_settle")(event, h.ctx);
+				if (action === "agent_before_settle") assert.equal(boundary.entries[0].details.tasks[0].id, task.id);
+				else assert.equal(boundary, undefined);
+			}
+			assert.equal(h.clock.timers.size, 0);
+			h.setIdle(true);
+			const checks = h.idleChecks.length;
+			h.clock.advance(24 * 60 * 60 * 1000);
+			assert.equal(h.idleChecks.length, checks);
+			assert.equal(h.messages.length, 0);
+		} finally { await h.close(); }
+	});
+}
+
+test("failed terminal log reads do not consume pending completion", async () => {
+	const h = harness("print", false);
+	try {
+		await h.handlers.get("session_start")({}, h.ctx);
+		h.setIdle(false);
+		const task = (await h.tool.execute("start", { action: "start", command: "first" })).structuredContent.task;
+		h.calls[0].resolve();
+		await flush();
+		unlinkSync(task.log_path);
+		const result = await h.tool.execute("read", { action: "output", id: task.id });
+		assert.equal(result.isError, true);
+		assert.match(result.structuredContent.error, /Cannot read task log/);
+		const boundary = h.handlers.get("turn_end")({ entries: [], outcome: "completed" }, h.ctx);
+		assert.equal(boundary.entries[0].details.tasks[0].id, task.id);
+	} finally { await h.close(); }
+});
+
+test("terminal output consumed by the agent removes only that pending reminder", async () => {
+	const h = harness();
+	try {
+		await h.handlers.get("session_start")({}, h.ctx);
+		h.setIdle(false);
+		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;
+		await h.tool.execute("running", { action: "output", id: b.id });
+		h.calls[0].resolve(7);
+		h.calls[1].resolve();
+		await flush();
+		await h.tool.execute("list", { action: "list" });
+		await h.commands.get("bg").handler(`output ${b.id}`, h.ctx);
+		const output = await h.tool.execute("read", { action: "output", id: a.id });
+		assert.equal(output.isError, true, "a nonzero command is still a successful log read");
+		const boundary = h.handlers.get("turn_end")({ entries: [], outcome: "completed" }, h.ctx);
+		assert.deepEqual(boundary.entries[0].details.tasks.map((task) => task.id), [b.id]);
+		assert.equal(h.messages.length, 1, "only the user's inspection message was sent");
+	} finally { await h.close(); }
+});
+
+test("idle completions coalesce, but a newly busy session receives them at its next boundary", async () => {
+	const h = harness();
+	try {
+		await h.handlers.get("session_start")({}, h.ctx);
+		for (const command of ["first", "second"]) await h.tool.execute(command, { action: "start", command });
+		h.calls[0].resolve();
+		h.calls[1].resolve(1);
+		await flush();
+		assert.equal(h.messages.length, 0);
+		h.setIdle(false);
+		h.clock.advance(0);
+		assert.equal(h.messages.length, 0, "idle wake must recheck state before sending");
+		const boundary = h.handlers.get("agent_before_settle")({ entries: [], outcome: "completed" }, h.ctx);
+		assert.equal(boundary.entries[0].details.tasks.length, 2);
+		assert.equal(boundary.continue, true);
+		assert.equal(h.handlers.get("turn_end")({ entries: [], outcome: "completed" }, h.ctx), undefined);
+	} finally { await h.close(); }
+});
+
+test("idle wake batches current completions and a terminal read can remove the whole batch", async () => {
+	const h = harness("print", false);
+	try {
+		await h.handlers.get("session_start")({}, h.ctx);
+		for (const command of ["first", "second"]) await h.tool.execute(command, { action: "start", command });
+		h.calls[0].resolve();
+		h.calls[1].resolve(1);
+		await flush();
+		h.clock.advance(0);
+		assert.equal(h.messages.length, 1);
+		assert.equal(h.messages[0].message.details.tasks.length, 2);
+		const task = (await h.tool.execute("third", { action: "start", command: "third" })).structuredContent.task;
+		h.calls[2].resolve();
+		await flush();
+		await h.tool.execute("read", { action: "output", id: task.id });
+		h.clock.advance(0);
+		assert.equal(h.messages.length, 1);
+		assert.equal(h.clock.timers.size, 0);
+	} finally { await h.close(); }
+});
+
+for (const outcome of ["aborted", "error"]) {
+	test(`${outcome} boundaries do not force continuation or replay a scheduled idle wake`, async () => {
+		const h = harness();
+		try {
+			await h.handlers.get("session_start")({}, h.ctx);
+			await h.tool.execute("start", { action: "start", command: "first" });
+			h.calls[0].resolve();
+			await flush();
+			h.setIdle(false);
+			assert.equal(h.handlers.get("turn_end")({ entries: [], outcome }, h.ctx), undefined);
+			assert.equal(h.handlers.get("agent_before_settle")({ entries: [], outcome }, h.ctx), undefined);
+			h.handlers.get("agent_settled")({ aborted: outcome === "aborted" }, h.ctx);
+			h.setIdle(true);
+			h.clock.advance(0);
+			assert.equal(h.messages.length, 0);
+			if (outcome === "aborted") {
+				const resumed = h.handlers.get("before_agent_start")({ messageType: "user", prompt: "Continue" }, h.ctx);
+				assert.equal(resumed.message.details.tasks.length, 1, "the next user prompt receives retained results");
+				assert.equal(h.handlers.get("turn_end")({ entries: [], outcome: "completed" }, h.ctx), undefined);
+				return;
+			}
+			const boundary = h.handlers.get("turn_end")({ entries: [], outcome: "completed" }, h.ctx);
+			assert.equal(boundary.entries[0].details.tasks.length, 1, "unread results remain available");
+		} finally { await h.close(); }
+	});
+}
+
+test("jobs finishing after a user interrupt stay queryable without restarting the agent until the next user prompt", async () => {
+	const h = harness("print", false);
+	try {
+		await h.handlers.get("session_start")({}, h.ctx);
+		const tasks = [];
+		for (const command of ["first", "second"]) {
+			tasks.push((await h.tool.execute(command, { action: "start", command })).structuredContent.task);
+		}
+		h.setIdle(false);
+		h.handlers.get("turn_end")({ entries: [], outcome: "aborted" }, h.ctx);
+		h.handlers.get("agent_before_settle")({ entries: [], outcome: "aborted" }, h.ctx);
+		h.handlers.get("agent_settled")({ aborted: true }, h.ctx);
+		h.setIdle(true);
+		for (const call of h.calls) {
+			assert.equal(call.signal.aborted, false, "interrupting the agent must not cancel accepted jobs");
+			call.resolve(7);
+		}
+		await flush();
+		h.clock.advance(24 * 60 * 60 * 1000);
+		assert.equal(h.messages.length, 0, "late completions must not restart the interrupted agent");
+		assert.equal(h.clock.timers.size, 0);
+		const list = await h.tool.execute("list", { action: "list" });
+		assert.ok(list.structuredContent.tasks.every((task) => task.status === "failed"));
+		assert.equal(h.handlers.get("before_agent_start")?.({ messageType: "custom" }, h.ctx), undefined);
+		assert.equal(h.handlers.get("turn_end")({ entries: [], outcome: "completed" }, h.ctx), undefined, "another extension's run must not release the interrupt");
+		const output = await h.tool.execute("read", { action: "output", id: tasks[0].id });
+		assert.equal(output.structuredContent.task.exit_code, 7);
+		const resumed = h.handlers.get("before_agent_start")({ messageType: "user", prompt: "Continue" }, h.ctx);
+		assert.deepEqual(resumed.message.details.tasks.map((task) => task.id), [tasks[1].id]);
+		assert.equal(h.handlers.get("turn_end")({ entries: [], outcome: "completed" }, h.ctx), undefined);
+		await h.tool.execute("new", { action: "start", command: "new" });
+		h.calls[2].resolve();
+		await flush();
+		h.clock.advance(0);
+		assert.equal(h.messages.length, 1, "the user prompt restores normal automatic delivery");
+	} finally { await h.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.ok(h.tool.description.length < 500);
 		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 () => {
+test("start provides non-blocking next steps in both model text and structured results", async () => {
+	const h = harness();
+	try {
+		await h.handlers.get("session_start")({}, h.ctx);
+		const started = await h.tool.execute("start", { action: "start", command: "sleep 60" });
+		const { task, guidance } = started.structuredContent;
+		assert.equal(task.status, "running");
+		assert.equal(guidance, "完成会自动通知。现在不要查询等待；继续其他独立工作，没有其他工作就结束当前轮，收到通知后再取结果。");
+		assert.ok(started.content[0].text.includes(guidance), "ordinary tool callers must see the same guidance as Codemode");
+		assert.ok(h.tool.description.includes(guidance), "scripts that filter out guidance still discover the lifecycle in the tool description");
+		assert.equal(h.tool.outputSchema.properties.guidance.type, "string");
+		assert.equal(h.tool.outputSchema.required?.includes("guidance") ?? false, false);
+		const list = await h.tool.execute("list", { action: "list" });
+		const output = await h.tool.execute("output", { action: "output", id: task.id });
+		assert.equal(list.structuredContent.guidance, undefined);
+		assert.equal(output.structuredContent.guidance, undefined);
+		h.calls[0].resolve();
+		await flush();
+		h.clock.advance(0);
+		assert.equal(h.messages.filter((entry) => entry.message.customType === "background-task-finished").length, 1);
+	} finally { await h.close(); }
+});
+
+test("tools, commands, widget and idle notifications share the same session jobs", async () => {
 	const h = harness();
 	try {
 		await h.handlers.get("session_start")({}, h.ctx);
@@ -91,9 +388,10 @@ test("tools, commands, widget and followUp share the same session jobs", async (
 
 		h.calls[0].resolve(7);
 		await flush();
+		h.clock.advance(0);
 		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.deepEqual(completed[0].options, { triggerTurn: true, deliverAs: "steer" });
 		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/);
@@ -117,6 +415,7 @@ test("cancel and shutdown are idempotent; new sessions cannot receive old comple
 		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");
+		h.clock.advance(0);
 		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);
@@ -145,9 +444,10 @@ for (const [mode, hasUI] of [["rpc", true], ["print", false], ["json", false]])
 			if (hasUI) assert.match(h.statuses.get("background-tasks"), /1\/2/);
 			h.calls[0].resolve();
 			await flush();
+			h.clock.advance(0);
 			assert.equal(h.clock.timers.size, 0);
 			assert.equal(h.statuses.has("background-tasks"), false);
-			assert.equal(h.messages.at(-1).options.deliverAs, "followUp");
+			assert.equal(h.messages.at(-1).options.deliverAs, "steer");
 		} finally { await h.close(); }
 	});
 }
@@ -157,7 +457,7 @@ test("bad actions, irrelevant fields, aborted acceptance and command syntax fail
 	try {
 		await h.handlers.get("session_start")({}, h.ctx);
 		for (const params of [
-			{ action: "other" }, { action: "start" }, { action: "list", command: "ignored" },
+			{ action: "other" }, { action: "notifications", enabled: false }, { action: "start" }, { action: "list", command: "ignored" },
 			{ action: "output" }, { action: "cancel", id: "unknown" },
 			{ action: "start", command: "x", id: "irrelevant" },
 		]) {

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

@@ -0,0 +1,77 @@
+// A blocking tool stands in for a synchronous subagent. Pi queues and shell jobs are real.
+import { appendFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+export default function (pi: ExtensionAPI) {
+	const record = (entry: unknown) => appendFileSync(process.env.BG_NOTIFICATION_EVENTS!, JSON.stringify(entry) + "\n");
+	pi.registerTool({
+		name: "synchronous_subagent_fixture", label: "Synchronous subagent fixture",
+		description: "Wait for four real shell jobs while holding one synchronous tool call open.",
+		parameters: Type.Object({ reads: Type.Number() }),
+		async execute(_id, { reads }, _signal, _update, ctx) {
+			record({ event: "waiting" });
+			writeFileSync(join(ctx.cwd, "release"), "ready");
+			const list = async () => (await ctx.executeTool("background_task", { action: "list" })).result.structuredContent as any;
+			const wait = async () => {
+				for (let i = 0; i < 1000; i++) {
+					const tasks = await list();
+					if (tasks.running === 0) return tasks.tasks;
+					await delay(5);
+				}
+				throw new Error("Fixture shell jobs did not finish");
+			};
+			await wait();
+			for (let i = 0; i < 2; i++) await ctx.executeTool("background_task", {
+				action: "start", command: "printf 'second wave\\n'; exit 7", description: `second wave ${i}`, timeout: 10,
+			});
+			const tasks = await wait();
+			for (const task of tasks.slice(0, reads)) await ctx.executeTool("background_task", { action: "output", id: task.id });
+			record({ event: "returned", tasks, consumed: tasks.slice(0, reads).map((task: any) => task.id) });
+			return { content: [{ type: "text", text: "Synchronous subagent returned; final build report is ready." }], details: undefined };
+		},
+	});
+	let requests = 0;
+	pi.registerProvider("bg-notifications", {
+		name: "Offline notification fixture", baseUrl: "http://127.0.0.1:1", api: "bg-notifications", apiKey: "fixture-not-a-secret",
+		models: [{ id: "deterministic", name: "Offline notification fixture", reasoning: false, input: ["text"], contextWindow: 128000, maxTokens: 4096, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } }],
+		streamSimple(model, context) {
+			const stream = createAssistantMessageEventStream();
+			queueMicrotask(() => {
+				requests++;
+				record({ event: "request", number: requests, messages: context.messages });
+				const direct = process.env.BG_NOTIFICATION_MODE === "direct";
+				const toolTurn = requests === 1 || (direct && requests === 2);
+				const message: any = { role: "assistant", api: model.api, provider: model.provider, model: model.id, timestamp: Date.now(), content: [], stopReason: toolTurn ? "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 (toolTurn) {
+					const reads = Number(process.env.BG_NOTIFICATION_READS);
+					if (direct && requests === 1) {
+						for (let i = 0; i < 2; i++) message.content.push({ type: "toolCall", id: `direct-start-${i}`, name: "background_task", arguments: {
+							action: "start", command: "while [ ! -f release ]; do sleep 0.01; done; printf 'first wave\\n'; exit 7", description: `first wave ${i}`, timeout: 10,
+						} });
+					} else if (direct) message.content.push({ type: "toolCall", id: "direct-blocking-tool", name: "synchronous_subagent_fixture", arguments: { reads } });
+					else {
+						const code = `for (let i = 0; i < 2; i++) text(await tools.background_task({ action: "start", command: "while [ ! -f release ]; do sleep 0.01; done; printf 'first wave\\\\n'; exit 7", description: "first wave " + i, timeout: 10 }));\ntext(await tools.synchronous_subagent_fixture({ reads: ${reads} }));`;
+						message.content.push({ type: "toolCall", id: "notification-fixture", name: "codemode", arguments: { code } });
+					}
+					for (let i = 0; i < message.content.length; i++) {
+						stream.push({ type: "toolcall_start", contentIndex: i, partial: message });
+						stream.push({ type: "toolcall_end", contentIndex: i, toolCall: message.content[i], partial: message });
+					}
+				} else {
+					message.content.push({ type: "text", text: "FINAL_REPORT" });
+					stream.push({ type: "text_start", contentIndex: 0, partial: message });
+					stream.push({ type: "text_delta", contentIndex: 0, delta: "FINAL_REPORT", partial: message });
+					stream.push({ type: "text_end", contentIndex: 0, content: "FINAL_REPORT", partial: message });
+				}
+				stream.push({ type: "done", reason: message.stopReason, message });
+			});
+			return stream;
+		},
+	});
+}

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

@@ -8,6 +8,7 @@ export default function (pi: ExtensionAPI) {
 		if (process.env.BG_SMOKE_EVENTS) appendFileSync(process.env.BG_SMOKE_EVENTS, JSON.stringify(entry) + "\n");
 	};
 	let sequence = 0;
+	const observedNotifications = new Set<string>();
 	pi.registerProvider("bg-fixture", {
 		name: "Offline background-task fixture", baseUrl: "http://127.0.0.1:1", api: "bg-fixture",
 		apiKey: "fixture-not-a-secret",
@@ -17,7 +18,9 @@ export default function (pi: ExtensionAPI) {
 			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) });
+				const tools = getCurrentTools(context.messages);
+				record({ event: "request", lastRole: last?.role, text: text.slice(0, 2000), tools: tools.map((tool) => tool.name),
+					backgroundDescription: tools.find((tool) => tool.name === "background_task")?.description });
 				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 });
@@ -32,6 +35,7 @@ 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 }));`;
+					else if (text.includes("SMOKE_GUIDANCE")) code = `text(await tools.background_task({ action: "start", command: "sleep 300", description: "Guidance 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 } } };
@@ -41,7 +45,7 @@ text({ status: result.task.status, output: result.output });`;
 					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.";
+					const reply = text.includes("[Background task finished]") ? "BACKGROUND_NOTIFICATION_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 });
@@ -57,7 +61,13 @@ text({ status: result.task.status, output: result.output });`;
 		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 });
+	pi.on("context", (_event, ctx) => {
+		// Both boundary entries and idle messages are persisted before the provider request.
+		// Key by entry ID so two actual notifications for the same tasks remain observable.
+		for (const entry of ctx.sessionManager.getBranch()) {
+			if (entry.type !== "custom_message" || observedNotifications.has(entry.id)) continue;
+			observedNotifications.add(entry.id);
+			record({ event: "custom", entryId: entry.id, type: entry.customType, details: entry.details });
+		}
 	});
 }

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

@@ -0,0 +1,140 @@
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { test } from "node:test";
+import { pathToFileURL } from "node:url";
+import "./runtime.mjs";
+
+const { createAgentSession, DefaultResourceLoader, ModelRuntime, SessionManager, SettingsManager } = await import("@earendil-works/pi-coding-agent");
+const { createAssistantMessageEventStream } = await import("@earendil-works/pi-ai");
+const { Type } = await import("typebox");
+const { default: register } = await import(process.env.BG_TEST_EXTENSION
+	? pathToFileURL(process.env.BG_TEST_EXTENSION).href : new URL("../extensions/background-tasks.ts", import.meta.url).href);
+
+for (const timing of ["before interrupt", "after interrupt", "after active compaction"]) {
+	test(`real Pi completion ${timing} stays stopped until the next user prompt, then delivers once`, { timeout: 20000 }, async (t) => {
+		const directory = mkdtempSync(join(tmpdir(), "pi-bg-interrupt-"));
+		const release = join(directory, "release");
+		const exited = join(directory, "exited");
+		const requests = [], settlements = [], errors = [];
+		let session, task, output, holding = false, summaries = 0;
+		const waitFor = async (check, label) => {
+			for (let i = 0; i < 1000; i++) {
+				if (check()) return;
+				await delay(10);
+			}
+			throw new Error(`Timed out waiting for ${label}`);
+		};
+		try {
+			const modelRuntime = await ModelRuntime.create({ authPath: join(directory, "auth.json"), modelsPath: join(directory, "models.json"), refreshOnCreate: false });
+			modelRuntime.registerProvider("bg-interrupt", {
+				name: "Offline interrupt fixture", baseUrl: "http://127.0.0.1:1", api: "bg-interrupt", apiKey: "fixture-not-a-secret",
+				models: [{ id: "deterministic", name: "Offline fixture", reasoning: false, input: ["text"], contextWindow: 128000, maxTokens: 4096, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } }],
+				streamSimple(model, context) {
+					const compacting = session.isCompacting;
+					if (compacting) summaries++;
+					else requests.push(context.messages);
+					const stream = createAssistantMessageEventStream();
+					queueMicrotask(() => {
+						const message = { role: "assistant", api: model.api, provider: model.provider, model: model.id, timestamp: Date.now(), content: [], stopReason: "toolUse",
+							usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } } };
+						if (compacting) {
+							message.stopReason = "stop";
+							message.content.push({ type: "text", text: "## Goal\nKeep the interrupted agent stopped. A shell job remains owned by this session." });
+						} else if (requests.length === 1) message.content.push({ type: "toolCall", id: "start-job", name: "background_task", arguments: {
+							action: "start", command: "while [ ! -f release ]; do sleep 0.01; done; printf 'late shell result\\n'; printf done > exited; exit 7", timeout: 10,
+						} });
+						else if (requests.length === 2) message.content.push({ type: "toolCall", id: "hold-turn", name: "interrupt_fixture", arguments: {} });
+						else if (requests.length === 3) message.content.push({ type: "toolCall", id: "read-result", name: "background_task", arguments: { action: "output", id: task.id } });
+						else {
+							message.stopReason = "stop";
+							message.content.push({ type: "text", text: "RESUMED_RESULT_ACK" });
+						}
+						stream.push({ type: "start", partial: message });
+						stream.push({ type: "done", reason: message.stopReason, message });
+					});
+					return stream;
+				},
+			});
+			const settingsManager = SettingsManager.inMemory({ compaction: { enabled: false, keepRecentTokens: 128 }, retry: { enabled: false }, cacheWarming: "off" });
+			const resourceLoader = new DefaultResourceLoader({
+				cwd: directory, agentDir: directory, settingsManager,
+				noExtensions: true, noSkills: true, noPromptTemplates: true, noThemes: true, noContextFiles: true,
+				extensionFactories: [register, (pi) => {
+					pi.on("agent_settled", (event) => { settlements.push(event.aborted); });
+					pi.registerTool({
+						name: "interrupt_fixture", label: "Interrupt fixture", description: "Hold a real tool until the user interrupts the agent.",
+						parameters: Type.Object({}),
+						async execute(_id, _params, signal) {
+							holding = true;
+							assert.ok(signal);
+							if (!signal.aborted) await new Promise((resolve) => signal.addEventListener("abort", resolve, { once: true }));
+							return { content: [{ type: "text", text: "User interrupted the held tool." }], details: undefined };
+						},
+					});
+				}],
+			});
+			await resourceLoader.reload();
+			const created = await createAgentSession({ cwd: directory, agentDir: directory, modelRuntime, model: modelRuntime.getModel("bg-interrupt", "deterministic"), thinkingLevel: "off", resourceLoader, settingsManager, sessionManager: SessionManager.inMemory(directory), tools: ["background_task", "interrupt_fixture"] });
+			session = created.session;
+			assert.deepEqual(created.extensionsResult.errors, []);
+			session.extensionRunner.onError((error) => errors.push(error));
+			session.subscribe((event) => {
+				if (event.type !== "tool_execution_end" || event.toolName !== "background_task") return;
+				if (event.result.structuredContent.action === "start") task = event.result.structuredContent.task;
+				else if (event.result.structuredContent.action === "output") output = event.result.structuredContent;
+			});
+			await session.bindExtensions({});
+			const prompting = session.prompt("Start a job and hold the agent so the user can interrupt. " + "Prior history to compact. ".repeat(200));
+			await waitFor(() => holding, "the real blocking tool");
+			assert.equal(task.status, "running");
+			if (timing === "before interrupt") {
+				writeFileSync(release, "finish while the tool is held");
+				await waitFor(() => existsSync(exited), "the background shell exit marker");
+				await delay(100);
+			}
+			const interruptRequestedAt = Date.now();
+			if (timing === "after active compaction") {
+				await session.compact();
+				assert.equal(summaries, 1, "manual compaction must run its native summary after interrupting the active agent");
+			} else await session.abort();
+			await prompting;
+			const interruptedAt = Date.now();
+			assert.deepEqual(settlements, [true], "native settlement must confirm the user interrupt");
+			assert.equal(session.isIdle, true);
+			writeFileSync(release, "finish after user interruption");
+			await waitFor(() => existsSync(exited), "the background shell surviving the interrupt");
+			await delay(1250);
+			assert.equal(requests.length, 2, "late completion must not start a model request");
+			assert.match(readFileSync(task.log_path, "utf8"), /late shell result/);
+			assert.equal(session.isIdle, true);
+			await session.prompt("Continue and inspect the completed job.");
+			assert.equal(requests.length, 4);
+			const resumedContext = JSON.stringify(requests[2]);
+			assert.equal((resumedContext.match(/\[Background task finished\]/g) ?? []).length, 1, "retained completion enters context before the resumed model request");
+			assert.ok(resumedContext.includes(task.id));
+			assert.equal(output.task.exit_code, 7);
+			assert.equal(output.output, "late shell result\n");
+			await delay(50);
+			assert.equal(requests.length, 4, "consumed completion must not trigger another turn");
+			const notifications = session.sessionManager.getBranch().filter((entry) => entry.type === "custom_message" && entry.customType === "background-task-finished");
+			assert.equal(notifications.length, 1);
+			assert.equal(notifications[0].details.tasks[0].id, task.id);
+			assert.equal(notifications[0].details.tasks[0].status, "failed");
+			if (timing === "before interrupt") assert.ok(notifications[0].details.tasks[0].ended_at <= interruptRequestedAt);
+			else assert.ok(notifications[0].details.tasks[0].ended_at >= interruptedAt);
+			assert.equal(session.getLastAssistantText(), "RESUMED_RESULT_ACK");
+			assert.deepEqual(errors, []);
+			t.diagnostic(JSON.stringify({ timing, requestsBeforeResume: 2, requestsAfterResume: 4, pendingDeliveredOnce: true, lateResultRecovered: true }));
+		} finally {
+			if (session) {
+				await session.abort();
+				await session.extensionRunner.emit({ type: "session_shutdown", reason: "quit" });
+				session.dispose();
+			}
+			rmSync(directory, { recursive: true, force: true });
+		}
+	});
+}