gentle-pi 2.4.0 → 2.6.0

package/tests/agents-integration.test.ts

@@ -0,0 +1,100 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth, type TuiMouseEvent } from "@earendil-works/pi-tui";
+import { TASK_EVENT, TASK_STATUS, TaskStore, type TaskRecord } from "../lib/agents-protocol.ts";
+import { AgentsView } from "../lib/agents-view.ts";
+import { stripAnsi } from "../lib/terminal-theme.ts";
+
+const plainTheme = { fg: (_color: string, text: string) => text };
+
+function task(id: string, overrides: Partial<TaskRecord> = {}): TaskRecord {
+	return { id, agent: id, mode: "task", prompt: "p", label: "p", cwd: "/r", parentSessionId: "session", status: TASK_STATUS.RUNNING, createdAt: 1000, startedAt: 1000, endedAt: null, model: "model", thinking: undefined, sessionPath: "/sessions/task.jsonl", error: null, result: null, lastStep: "working", lastActivityAt: 1000, turns: 0, toolCalls: 0, tokens: 0, cost: 0, ...overrides };
+}
+
+function mouse(x: number, y: number, width: number, height: number, type: TuiMouseEvent["type"] = "click"): TuiMouseEvent {
+	return { type, button: type === "move" || type === "wheel" ? "none" : "left", x, y, screenX: x, screenY: y, width, height, shift: false, alt: false, ctrl: false };
+}
+
+test("AgentsView integrates flat current-session selection, semantic scrolling, live geometry, and idempotent close", () => {
+	const store = new TaskStore();
+	let rows = 8;
+	const closes: string[] = [];
+	const view = new AgentsView({
+		theme: plainTheme,
+		rows: () => rows,
+		store,
+		sessionId: "session",
+		now: () => 61_000,
+		onCancel() {},
+		onOpen() {},
+		onClose: () => closes.push("close"),
+		requestRender() {},
+	});
+	store.add(task("first"));
+	store.add(task("second"));
+	for (let index = 0; index < 12; index += 1) store.apply("first", { type: TASK_EVENT.TEXT, text: `semantic line ${index}\n` }, 2000);
+
+	const wide = 80;
+	let frame = view.render(wide);
+	const header = stripAnsi(frame[0] ?? "");
+	assert.equal(visibleWidth(header), wide);
+	assert.match(header, /\[× Close\]/, "a pane-capable header exposes the wide close control");
+	const closeX = visibleWidth(header.slice(0, header.indexOf("[× Close]")));
+
+	view.handleInput("k");
+	view.handleInput("\x1b[D");
+	assert.equal(view.selectedTask()?.id, "first", "up and left keep the first task selected without a group heading");
+	rows = 6;
+	assert.equal(view.handleMouse(mouse(closeX, 0, wide, frame.length)), undefined, "old close bounds are inert before the live resize frame");
+	frame = view.render(wide);
+	assert.equal(frame.length, rows, "the next frame uses the live height budget");
+	assert.doesNotMatch(frame.map(stripAnsi).join("\n"), /Current orchestrator|Select a task to inspect its thread/, "current-session tasks stay flat with an active detail pane");
+	assert.match(frame.map(stripAnsi).join("\n"), /semantic line 11/, "the selected task still follows its thread after resizing");
+
+	view.handleInput("\x1b[C");
+	assert.equal(view.selectedTask()?.id, "first", "right does not expand a heading in the flat list");
+	view.handleInput("j");
+	assert.equal(view.selectedTask()?.id, "second", "down selects the next task directly");
+	view.handleInput("k");
+	assert.equal(view.selectedTask()?.id, "first", "up returns directly to the first task");
+	view.render(wide);
+	view.handleInput("\x1b[5~");
+	frame = view.render(wide);
+	assert.doesNotMatch(frame.map(stripAnsi).join("\n"), /semantic line 11/, "manual thread scrolling remains off the tail after resizing");
+	const narrow = view.render(59).map(stripAnsi);
+	assert.equal(narrow.length, rows, "width 59 keeps a narrow single viewport");
+	assert.match(narrow[0] ?? "", /\[×\]/, "narrow mode keeps only the compact close control");
+	view.handleInput("\t");
+	const details = view.render(59).map(stripAnsi);
+	assert.match(details[0] ?? "", /\[← Back\]/, "Tab opens selected-task details directly from the flat list");
+	assert.match(details.join("\n"), /first · running/, "details belong to the selected task");
+	view.handleInput("\t");
+	assert.equal(view.selectedTask()?.id, "first", "returning from details preserves task selection");
+	rows = 2;
+	const fallback = view.render(59).map(stripAnsi);
+	assert.equal(fallback.length, 1, "a two-row terminal uses the one-line fallback");
+	assert.match(fallback[0] ?? "", /^× Close/, "fallback mode keeps a single Close cell");
+	assert.equal(view.handleMouse(mouse(1, 0, 59, fallback.length)), undefined, "fallback routing outside the Close cell is inert");
+
+	rows = 6;
+	frame = view.render(wide);
+	const reopenedHeader = stripAnsi(frame[0] ?? "");
+	const reopenedCloseX = visibleWidth(reopenedHeader.slice(0, reopenedHeader.indexOf("[× Close]")));
+	let notifications = 0;
+	const unsubscribe = store.subscribe("first", () => {
+		notifications += 1;
+		if (notifications > 1) throw new Error("the selected listener was rebound during a live update");
+	});
+	store.apply("first", { type: TASK_EVENT.TEXT, text: "after reopen" }, 2000);
+	assert.equal(notifications, 1, "reopening panes retains an idempotent selected-task subscription");
+	assert.equal(view.handleMouse(mouse(reopenedCloseX, 0, wide, frame.length)), undefined, "a task update invalidates the old close bounds");
+	frame = view.render(wide);
+	const currentHeader = stripAnsi(frame[0] ?? "");
+	const currentCloseX = visibleWidth(currentHeader.slice(0, currentHeader.indexOf("[× Close]")));
+	unsubscribe();
+	assert.equal(view.handleMouse(mouse(currentCloseX, 0, wide, frame.length))?.handled, true);
+	view.handleInput("\x1b");
+	view.handleInput("q");
+	assert.deepEqual(closes, ["close"], "pointer, Escape, and q share the same idempotent close action");
+	view.dispose();
+});

package/tests/agents-messaging.test.ts

@@ -0,0 +1,94 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { join } from "node:path";
+import test from "node:test";
+import { CHILD_MESSAGE_MAX_BYTES, ChildMessenger, parseChildFrame } from "../lib/agents-messaging.ts";
+
+test("notification and query frames admit only bounded exact schemas", () => {
+	assert.deepEqual(parseChildFrame({ id: "n1", kind: "notification", message: "💡\nready" }).frame, { id: "n1", kind: "notification", message: "💡\nready" });
+	assert.deepEqual(parseChildFrame({ id: "q1", kind: "query", message: "💡\nready" }).frame, { id: "q1", kind: "query", message: "💡\nready" });
+	for (const frame of [
+		{ id: "n1", kind: "notification", message: "ready", sender: "forged" },
+		{ id: "n1", kind: "query", message: "wrong grammar" },
+		{ id: "q1", kind: "notification", message: "wrong grammar" },
+		{ id: "q0", kind: "query", message: "leading zero" },
+		{ id: `q${"1".repeat(1_000)}`, kind: "query", message: "unbounded correlation" },
+		{ id: "q9007199254740992", kind: "query", message: "unsafe correlation" },
+		{ id: "q1", kind: "query", message: "\uD800" },
+		{ id: "q1", kind: "query", message: "💡".repeat(Math.floor(CHILD_MESSAGE_MAX_BYTES / 4) + 1) },
+		{ id: 3, kind: "notification", message: "ready" },
+	]) assert.ok(parseChildFrame(frame).error, `reject ${JSON.stringify(frame).slice(0, 80)}`);
+});
+
+test("child notification admissions require an exact acknowledgement and clean up", async () => {
+	const listeners = new Map<string, Array<(value: Record<string, unknown>) => void>>();
+	const frames: Array<Record<string, unknown>> = [];
+	const timers: Array<() => void> = [];
+	const endpoint = { send: (frame: Record<string, unknown>) => { frames.push(frame); return true; }, on: (event: string, listener: (value: Record<string, unknown>) => void) => listeners.set(event, [...(listeners.get(event) ?? []), listener]) };
+	const messenger = new ChildMessenger(endpoint, (fn) => { timers.push(fn); return () => {}; });
+	const pending = messenger.notify("wait");
+	let settled = false;
+	void pending.then(() => { settled = true; });
+	for (const listener of listeners.get("message") ?? []) listener({ id: "n1", kind: "ack", accepted: true, sender: "forged" });
+	for (const listener of listeners.get("message") ?? []) listener({ id: "n1", kind: "ack", accepted: false, error: "x".repeat(257) });
+	for (const listener of listeners.get("message") ?? []) listener({ id: "n1", kind: "ack", accepted: true, error: "x".repeat(8 * 1024 + 1) });
+	await Promise.resolve();
+	assert.equal(settled, false, "malformed acknowledgements cannot settle a pending notification");
+	assert.deepEqual(frames, [{ id: "n1", kind: "notification", message: "wait" }]);
+	for (const listener of listeners.get("message") ?? []) listener({ id: "n1", kind: "ack", accepted: true });
+	await pending;
+	const timedOut = messenger.notify("timeout");
+	timers.at(-1)!();
+	await assert.rejects(timedOut, /timed out/);
+	const inflight = Array.from({ length: 8 }, (_, index) => messenger.notify(`pending ${index}`));
+	await assert.rejects(messenger.notify("over capacity"), /too many/);
+	for (const listener of listeners.get("disconnect") ?? []) listener({});
+	assert.ok((await Promise.allSettled(inflight)).every((result) => result.status === "rejected"));
+	const afterDisconnect = messenger.notify("after disconnect");
+	void afterDisconnect.catch(() => {});
+	await Promise.resolve();
+	assert.equal(frames.length, 10, "a disconnected messenger cannot send another notification");
+});
+
+test("callback failures clear pending work but a closed messenger cannot retry", async () => {
+	const listeners = new Map<string, Array<(value: Record<string, unknown>) => void>>();
+	const callbacks: Array<(error: Error | null) => void> = [];
+	const timers: Array<{ cancelled: boolean }> = [];
+	const endpoint = { send: (_frame: Record<string, unknown>, callback?: (error: Error | null) => void) => { callbacks.push(callback!); return true; }, on: (event: string, listener: (value: Record<string, unknown>) => void) => listeners.set(event, [...(listeners.get(event) ?? []), listener]) };
+	const messenger = new ChildMessenger(endpoint, () => {
+		const timer = { cancelled: false };
+		timers.push(timer);
+		return () => { timer.cancelled = true; };
+	});
+	const failed = messenger.notify("first");
+	callbacks[0](new Error("send failed"));
+	await assert.rejects(failed, /send failed/);
+	const retry = messenger.notify("retry");
+	for (const listener of listeners.get("message") ?? []) listener({ id: "n2", kind: "ack", accepted: true });
+	await retry;
+	messenger.close();
+	assert.ok(timers.every((timer) => timer.cancelled), "settled and closed work cancels every timer");
+	const afterClose = messenger.notify("after close");
+	void afterClose.catch(() => {});
+	await Promise.resolve();
+	assert.equal(callbacks.length, 2, "a closed messenger cannot retry through its endpoint");
+	const exhausted = new ChildMessenger(endpoint, () => () => {});
+	(exhausted as unknown as { nextId: number }).nextId = Number.MAX_SAFE_INTEGER;
+	await assert.rejects(exhausted.notify("overflow"), /correlation exhausted/);
+});
+
+test("a real Node IPC child exchanges a notification acknowledgement without stdout framing", async () => {
+	const child = spawn(process.execPath, [join(import.meta.dirname, "fixtures", "agents-messaging-child.mjs")], { stdio: ["ignore", "pipe", "pipe", "ipc"] });
+	const messages: unknown[] = [];
+	let output = "";
+	const closed = once(child, "close");
+	child.on("message", (message) => messages.push(message));
+	child.stdout.on("data", (chunk) => { output += chunk; });
+	await once(child, "message");
+	assert.deepEqual(messages, [{ id: "n1", kind: "notification", message: "fixture ready" }]);
+	child.send({ id: "n1", kind: "ack", accepted: true });
+	const [code] = await closed;
+	assert.equal(code, 0);
+	assert.equal(output, '{"accepted":true}\n');
+});

package/tests/agents-protocol.test.ts

@@ -0,0 +1,198 @@
+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("response observations are opt-in, finalized, field-specific and content-free", () => {
+	const message = { role: "assistant", provider: "openai", model: "gpt-4o", responseModel: "gpt-4o-2024-08-06",
+		providerThinkingLevel: "high", stopReason: "stop", content: [{ type: "text", text: "private response" }],
+		errorMessage: "private error", responseId: "private id", modelVersion: "invented",
+		usage: { input: 12, output: 4, cacheRead: 0, cacheWrite: -1, totalTokens: 16, reasoning: 2 } };
+	const raw = { type: "message_end", message };
+	assert.deepEqual(normalizeRpcEvent(raw), [{ type: TASK_EVENT.USAGE, tokens: 16, cost: 0 }]);
+	const events = normalizeRpcEvent(raw, { observeResponses: true });
+	assert.equal(events.length, 2);
+	const observation = events.find((event) => event.type === "response_observation")?.observation;
+	assert.ok(observation);
+	assert.deepEqual(observation.provider, { state: "observed", value: "openai" });
+	assert.deepEqual(observation.model, { state: "observed", value: "gpt-4o" });
+	assert.deepEqual(observation.responseModel, { state: "observed", value: message.responseModel });
+	assert.deepEqual(observation.providerThinkingLevel, { state: "observed", value: "high" });
+	assert.deepEqual(observation.selected, { provider: { state: "unavailable" }, model: { state: "unavailable" }, effort: { state: "unavailable" } });
+	assert.deepEqual(observation.tokens, { input: { state: "reported", value: 12 }, output: { state: "reported", value: 4 },
+		cacheRead: { state: "unavailable" }, cacheWrite: { state: "unavailable" }, totalTokens: { state: "reported", value: 16 },
+		reasoning: { state: "reported", value: 2 } });
+	assert.doesNotMatch(JSON.stringify(observation), /private|invented|modelVersion|content|responseId/);
+	for (const stopReason of ["stop", "length", "toolUse", "error", "aborted"]) {
+		const [event] = normalizeRpcEvent({ type: "message_end", message: { role: "assistant", stopReason } }, { observeResponses: true });
+		assert.ok(event?.type === "response_observation", "missing usage still exposes a response");
+		assert.equal(event.observation.stopReason, stopReason);
+	}
+	for (const stopReason of ["pending", "deferred", undefined, "private error"]) {
+		assert.deepEqual(normalizeRpcEvent({ type: "message_end", message: { role: "assistant", stopReason } }, { observeResponses: true }), []);
+	}
+	for (const type of ["message_start", "message_update", "turn_end", "agent_end"]) {
+		assert.ok(!normalizeRpcEvent({ type, message, messages: [message] }, { observeResponses: true }).some((event) => event.type === "response_observation"));
+	}
+	assert.deepEqual(normalizeRpcEvent({ type: "message_end", message: { ...message, role: "toolResult" } }, { observeResponses: true }), []);
+});
+
+test("response observations reject malformed counters and unbounded metadata without coercion", () => {
+	for (const value of [0, -1, 1.5, NaN, Infinity, "12", null, undefined, 1_000_000_001]) {
+		const [event] = normalizeRpcEvent({ type: "message_end", message: { role: "assistant", stopReason: "error",
+			provider: "x".repeat(33), model: "x".repeat(129), responseModel: "private\ntext", providerThinkingLevel: {},
+			usage: { input: value, output: value, cacheRead: value, cacheWrite: value, totalTokens: value, reasoning: value } } }, { observeResponses: true }).filter((event) => event.type === "response_observation");
+		assert.ok(event);
+		for (const field of Object.values(event.observation.tokens)) assert.deepEqual(field, { state: "unavailable" });
+		for (const field of ["provider", "model", "responseModel", "providerThinkingLevel"] as const) assert.deepEqual(event.observation[field], { state: "unavailable" });
+	}
+});
+
+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-queries.test.ts

@@ -0,0 +1,190 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { AGENT_MODE, type AgentDefinition } from "../lib/agents-config.ts";
+import { CHILD_MESSAGE_MAX_BYTES, ChildMessenger } from "../lib/agents-messaging.ts";
+import { TaskStore } from "../lib/agents-protocol.ts";
+import { AgentRunner } from "../lib/agents-runner.ts";
+import { fakeChild } from "./agents-fake-child.ts";
+
+const tick = () => new Promise((resolve) => setImmediate(resolve));
+const agent: AgentDefinition = { name: "worker", description: "", filePath: "/a.md", scope: "global", instructions: "", model: undefined, thinking: undefined, mode: undefined, tools: ["read"] };
+const request = (mode = AGENT_MODE.BACKGROUND) => ({ agent, prompt: "work", label: undefined, context: undefined, mode, cwd: "/repo", parentSessionId: "s1", model: undefined, thinking: undefined, sessionDir: "/sessions", resumeSessionPath: undefined, env: {} });
+
+test("ChildMessenger validates query replies and settles timeout, callback failure, and disconnect once", async () => {
+	const listeners = new Map<string, Array<(value: Record<string, unknown>) => void>>();
+	const frames: Array<Record<string, unknown>> = [];
+	const timers: Array<() => void> = [];
+	let callback: ((error: Error | null) => void) | undefined;
+	const endpoint = {
+		send: (frame: Record<string, unknown>, done?: (error: Error | null) => void) => { frames.push(frame); callback = done; return false; },
+		on: (event: string, listener: (value: Record<string, unknown>) => void) => listeners.set(event, [...(listeners.get(event) ?? []), listener]),
+	};
+	const messenger = new ChildMessenger(endpoint, (fn) => { timers.push(fn); return () => {}; });
+	const pending = messenger.query("which file?");
+	assert.deepEqual(frames, [{ id: "q1", kind: "query", message: "which file?" }]);
+	for (const listener of listeners.get("message") ?? []) listener({ id: "q1", kind: "reply", message: "\uD800" });
+	for (const listener of listeners.get("message") ?? []) listener({ id: "q1", kind: "reply", message: "x".repeat(CHILD_MESSAGE_MAX_BYTES + 1) });
+	callback?.(new Error("send failed"));
+	await assert.rejects(pending, /send failed/);
+	const timeout = messenger.query("timeout");
+	timers.at(-1)!();
+	await assert.rejects(timeout, /timed out/);
+	const disconnected = messenger.query("disconnect");
+	for (const listener of listeners.get("disconnect") ?? []) listener({});
+	await assert.rejects(disconnected, /closed/);
+});
+
+test("ChildMessenger resolves one strictly correlated query reply", async () => {
+	const listeners = new Map<string, Array<(value: Record<string, unknown>) => void>>();
+	const frames: Array<Record<string, unknown>> = [];
+	const endpoint = {
+		send: (frame: Record<string, unknown>) => { frames.push(frame); return true; },
+		on: (event: string, listener: (value: Record<string, unknown>) => void) => listeners.set(event, [...(listeners.get(event) ?? []), listener]),
+	};
+	const messenger = new ChildMessenger(endpoint, () => () => {});
+	const pending = messenger.query("Where?");
+	for (const listener of listeners.get("message") ?? []) listener({ id: "n1", kind: "reply", message: "forged" });
+	for (const listener of listeners.get("message") ?? []) listener({ id: "q1", kind: "reply", message: "src/a.ts", extra: true });
+	for (const listener of listeners.get("message") ?? []) listener({ id: "q1", kind: "reply", message: "src/a.ts" });
+	assert.deepEqual(frames, [{ id: "q1", kind: "query", message: "Where?" }]);
+	assert.equal(await pending, "src/a.ts");
+});
+
+test("ChildMessenger rejects an empty reply error and ignores mixed reply fields", async () => {
+	const listeners = new Map<string, Array<(value: Record<string, unknown>) => void>>();
+	const timers: Array<{ cancelled: boolean; fn: () => void }> = [];
+	const messenger = new ChildMessenger({
+		send: () => true,
+		on: (event, listener) => listeners.set(event, [...(listeners.get(event) ?? []), listener as (value: Record<string, unknown>) => void]),
+	}, (fn) => {
+		const timer = { cancelled: false, fn };
+		timers.push(timer);
+		return () => { timer.cancelled = true; };
+	});
+	const emptyError = messenger.query("empty error");
+	for (const listener of listeners.get("message") ?? []) listener({ id: "q1", kind: "reply", error: "" });
+	await assert.rejects(emptyError, /parent rejected query/);
+	assert.equal(timers[0]?.cancelled, true, "a rejected reply cancels its deadline");
+	const mixed = messenger.query("mixed fields");
+	for (const listener of listeners.get("message") ?? []) listener({ id: "q2", kind: "reply", message: "answer", error: "also error" });
+	assert.equal(timers[1]?.cancelled, false, "mixed reply fields cannot settle a query");
+	timers[1]?.fn();
+	await assert.rejects(mixed, /timed out/);
+});
+
+test("runner sends bounded static query rejection frames that settle the child before timeout", async () => {
+	const child = fakeChild();
+	const listeners = new Map<string, Array<(value: Record<string, unknown>) => void>>();
+	const timers: Array<{ cancelled: boolean; fn: () => void }> = [];
+	child.child.send = (frame, done) => {
+		child.sent.push(frame);
+		for (const listener of listeners.get("message") ?? []) listener(frame);
+		done?.(null);
+		return true;
+	};
+	const messenger = new ChildMessenger({
+		send: (frame) => { child.message(frame); return true; },
+		on: (event, listener) => listeners.set(event, [...(listeners.get(event) ?? []), listener as (value: Record<string, unknown>) => void]),
+	}, (fn) => {
+		const timer = { cancelled: false, fn };
+		timers.push(timer);
+		return () => { timer.cancelled = true; };
+	});
+	const runner = new AgentRunner(new TaskStore(), { maxConcurrency: 1, stallTimeoutMs: 10_000 }, { spawn: () => child.child, now: () => 1, schedule: () => () => {}, pi: { command: "pi", args: [] } }, { askUser: async () => ({ cancelled: true }), onQuery: () => { throw new Error(`\uD800${"x".repeat(CHILD_MESSAGE_MAX_BYTES)}`); } });
+	runner.run(request());
+	await tick();
+	const pending = messenger.query("reject me");
+	timers[0]?.fn();
+	await assert.rejects(pending, /parent rejected query/);
+	assert.deepEqual(child.sent.at(-1), { id: "q1", kind: "reply", error: "parent rejected query" });
+	assert.equal(timers[0]?.cancelled, true, "the child reply settles before its deadline");
+});
+
+test("a malformed query with a valid q ID gets a reply that clears the matching child query", async () => {
+	const child = fakeChild();
+	const listeners = new Map<string, Array<(value: Record<string, unknown>) => void>>();
+	const timers: Array<{ cancelled: boolean; fn: () => void }> = [];
+	child.child.send = (frame, done) => {
+		child.sent.push(frame);
+		for (const listener of listeners.get("message") ?? []) listener(frame);
+		done?.(null);
+		return true;
+	};
+	const messenger = new ChildMessenger({
+		send: (frame) => { child.message(frame); return true; },
+		on: (event, listener) => listeners.set(event, [...(listeners.get(event) ?? []), listener as (value: Record<string, unknown>) => void]),
+	}, (fn) => {
+		const timer = { cancelled: false, fn };
+		timers.push(timer);
+		return () => { timer.cancelled = true; };
+	});
+	const runner = new AgentRunner(new TaskStore(), { maxConcurrency: 1, stallTimeoutMs: 10_000 }, { spawn: () => child.child, now: () => 1, schedule: () => () => {}, pi: { command: "pi", args: [] } }, { askUser: async () => ({ cancelled: true }), onQuery: () => {} });
+	runner.run(request());
+	await tick();
+	const pending = messenger.query("valid first");
+	child.message({ id: "q1", kind: "query", message: "malformed", extra: true });
+	timers[0]?.fn();
+	await assert.rejects(pending, /invalid child IPC frame/);
+	assert.deepEqual(child.sent.at(-1), { id: "q1", kind: "reply", error: "invalid child IPC frame" });
+	assert.equal(timers[0]?.cancelled, true);
+});
+
+test("background queries keep correlation, bounds, and ownership before replying only over IPC", async () => {
+	const child = fakeChild();
+	const queries: Array<{ taskId: string; requestId: string; message: string }> = [];
+	const runner = new AgentRunner(new TaskStore(), { maxConcurrency: 1, stallTimeoutMs: 10_000 }, { spawn: () => child.child, now: () => 1, schedule: () => () => {}, pi: { command: "pi", args: [] } }, {
+		askUser: async () => ({ cancelled: true }), onQuery: (task, requestId, message) => queries.push({ taskId: task.id, requestId, message }),
+	});
+	const task = runner.run(request());
+	await tick();
+	for (const [id, message] of [["q1", "Which file?"], ["q2", "two"], ["q3", "three"], ["q4", "four"], ["q5", "five"], ["q1", "duplicate"]]) child.message({ id, kind: "query", message });
+	await tick();
+	assert.deepEqual(queries, ["q1", "q2", "q3", "q4"].map((requestId, index) => ({ taskId: task.id, requestId, message: ["Which file?", "two", "three", "four"][index] })));
+	assert.deepEqual(child.sent.slice(-2), [{ id: "q5", kind: "reply", error: "too many pending parent queries" }, { id: "q1", kind: "reply", error: "duplicate query request" }]);
+	assert.equal(await runner.reply(task.id, "q1", "src/a.ts", "s1"), true);
+	assert.equal(await runner.reply(task.id, "q1", "again", "s1"), false);
+	assert.equal(await runner.reply(task.id, "q2", "other", "s2"), false);
+	assert.equal(await runner.reply(task.id, "q2", "x".repeat(CHILD_MESSAGE_MAX_BYTES + 1), "s1"), false);
+	assert.deepEqual(child.sent.at(-1), { id: "q1", kind: "reply", message: "src/a.ts" });
+});
+
+test("a throwing query hook rolls back ownership before one error and never schedules a second reply", async () => {
+	const child = fakeChild();
+	const timers: Array<{ fn: () => void; ms: number }> = [];
+	const runner = new AgentRunner(new TaskStore(), { maxConcurrency: 1, stallTimeoutMs: 10_000 }, { spawn: () => child.child, now: () => 1, schedule: (fn, ms) => { timers.push({ fn, ms }); return () => {}; }, pi: { command: "pi", args: [] } }, { askUser: async () => ({ cancelled: true }), onQuery: () => { throw new Error("host callback failed"); } });
+	const task = runner.run(request());
+	await tick();
+	child.message({ id: "q1", kind: "query", message: "throw" });
+	assert.deepEqual(child.sent.at(-1), { id: "q1", kind: "reply", error: "parent rejected query" });
+	assert.equal(await runner.reply(task.id, "q1", "late", "s1"), false);
+	timers.at(-1)?.fn();
+	assert.equal(child.sent.filter((frame) => frame.id === "q1").length, 1);
+});
+
+test("query expiry, IPC revocation, delayed callbacks, and foreground admission settle once", async () => {
+	const child = fakeChild();
+	const timers: Array<{ fn: () => void; ms: number }> = [];
+	const runner = new AgentRunner(new TaskStore(), { maxConcurrency: 1, stallTimeoutMs: 10_000 }, { spawn: () => child.child, now: () => 1, schedule: (fn, ms) => { timers.push({ fn, ms }); return () => {}; }, pi: { command: "pi", args: [] } }, { askUser: async () => ({ cancelled: true }), onQuery: () => {} });
+	const task = runner.run(request());
+	await tick();
+	child.message({ id: "q1", kind: "query", message: "wait" });
+	assert.equal(timers.at(-1)?.ms, 30_000);
+	let callback: ((error: Error | null) => void) | undefined;
+	child.child.send = (_frame, done) => { callback = done; return false; };
+	const pending = runner.reply(task.id, "q1", "late", "s1");
+	timers.at(-1)?.fn();
+	assert.equal(await pending, false);
+	callback?.(null);
+	assert.equal(await runner.reply(task.id, "q1", "again", "s1"), false);
+	child.message({ id: "q2", kind: "query", message: "disconnect" });
+	child.child.disconnect?.();
+	assert.equal(await runner.reply(task.id, "q2", "no", "s1"), false);
+	const foregroundChild = fakeChild();
+	let foregroundQueries = 0;
+	const foreground = new AgentRunner(new TaskStore(), { maxConcurrency: 1, stallTimeoutMs: 10_000 }, { spawn: () => foregroundChild.child, now: () => 1, schedule: () => () => {}, pi: { command: "pi", args: [] } }, { askUser: async () => ({ cancelled: true }), onQuery: () => { foregroundQueries += 1; } });
+	foreground.run(request(AGENT_MODE.TASK));
+	await tick();
+	foregroundChild.message({ id: "q1", kind: "query", message: "not yet" });
+	await tick();
+	assert.equal(foregroundQueries, 1);
+});

package/tests/agents-responsive.test.ts

@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { measureAgentsViewLayout } from "../lib/agents-view-layout.ts";
+
+const widths = [0, 1, 2, 11, 12, 59, 60, 90];
+
+for (const rows of [0, 1, 2]) {
+	test(`Agents layout safely bounds ${rows}-row terminals`, () => {
+		for (const width of widths) {
+			const layout = measureAgentsViewLayout(width, rows);
+			assert.equal(layout.height, rows);
+			assert.ok(layout.width >= 0 && layout.width <= width);
+			assert.ok(layout.bodyRows >= 0);
+			assert.ok(layout.listWidth >= 0 && layout.threadWidth >= 0);
+		}
+	});
+}
+
+test("Agents layout reserves fallback for tiny terminals, a single viewport for narrow terminals, and panes at 60 cells", () => {
+	for (const width of [0, 1, 2, 11]) assert.equal(measureAgentsViewLayout(width, 8).mode, "fallback");
+	for (const height of [0, 1, 2]) assert.equal(measureAgentsViewLayout(80, height).mode, "fallback");
+	for (const width of [12, 59]) {
+		const narrow = measureAgentsViewLayout(width, 3);
+		assert.equal(narrow.mode, "narrow");
+		assert.equal(narrow.bodyRows, 0);
+		assert.equal(narrow.footerY, 1);
+	}
+	const layout = measureAgentsViewLayout(60, 8);
+	assert.equal(layout.mode, "panes");
+	assert.equal(layout.height, 8);
+	assert.equal(layout.bodyRows, 5);
+	assert.equal(layout.footerY, 6);
+	assert.equal(layout.listX, 2);
+	assert.equal(layout.threadX, layout.listX + layout.listWidth + 3);
+	assert.ok(layout.threadX + layout.threadWidth + 1 <= layout.width);
+	const fullscreen = measureAgentsViewLayout(60, 8, true);
+	assert.equal(fullscreen.mode, "narrow");
+	assert.equal(fullscreen.threadWidth, 56);
+	assert.equal(fullscreen.threadX, 2);
+	assert.equal(fullscreen.height, 8);
+	assert.equal(visibleWidth("寿司"), 4, "multibyte widths remain terminal-cell widths");
+});