gentle-pi 2.3.0 → 2.5.0

package/tests/agents-protocol.test.ts

@@ -0,0 +1,153 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+	applyTaskEvent,
+	emptyThread,
+	normalizeRpcEvent,
+	TASK_EVENT,
+	TASK_STATUS,
+	taskLabel,
+	TaskStore,
+	THREAD_ITEM,
+	type TaskRecord,
+} from "../lib/agents-protocol.ts";
+
+// Gentle Agents protocol: the child pi process streams RPC events; the host
+// normalizes them into small typed deltas, applies them to an append-only
+// thread, and notifies only the listeners of the task that changed.
+
+function record(overrides: Partial<TaskRecord> = {}): TaskRecord {
+	return {
+		id: "t1",
+		agent: "gentle-ai-explore",
+		mode: "task",
+		prompt: "Map the repo",
+		label: "map the repo",
+		cwd: "/repo",
+		parentSessionId: "s1",
+		status: TASK_STATUS.QUEUED,
+		createdAt: 1000,
+		startedAt: null,
+		endedAt: null,
+		model: "openai-codex/gpt-5.6-terra",
+		thinking: "high",
+		sessionPath: null,
+		error: null,
+		result: null,
+		lastStep: "queued",
+		lastActivityAt: 1000,
+		turns: 0,
+		toolCalls: 0,
+		tokens: 0,
+		cost: 0,
+		...overrides,
+	};
+}
+
+test("normalizeRpcEvent maps pi RPC events to task deltas and ignores the rest", () => {
+	assert.deepEqual(normalizeRpcEvent({ type: "message_update", assistantMessageEvent: { type: "text_delta", delta: "Hi" } }), [{ type: TASK_EVENT.TEXT, text: "Hi" }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "message_update", assistantMessageEvent: { type: "thinking_delta", delta: "hmm" } }), [{ type: TASK_EVENT.THINKING, text: "hmm" }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "tool_execution_start", toolCallId: "c1", toolName: "bash", args: { command: "ls" } }), [{ type: TASK_EVENT.TOOL_START, callId: "c1", name: "bash", args: { command: "ls" } }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "tool_execution_update", toolCallId: "c1", toolName: "bash", partialResult: { content: [{ type: "text", text: "a\nb" }] } }), [{ type: TASK_EVENT.TOOL_UPDATE, callId: "c1", output: "a\nb" }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "tool_execution_end", toolCallId: "c1", toolName: "bash", isError: true, result: { content: [{ type: "text", text: "boom" }] } }), [{ type: TASK_EVENT.TOOL_END, callId: "c1", output: "boom", isError: true }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "turn_end" }), [{ type: TASK_EVENT.TURN_END }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "agent_end", messages: [{ role: "assistant", content: [{ type: "text", text: "done." }], stopReason: "stop" }] }), [{ type: TASK_EVENT.AGENT_END, text: "done.", outcome: "success" }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "agent_end", messages: [{ role: "assistant", content: [], stopReason: "error", errorMessage: "WebSocket error with untrusted provider payload" }] }), [{ type: TASK_EVENT.AGENT_END, text: "", outcome: "error", diagnostic: "assistant reported an error" }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "agent_end", messages: [{ role: "assistant", content: [], stopReason: "aborted" }] }), [{ type: TASK_EVENT.AGENT_END, text: "", outcome: "aborted", diagnostic: "assistant aborted" }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "agent_end", messages: [{ role: "assistant", content: [], stopReason: "stop" }] }), [{ type: TASK_EVENT.AGENT_END, text: "", outcome: "empty", diagnostic: "assistant returned no final report" }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "agent_settled" }), [{ type: TASK_EVENT.AGENT_SETTLED }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "message_update", assistantMessageEvent: { type: "error", reason: "error", error: { message: "rate limited" } } }), [{ type: TASK_EVENT.ERROR, message: "rate limited" }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "extension_ui_request", id: "u1", method: "confirm", title: "Delete?" }), [{ type: TASK_EVENT.ASK, request: { id: "u1", method: "confirm", title: "Delete?" } }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "extension_ui_request", id: "u2", method: "setStatus", statusKey: "mcp" }), [], "fire-and-forget UI requests never count as questions");
+	assert.deepEqual(normalizeRpcEvent({ type: "extension_ui_request", id: "u3", method: "notify", message: "hi" }), []);
+	assert.deepEqual(normalizeRpcEvent({ type: "auto_retry_start", attempt: 1, maxAttempts: 3 }), [{ type: TASK_EVENT.NOTE, text: "retrying (1/3)" }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "message_end", message: { role: "assistant", usage: { totalTokens: 9621, cost: { total: 0.0193 } } } }), [{ type: TASK_EVENT.USAGE, tokens: 9621, cost: 0.0193 }]);
+	assert.deepEqual(normalizeRpcEvent({ type: "message_end", message: { role: "user" } }), []);
+	assert.deepEqual(normalizeRpcEvent({ type: "queue_update" }), []);
+	assert.deepEqual(normalizeRpcEvent("garbage"), []);
+});
+
+test("taskLabel prefers an explicit label and otherwise takes the prompt's first sentence", () => {
+	assert.equal(taskLabel("Map the repo. Then report.", "  map  the repo "), "map the repo");
+	assert.equal(taskLabel("Repeat a fresh read-only exploration of lib. Own runtime architecture: extensions, hooks."), "Repeat a fresh read-only exploration of lib");
+	assert.equal(taskLabel("\n\nFirst line here:\nsecond"), "First line here");
+	assert.equal(taskLabel(`${"x".repeat(100)} tail`).length, 72);
+	assert.equal(taskLabel("\x1b[31mred\x1b[0m"), "red");
+});
+
+test("applyTaskEvent appends incrementally: text deltas merge, tool output is replaced, items stay bounded", () => {
+	let thread = emptyThread({ maxItems: 3, maxOutputChars: 9 });
+	thread = applyTaskEvent(thread, { type: TASK_EVENT.TEXT, text: "Hel" });
+	thread = applyTaskEvent(thread, { type: TASK_EVENT.TEXT, text: "lo" });
+	assert.deepEqual(thread.items, [{ kind: THREAD_ITEM.TEXT, text: "Hello" }]);
+	thread = applyTaskEvent(thread, { type: TASK_EVENT.TOOL_START, callId: "c1", name: "bash", args: { command: "ls" } });
+	thread = applyTaskEvent(thread, { type: TASK_EVENT.TOOL_UPDATE, callId: "c1", output: "line one\nline two" });
+	assert.equal(thread.items[1].kind, THREAD_ITEM.TOOL);
+	assert.equal((thread.items[1] as { output: string }).output, "…line two", "tool output keeps the tail");
+	thread = applyTaskEvent(thread, { type: TASK_EVENT.TOOL_END, callId: "c1", output: "ok", isError: false });
+	assert.deepEqual(thread.items[1], { kind: THREAD_ITEM.TOOL, callId: "c1", name: "bash", args: { command: "ls" }, output: "ok", running: false, isError: false });
+	thread = applyTaskEvent(thread, { type: TASK_EVENT.NOTE, text: "retrying (1/3)" });
+	thread = applyTaskEvent(thread, { type: TASK_EVENT.TEXT, text: "After" });
+	assert.equal(thread.items.length, 3);
+	assert.equal(thread.dropped, 1, "the oldest item made room");
+	assert.equal(thread.items[0].kind, THREAD_ITEM.TOOL);
+	assert.equal(thread.version, 7);
+});
+
+test("applyTaskEvent sanitizes text, ignores updates for unknown tools, and records asks as notes", () => {
+	let thread = emptyThread();
+	thread = applyTaskEvent(thread, { type: TASK_EVENT.TEXT, text: "\x1b[31mred\x1b[0m" });
+	assert.deepEqual(thread.items, [{ kind: THREAD_ITEM.TEXT, text: "red" }]);
+	const before = thread;
+	thread = applyTaskEvent(thread, { type: TASK_EVENT.TOOL_UPDATE, callId: "missing", output: "x" });
+	assert.strictEqual(thread, before);
+	thread = applyTaskEvent(thread, { type: TASK_EVENT.ASK, request: { id: "u1", method: "confirm", title: "Delete?" } });
+	assert.deepEqual(thread.items[1], { kind: THREAD_ITEM.NOTE, text: "asked: Delete?" });
+});
+
+test("TaskStore notifies only the listeners of the task that changed and keeps summaries cheap", () => {
+	const store = new TaskStore();
+	store.add(record({ id: "a" }));
+	store.add(record({ id: "b", agent: "worker" }));
+	const seenA: string[] = [];
+	const seenB: string[] = [];
+	const summaries: string[] = [];
+	const offA = store.subscribe("a", (task) => seenA.push(`${task.status}:${task.lastStep}`));
+	store.subscribe("b", (task) => seenB.push(task.status));
+	store.subscribeSummary((summary) => summaries.push(`${summary.running}/${summary.queued}/${summary.finished}`));
+	store.update("a", { status: TASK_STATUS.RUNNING, startedAt: 2000, lastStep: "starting" });
+	store.apply("a", { type: TASK_EVENT.TOOL_START, callId: "c1", name: "bash", args: {} }, 2500);
+	assert.deepEqual(seenA, ["running:starting", "running:bash"]);
+	assert.deepEqual(seenB, []);
+	assert.deepEqual(summaries, ["1/1/0"], "an event inside a task never touches the summary");
+	assert.equal(store.get("a")?.toolCalls, 1);
+	assert.equal(store.get("a")?.lastActivityAt, 2500);
+	assert.equal(store.thread("a").items.length, 1);
+	offA();
+	store.update("a", { status: TASK_STATUS.COMPLETED, endedAt: 3000 });
+	assert.equal(seenA.length, 2, "unsubscribed listener stays quiet");
+	assert.deepEqual(summaries, ["1/1/0", "0/1/1"]);
+	assert.deepEqual(store.list("s1").map((task) => task.id), ["a", "b"], "newest activity first");
+	assert.equal(store.get("missing"), undefined);
+	assert.deepEqual(store.thread("missing"), emptyThread());
+});
+
+test("TaskStore.apply moves the task to waiting on ask, back to running on any later event, and counts turns", () => {
+	const store = new TaskStore();
+	store.add(record({ id: "a", status: TASK_STATUS.RUNNING }));
+	store.apply("a", { type: TASK_EVENT.ASK, request: { id: "u1", method: "input", title: "Name?" } }, 1);
+	assert.equal(store.get("a")?.status, TASK_STATUS.WAITING);
+	assert.equal(store.get("a")?.lastStep, "asked: Name?");
+	store.apply("a", { type: TASK_EVENT.TEXT, text: "thanks" }, 2);
+	assert.equal(store.get("a")?.status, TASK_STATUS.RUNNING);
+	store.apply("a", { type: TASK_EVENT.TURN_END }, 3);
+	store.apply("a", { type: TASK_EVENT.TURN_END }, 4);
+	assert.equal(store.get("a")?.turns, 2);
+	store.apply("a", { type: TASK_EVENT.USAGE, tokens: 100, cost: 0.5 }, 4);
+	store.apply("a", { type: TASK_EVENT.USAGE, tokens: 50, cost: 0.25 }, 4);
+	assert.equal(store.get("a")?.tokens, 150);
+	assert.equal(store.get("a")?.cost, 0.75);
+	store.apply("a", { type: TASK_EVENT.AGENT_END, text: "final answer", outcome: "success" }, 5);
+	assert.equal(store.get("a")?.result, "final answer");
+	assert.equal(store.get("a")?.status, TASK_STATUS.RUNNING, "agent_end alone does not finish: the runner decides");
+});

package/tests/agents-runner-process.test.ts

@@ -0,0 +1,111 @@
+import assert from "node:assert/strict";
+import { spawn as nodeSpawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+import { AGENT_MODE, type AgentDefinition } from "../lib/agents-config.ts";
+import { AgentRunner, type ChildLike, type RunnerDeps, type TaskRequest } from "../lib/agents-runner.ts";
+import { TASK_STATUS, TaskStore } from "../lib/agents-protocol.ts";
+
+const fixture = fileURLToPath(new URL("./fixtures/agents-process-child.mjs", import.meta.url));
+const agent: AgentDefinition = { name: "process", description: "test", filePath: "/test.md", scope: "global", instructions: "", model: undefined, thinking: undefined, mode: undefined, tools: [] };
+const request = (prompt: string): TaskRequest => ({ agent, prompt, label: undefined, context: undefined, mode: AGENT_MODE.BACKGROUND, cwd: process.cwd(), parentSessionId: "test", model: undefined, thinking: undefined, sessionDir: "/tmp", resumeSessionPath: undefined, env: {} });
+
+const waitFor = async (predicate: () => boolean, timeoutMs = 10_000): Promise<void> => {
+	const deadline = Date.now() + timeoutMs;
+	while (!predicate()) {
+		if (Date.now() >= deadline) throw new Error(`condition was not met within ${timeoutMs}ms`);
+		await new Promise((resolve) => setTimeout(resolve, 10));
+	}
+};
+
+test("POSIX cleanup retains queue slots when a leader exits but its TERM-resisting descendant remains", { skip: process.platform === "win32" }, async () => {
+	const store = new TaskStore();
+	let launches = 0;
+	let firstPid: number | undefined;
+	const descendantPids: Array<number | undefined> = [];
+	let firstDetached = false;
+	const ownedPids: number[] = [];
+	const runtimeTimers: Array<{ fn: () => void; timer: ReturnType<typeof setTimeout> | undefined; cancelled: boolean }> = [];
+	const armRuntimeTimeout = (index: number) => {
+		const timer = runtimeTimers[index];
+		if (timer && !timer.cancelled && timer.timer === undefined) timer.timer = setTimeout(timer.fn, 500);
+	};
+	const deps: RunnerDeps = {
+		spawn: (_command, _args, options): ChildLike => {
+			launches += 1;
+			const env = launches === 1 ? { ...options.env, AGENTS_PROCESS_CHILD_EXIT_ON_TERM: "1" } : launches === 3 ? { ...options.env, AGENTS_PROCESS_CHILD_EXIT_AFTER_READY: "1" } : options.env;
+			const child = nodeSpawn(process.execPath, [fixture], { cwd: options.cwd, env, detached: options.detached, stdio: ["pipe", "pipe", "pipe"] });
+			const launchIndex = launches - 1;
+			ownedPids.push(child.pid!);
+			if (launches === 1) {
+				firstPid = child.pid;
+				firstDetached = options.detached === true;
+			}
+			let output = "";
+			child.stdout.on("data", (chunk: Buffer) => {
+				output += chunk.toString();
+				const match = output.match(/DESCENDANT:(\d+)/);
+				if (match) {
+					descendantPids[launchIndex] = Number(match[1]);
+					armRuntimeTimeout(launchIndex);
+				}
+			});
+			return child;
+		},
+		now: Date.now,
+		schedule: (fn, ms) => {
+			if (ms === 500) {
+				const timer = { fn, timer: undefined, cancelled: false };
+				const index = launches - 1;
+				runtimeTimers[index] = timer;
+				if (descendantPids[index] !== undefined) armRuntimeTimeout(index);
+				return () => {
+					timer.cancelled = true;
+					if (timer.timer) clearTimeout(timer.timer);
+				};
+			}
+			const timer = setTimeout(fn, ms);
+			return () => clearTimeout(timer);
+		},
+		pi: { command: process.execPath, args: [fixture] },
+	};
+	const runner = new AgentRunner(store, { maxConcurrency: 1, stallTimeoutMs: 500 }, deps, { askUser: async () => ({ cancelled: true }) });
+	const first = runner.run(request("first"));
+	const second = runner.run(request("second"));
+	const third = runner.run(request("third"));
+	const fourth = runner.run(request("fourth"));
+	try {
+		await waitFor(() => launches === 1 && descendantPids[0] !== undefined);
+		assert.equal(firstDetached, true, "the first child owns a POSIX process group");
+		assert.equal(runner.cancel(first.id), true);
+		assert.equal(store.get(first.id)?.status, TASK_STATUS.RUNNING, "leader exit does not release its live descendant group");
+		await new Promise((resolve) => setTimeout(resolve, 40));
+		assert.doesNotThrow(() => process.kill(descendantPids[0]!, 0), "the exact TERM-resisting descendant remains alive");
+		assert.equal(launches, 1, "the queued task cannot use the slot during SIGTERM grace");
+		await waitFor(() => store.get(first.id)?.status === TASK_STATUS.CANCELLED);
+		assert.equal(launches, 2, "the slot opens only after the owned group exits");
+		assert.throws(() => process.kill(-firstPid!, 0), { code: "ESRCH" }, "SIGKILL cleaned the owned child group, including its descendant");
+		await waitFor(() => store.get(second.id)?.status === TASK_STATUS.TIMED_OUT);
+		assert.throws(() => process.kill(-ownedPids[1], 0), { code: "ESRCH" }, "timeout also bounds cleanup of its owned group");
+		await waitFor(() => launches === 3 && descendantPids[2] !== undefined);
+		await new Promise((resolve) => setTimeout(resolve, 40));
+		assert.doesNotThrow(() => process.kill(descendantPids[2]!, 0), "the natural-exit descendant remains alive");
+		assert.equal(launches, 3, "natural leader exit does not release the queue slot");
+		await waitFor(() => store.get(third.id)?.status === TASK_STATUS.FAILED);
+		assert.equal(launches, 4, "the queue resumes after natural-exit group cleanup");
+		assert.throws(() => process.kill(-ownedPids[2], 0), { code: "ESRCH" }, "natural exit also cleans its owned group");
+	} finally {
+		if (firstDetached) {
+			for (const pid of ownedPids) {
+				try { process.kill(-pid, "SIGKILL"); } catch {}
+			}
+		} else {
+			for (const pid of [firstPid, ...descendantPids, ...ownedPids]) {
+				if (pid) try { process.kill(pid, "SIGKILL"); } catch {}
+			}
+		}
+		runner.cancel(second.id);
+		runner.cancel(third.id);
+		runner.cancel(fourth.id);
+	}
+});