gentle-pi 3.3.0 → 3.5.0

package/tests/background-cache-warming.test.ts

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { readFileSync } from "node:fs";
+import { installBackgroundCacheWarming, type WarmingState } from "../lib/background-cache-warming.ts";
+
+test("native warming decisions use only current owned live background work", () => {
+	let handler: Parameters<Parameters<typeof installBackgroundCacheWarming>[0]["on"]>[1];
+	let state: WarmingState = { sessionId: "parent", ownedTaskIds: new Set(["task"]), tasks: [
+		{ id: "task", parentSessionId: "parent", mode: "background", status: "queued" },
+	] };
+	installBackgroundCacheWarming({ on(event, callback) {
+		assert.equal(event, "cache_warming_decision");
+		handler = callback;
+	} }, () => state);
+	const candidate = { warmCost: 0.01, missCost: 0.1, continuationProbability: 0.15, action: "stop" as const };
+	assert.deepEqual(handler!(candidate), { action: "warm" });
+	state.tasks[0].status = "running";
+	assert.deepEqual(handler!(candidate), { action: "warm" });
+	for (const status of ["waiting", "completed", "failed", "cancelled", "timed_out"] as const) {
+		state.tasks[0].status = status;
+		assert.equal(handler!(candidate), undefined, status);
+	}
+	state.tasks[0].status = "running";
+	for (const patch of [
+		{ sessionId: undefined }, { sessionId: "other" }, { ownedTaskIds: new Set<string>() },
+		{ tasks: [] }, { tasks: [{ ...state.tasks[0], mode: "task" }] },
+	]) {
+		const original = state;
+		state = { ...state, ...patch };
+		assert.equal(handler!(candidate), undefined);
+		state = original;
+	}
+	for (const warmCost of [0.06, 1, NaN, Infinity, -1]) {
+		assert.deepEqual(handler!({ ...candidate, warmCost }), { action: "stop" });
+	}
+	for (const missCost of [0, -1, NaN, Infinity]) {
+		assert.deepEqual(handler!({ ...candidate, missCost }), { action: "stop" });
+	}
+	assert.deepEqual(handler!({ ...candidate, warmCost: 0, missCost: 0.05 }), { action: "warm" });
+	assert.deepEqual(handler!({ ...candidate, warmCost: 0, missCost: 0.049 }), { action: "stop" });
+	state.tasks = [];
+	assert.equal(handler!({ ...candidate, action: "warm" }), undefined, "ordinary idle keeps native action");
+});
+
+// Supplemental architecture guard; the extension lifecycle is exercised in gentle-agents.test.ts.
+test("warming helper has no maintenance capabilities", () => {
+	const helper = readFileSync(new URL("../lib/background-cache-warming.ts", import.meta.url), "utf8");
+	assert.doesNotMatch(helper, /setTimeout|setInterval|sendMessage|sendUserMessage|subagent_|runner\./);
+});
+
+test("background prompt prohibits cache polling and documents explicit native idle opt-in", () => {
+	const prompt = readFileSync(new URL("../assets/orchestrator-delegation.md", import.meta.url), "utf8");
+	assert.match(prompt, /completion or cache maintenance/);
+	assert.match(prompt, /user-requested inspection, relevant scope change, input request, or suspected abnormal behavior/);
+	assert.match(prompt, /Never relaunch equivalent work merely because it is queued or running/);
+	const docs = readFileSync(new URL("../docs/readme-reference.md", import.meta.url), "utf8");
+	assert.match(docs, /"cacheWarming": "idle"/);
+	assert.match(docs, /\$0\.05/);
+	assert.match(docs, /"streaming".*no idle decision/s);
+});

package/tests/background-subagents.test.ts

@@ -530,6 +530,28 @@ function notifyContext(
 	} as unknown as ExtensionContext;
 }
 
+/**
+ * The same minimal context as `notifyContext`, but interactive: `hasUI` is true
+ * and `ui.select` answers the command's no-argument menu. `notifyContext` stays
+ * `hasUI: false` so every existing sub-action test keeps the non-menu path.
+ */
+function selectingContext(
+	cwd: string,
+	notices: Array<{ message: string; type?: string }>,
+	select: (title: string, options: string[]) => Promise<string | undefined>,
+): ExtensionContext {
+	return {
+		cwd,
+		hasUI: true,
+		ui: {
+			notify: (message: string, type?: string) => {
+				notices.push({ message, type });
+			},
+			select,
+		},
+	} as unknown as ExtensionContext;
+}
+
 /** Point the command's global config home at a scratch dir, never at ~/.pi. */
 function scopedEnv(t: TestContext, values: Record<string, string | undefined>): void {
 	const previous = new Map<string, string | undefined>();
@@ -590,6 +612,52 @@ test("no argument reports the effective policy, the deciding default, and the ca
 	);
 });
 
+test("no argument opens a selectable menu and applies the chosen sub-action", async (t) => {
+	const cwd = makeScratch("gp-bg-cmd-select-");
+	const configHome = join(makeScratch("gp-bg-home-"), "gentle-ai");
+	const globalFile = join(configHome, "background-subagents.json");
+	scopedEnv(t, {
+		GENTLE_PI_CONFIG_HOME: configHome,
+		GENTLE_PI_BACKGROUND_SUBAGENTS: undefined,
+	});
+	const command = registeredCommands().get("gentle:background-subagents");
+	assert.ok(command, "gentle:background-subagents must be registered");
+
+	// A dismissed menu (undefined selection) reports nothing and writes nothing.
+	// It runs first so the untouched config home can prove the no-write: a second
+	// scopedEnv save point in one test would restore out of order at teardown.
+	const dismissed: Array<{ message: string; type?: string }> = [];
+	await command!.handler("", selectingContext(cwd, dismissed, async () => undefined));
+	assert.equal(dismissed.length, 0, "a dismissed menu reports nothing");
+	assert.equal(existsSync(globalFile), false, "a dismissed menu writes no file");
+
+	// Choosing "enable" writes the global file and reports exactly once, in the
+	// same shape the direct `enable` sub-action already reports.
+	const notices: Array<{ message: string; type?: string }> = [];
+	await command!.handler(
+		"",
+		selectingContext(cwd, notices, async (title, options) => {
+			assert.equal(title, "Background subagents policy");
+			assert.deepEqual(options, ["status", "enable", "disable"]);
+			return "enable";
+		}),
+	);
+	assert.equal(notices.length, 1, "one invocation reports exactly once");
+	assert.equal(notices[0]!.type, "info");
+	assert.equal(
+		notices[0]!.message,
+		[
+			`background subagents: on (decided by global file ${globalFile}; capability: absent)`,
+			`Wrote on to the global file ${globalFile}.`,
+			"Resolution order (first hit wins): project file, global file, GENTLE_PI_BACKGROUND_SUBAGENTS, built-in default off.",
+		].join("\n"),
+	);
+	assert.deepEqual(JSON.parse(readFileSync(globalFile, "utf8")), {
+		schema: "gentle-pi.background-subagents/v1",
+		policy: "on",
+	});
+});
+
 test("status names the project file that decided and the global file it shadows", async (t) => {
 	const cwd = makeScratch("gp-bg-cmd-project-");
 	const configHome = join(makeScratch("gp-bg-home-"), "gentle-ai");

package/tests/command-palette.test.ts

@@ -32,6 +32,14 @@ function createPalette(groups: readonly CommandPaletteGroup[], theme?: CommandPa
 	return { palette, results };
 }
 
+test("animations is discoverable under Configuration with its live description", () => {
+	const groups = buildCommandPaletteGroups([{ name: "gentle:animations", description: "status|quality|performance|potato" }], {});
+	assert.equal(groups[0]?.title, "Configuration");
+	assert.equal(groups[0]?.items[0]?.command, "gentle:animations");
+	assert.match(groups[0]?.items[0]?.label ?? "", /[Aa]nimation/);
+	assert.equal(groups[0]?.items[0]?.description, "status|quality|performance|potato");
+});
+
 // --- rankPaletteGroups -------------------------------------------------------
 
 test("rankPaletteGroups ranks label-prefix, label-contains, label-subsequence, command-contains, then description-contains", () => {
@@ -337,6 +345,7 @@ test("COMMAND_PALETTE_CATALOG matches the curated command set, in order", () =>
 		"gentle:review-mode",
 		"gentle:background-subagents",
 		"gentle:double-esc-cancel",
+		"gentle:animations",
 		"gentle:telemetry",
 		"gentle:banner",
 		"gentle:banner-color",

package/tests/gentle-agents.test.ts

@@ -147,8 +147,10 @@ function fakePi() {
 		await fire("session_shutdown", ctx, { reason: "quit" });
 	};
 	const fire = async (event: string, ctx: ExtensionContext, payload: unknown = {}) => {
+		const results: unknown[] = [];
 		try {
-			for (const handler of handlers.get(event) ?? []) await handler(payload, ctx);
+			for (const handler of handlers.get(event) ?? []) results.push(await handler(payload, ctx));
+			return results;
 		} finally {
 			if (event === "session_start") {
 				activeSession = ctx;
@@ -237,6 +239,73 @@ function deps(): { deps: Partial<AgentsDeps>; children: FakeChild[]; spawned: st
 	};
 }
 
+test("cache warming follows actual Gentle Agents ownership and completion lifecycle", async (t) => {
+	const h = fakePi();
+	const runtime = deps();
+	let store: TaskStore | undefined;
+	const list = TaskStore.prototype.list;
+	t.mock.method(TaskStore.prototype, "list", function (this: TaskStore, ...args: Parameters<TaskStore["list"]>) {
+		store = this;
+		return list.apply(this, args);
+	});
+	const scheduled = t.mock.fn(() => () => {});
+	runtime.deps.schedule = scheduled;
+	gentleAgents(h.pi, {}, runtime.deps);
+	const { ctx } = fakeContext();
+	let sessionId = "warming-parent";
+	ctx.sessionManager.getSessionId = () => sessionId;
+	await h.fire("session_start", ctx);
+	const candidate = { type: "cache_warming_decision", warmCost: 0.01, missCost: 0.1, continuationProbability: 0.15, action: "stop" };
+	const run = t.mock.method(AgentRunner.prototype, "run");
+	const status = t.mock.method(h.tools.get("subagent_status")!, "execute");
+	const result = t.mock.method(h.tools.get("subagent_result")!, "execute");
+	const decide = async (expected: unknown) => {
+		const before = [runtime.spawned.length, run.mock.callCount(), scheduled.mock.callCount(), status.mock.callCount(), result.mock.callCount()];
+		const sent = [...h.sent], entries = [...h.entries];
+		const childTraffic = runtime.children.map(child => JSON.stringify([child.written, child.sent, child.killed]));
+		const timeout = t.mock.method(globalThis, "setTimeout");
+		const interval = t.mock.method(globalThis, "setInterval");
+		try {
+			assert.deepEqual(await h.fire("cache_warming_decision", ctx, candidate), [expected]);
+			assert.equal(timeout.mock.callCount(), 0);
+			assert.equal(interval.mock.callCount(), 0);
+		} finally { timeout.mock.restore(); interval.mock.restore(); }
+		assert.deepEqual([runtime.spawned.length, run.mock.callCount(), scheduled.mock.callCount(), status.mock.callCount(), result.mock.callCount()], before);
+		assert.deepEqual(h.sent, sent, "no maintenance or duplicate completion message");
+		assert.deepEqual(h.entries, entries, "no maintenance context entry");
+		assert.deepEqual(runtime.children.map(child => JSON.stringify([child.written, child.sent, child.killed])), childTraffic, "no child inspection, steering, or cancellation");
+	};
+	await decide(undefined);
+	const launch = await h.tools.get("subagent_run")!.execute("warming-launch", { agent: "explore", task: "Map warming", mode: "background" }, undefined, undefined, ctx);
+	await tick();
+	const taskId = (launch.details.gentleAgents as { taskId: string }).taskId;
+	assert.equal(runtime.children.length, 1);
+	await decide({ action: "warm" });
+	// The same live owned child is foreign when the active session changes.
+	sessionId = "other-parent";
+	await decide(undefined);
+	sessionId = "warming-parent";
+	await decide({ action: "warm" });
+	runtime.children[0].emit({ type: "agent_end", messages: [{ role: "assistant", content: [{ type: "text", text: "mapped" }] }] });
+	await tick();
+	await decide({ action: "warm" });
+	assert.equal(h.sent.length, 0, "agent_end is not settlement");
+	runtime.children[0].emit({ type: "agent_settled" });
+	await tick();
+	await decide(undefined);
+	assert.equal(h.sent.length, 1);
+	assert.equal(h.sent[0].message.customType, "gentle-agents.result");
+	assert.match(JSON.stringify(h.sent[0].message), new RegExp(taskId));
+	assert.equal(h.sent[0].options.triggerTurn, true);
+	assert.equal(run.mock.callCount(), 1, "warming never launches equivalent work");
+	// Seed the actual history-restore path with a stale live-looking record:
+	// sharing the parent ID and running status must not confer ownership.
+	assert.equal(store!.restore({ ...store!.get(taskId)!, id: "warming-restored", status: TASK_STATUS.RUNNING }, emptyThread()), true);
+	await decide(undefined);
+	await h.fire("session_shutdown", ctx);
+	await decide(undefined);
+});
+
 const PRINT_BACKGROUND_ERROR = "Background subagents are unavailable in print mode: pi -p exits before a parent session can receive results. Use task mode, RPC mode, or interactive Pi.";
 
 for (const continuation of [false, true]) {
@@ -310,6 +379,96 @@ for (const mode of ["print", "tui", "rpc"] as const) {
 	});
 }
 
+/** Controllable fake for `AgentsDeps.schedule`: records every scheduled callback instead of running it, so a test can fire the RPC publisher's coalescing window deterministically. */
+function fakeScheduler() {
+	const pending: Array<{ id: number; fn: () => void }> = [];
+	let nextId = 0;
+	return {
+		schedule: (fn: () => void, _ms: number) => {
+			const id = nextId++;
+			pending.push({ id, fn });
+			return () => {
+				const index = pending.findIndex((entry) => entry.id === id);
+				if (index !== -1) pending.splice(index, 1);
+			};
+		},
+		flushAll: () => {
+			const due = pending.splice(0, pending.length);
+			for (const entry of due) entry.fn();
+		},
+	};
+}
+
+for (const scenario of [
+	{ label: "an interactive RPC host", mode: "rpc", env: { PATH: "/bin", GENTLE_SHELL_INTERACTIVE_HOST: "1" }, expectPublish: true },
+	{ label: "plain RPC without the interactive-host variable", mode: "rpc", env: { PATH: "/bin" }, expectPublish: false },
+	{ label: "TUI", mode: "tui", env: { PATH: "/bin" }, expectPublish: false },
+] as const) {
+	test(`gentle-agents publishes the live activity payload through setWidget only on ${scenario.label}`, async (t) => {
+		const h = fakePi();
+		const runtime = deps();
+		const scheduler = fakeScheduler();
+		runtime.deps.schedule = scheduler.schedule;
+		runtime.deps.env = scenario.env;
+		gentleAgents(h.pi, {}, runtime.deps);
+		const { ctx } = fakeContext();
+		Object.assign(ctx, { mode: scenario.mode, hasUI: scenario.mode === "tui" || scenario.mode === "rpc" });
+		const setWidget = t.mock.method(ctx.ui, "setWidget");
+
+		await h.fire("session_start", ctx);
+		scheduler.flushAll(); // consume the publisher's own start-time frame, if any
+		setWidget.mock.resetCalls();
+
+		await h.tools.get("subagent_run")!.execute("control", { agent: "explore", task: "Map", mode: "background" }, undefined, undefined, ctx);
+		scheduler.flushAll();
+
+		// The TUI card's own setWidget call always carries a component-factory
+		// function, never an array; only the RPC publisher pushes an array.
+		const activityCalls = setWidget.mock.calls.filter((call) => call.arguments[0] === "gentle-agents" && Array.isArray(call.arguments[1]));
+		if (!scenario.expectPublish) {
+			assert.deepEqual(activityCalls, [], "no array-shaped setWidget push outside an interactive RPC host");
+			return;
+		}
+		assert.equal(activityCalls.length, 1, "one push per coalescing window");
+		// The fake `ui.setWidget` types `content` as the TUI-only component factory;
+		// the RPC publisher instead calls it with a plain `string[]` (real pi's
+		// RPC-mode contract), which needs an unknown-mediated cast here.
+		const [key, lines] = activityCalls[0]!.arguments as unknown as [string, string[]];
+		assert.equal(key, "gentle-agents");
+		assert.equal(lines.length, 1);
+		const activity = JSON.parse(lines[0]!) as { schema: string; tasks: Array<{ summary: { id: string } }> };
+		assert.equal(activity.schema, "gentle-agents.activity/v1");
+		assert.ok(activity.tasks.some((task) => typeof task.summary.id === "string" && task.summary.id.length > 0), "the newly launched task must be in the payload");
+	});
+}
+
+test("gentle-agents notifies once, deduplicated, when the RPC activity publisher's setWidget throws", async (t) => {
+	const h = fakePi();
+	const runtime = deps();
+	const scheduler = fakeScheduler();
+	runtime.deps.schedule = scheduler.schedule;
+	runtime.deps.env = { PATH: "/bin", GENTLE_SHELL_INTERACTIVE_HOST: "1" };
+	gentleAgents(h.pi, {}, runtime.deps);
+	const { ctx } = fakeContext();
+	Object.assign(ctx, { mode: "rpc", hasUI: true });
+	const notify = t.mock.method(ctx.ui, "notify");
+	// Only the publisher's array-shaped push fails; the TUI card's own
+	// component-factory push (`showWidget`) must stay untouched.
+	ctx.ui.setWidget = ((_key: string, content: unknown) => {
+		if (Array.isArray(content)) throw new Error("boom");
+	}) as typeof ctx.ui.setWidget;
+
+	await h.fire("session_start", ctx);
+	scheduler.flushAll(); // the publisher's own start-time frame fails: one notify
+
+	await h.tools.get("subagent_run")!.execute("control", { agent: "explore", task: "Map", mode: "background" }, undefined, undefined, ctx);
+	scheduler.flushAll(); // a second flush with the same recurring failure must not notify again
+
+	assert.equal(notify.mock.callCount(), 1, "the same recurring setWidget failure is deduplicated to one notify per session");
+	assert.match(String(notify.mock.calls[0]?.arguments[0]), /boom/);
+	assert.equal(notify.mock.calls[0]?.arguments[1], "warning");
+});
+
 test("all nine subagent registrations own their transcript shell", () => {
 	const { pi, tools } = fakePi();
 	gentleAgents(pi, {}, deps().deps);
@@ -1838,7 +1997,7 @@ test("default Node spawn adapter distinguishes IPC-only and permission-capable c
 			const { ctx } = fakeContext();
 			(ctx.sessionManager as unknown as { getCwd(): string }).getCwd = () => sessionCwd;
 			await h.fire("session_start", ctx);
-			shutdown.push(() => h.fire("session_shutdown", ctx));
+			shutdown.push(async () => { await h.fire("session_shutdown", ctx); });
 			return { h, ctx, result: h.tools.get("subagent_run")!.execute(`spawn-${mode}`, { agent: "explore", task: `Capture ${mode}`, mode }, undefined, undefined, ctx) };
 		};
 		const task = await launch("task", { PATH: "/bin", FIXTURE: "task" });

package/tests/gentle-ai-binary.test.ts

@@ -97,7 +97,7 @@ async function writeWindowsSourceBinary(packageRoot: string): Promise<{ binaryPa
 		method: "go-sumdb-source-build",
 		package: "github.com/gentleman-programming/gentle-ai/v3/cmd/gentle-ai",
 		module: "github.com/gentleman-programming/gentle-ai/v3",
-		tag: "v3.4.0",
+		tag: "v3.5.0",
 		architecture: process.arch === "x64" ? "x64" : "arm64",
 		binarySha256: createHash("sha256").update(binary).digest("hex"),
 		moduleChecksum: GENTLE_AI_WINDOWS_SOURCE_MODULE_CHECKSUM,