gentle-pi 2.4.0 → 2.5.0

package/tests/agents-config.test.ts

@@ -0,0 +1,143 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test, { after } from "node:test";
+import {
+	AGENT_MODE,
+	agentDirectories,
+	discoverAgents,
+	loadAgentsConfig,
+	parseAgentDefinition,
+	parseAgentsConfig,
+	parseFrontmatter,
+	parseModelRef,
+	resolveAgentProfile,
+} from "../lib/agents-config.ts";
+
+// Gentle Agents configuration: markdown agent definitions (the same files
+// gentle-ai installs) and subagents.json, both parsed without touching pi.
+
+const root = mkdtempSync(join(tmpdir(), "gentle-agents-config-"));
+after(() => rmSync(root, { recursive: true, force: true }));
+
+const EXPLORER = `---
+name: gentle-ai-explore
+description: Read-only exploration and mapping.
+model: openai-codex/gpt-5.6-terra
+thinking: high
+tools:
+  - read
+  - grep
+  - codegraph
+---
+
+You are the read-only explorer.
+Map files and return a compressed handoff.
+`;
+
+test("parseFrontmatter reads scalars, inline lists, and block lists, and keeps the body", () => {
+	const { data, body } = parseFrontmatter("---\nname: a\ntools: [read, grep]\nlist:\n  - one\n  - two\nquoted: \"x: y\"\n---\nBody here\n");
+	assert.deepEqual(data, { name: "a", tools: ["read", "grep"], list: ["one", "two"], quoted: "x: y" });
+	assert.equal(body, "Body here");
+	assert.deepEqual(parseFrontmatter("no frontmatter"), { data: {}, body: "no frontmatter" });
+});
+
+test("parseModelRef splits provider/id and accepts a bare id", () => {
+	assert.deepEqual(parseModelRef("openai-codex/gpt-5.6-terra"), { provider: "openai-codex", id: "gpt-5.6-terra" });
+	assert.deepEqual(parseModelRef("sonnet"), { provider: undefined, id: "sonnet" });
+	assert.equal(parseModelRef("   "), undefined);
+});
+
+test("parseAgentDefinition builds a definition from the gentle-ai agent format", () => {
+	const agent = parseAgentDefinition(EXPLORER, "/home/x/.pi/agent/agents/gentle-ai-explore.md", "global");
+	assert.ok(!("error" in agent));
+	assert.equal(agent.name, "gentle-ai-explore");
+	assert.equal(agent.description, "Read-only exploration and mapping.");
+	assert.deepEqual(agent.model, { provider: "openai-codex", id: "gpt-5.6-terra" });
+	assert.equal(agent.thinking, "high");
+	assert.deepEqual(agent.tools, ["read", "grep", "codegraph"]);
+	assert.equal(agent.mode, undefined);
+	assert.equal(agent.scope, "global");
+	assert.match(agent.instructions, /^You are the read-only explorer\./);
+});
+
+test("parseAgentDefinition accepts effort and subagent_mode aliases, csv tools, and names from the file", () => {
+	const agent = parseAgentDefinition("---\ndescription: d\neffort: low\nsubagent_mode: background\ntools: read, bash\n---\nbody", "/p/.pi/agents/worker.md", "project");
+	assert.ok(!("error" in agent));
+	assert.equal(agent.name, "worker");
+	assert.equal(agent.thinking, "low");
+	assert.equal(agent.mode, AGENT_MODE.BACKGROUND);
+	assert.deepEqual(agent.tools, ["read", "bash"]);
+});
+
+test("parseAgentDefinition rejects unknown thinking levels, modes, and empty bodies", () => {
+	assert.match((parseAgentDefinition("---\nname: a\nthinking: extreme\n---\nbody", "/a.md", "global") as { error: string }).error, /thinking "extreme"/);
+	assert.match((parseAgentDefinition("---\nname: a\nsubagent_mode: forever\n---\nbody", "/a.md", "global") as { error: string }).error, /mode "forever"/);
+	assert.match((parseAgentDefinition("---\nname: a\n---\n   \n", "/a.md", "global") as { error: string }).error, /no instructions/);
+});
+
+test("discoverAgents merges the four directories with project over global and subagents over agents", () => {
+	const home = join(root, "home");
+	const cwd = join(root, "project");
+	for (const dir of [".pi/agent/agents", ".pi/agent/subagents"]) mkdirSync(join(home, dir), { recursive: true });
+	for (const dir of [".pi/agents", ".pi/subagents"]) mkdirSync(join(cwd, dir), { recursive: true });
+	writeFileSync(join(home, ".pi/agent/agents/explore.md"), EXPLORER);
+	writeFileSync(join(home, ".pi/agent/agents/shared.md"), "---\ndescription: global agents\n---\nglobal");
+	writeFileSync(join(home, ".pi/agent/subagents/shared.md"), "---\ndescription: global subagents\n---\nglobal sub");
+	writeFileSync(join(cwd, ".pi/agents/shared.md"), "---\ndescription: project agents\n---\nproject");
+	writeFileSync(join(cwd, ".pi/agents/broken.md"), "---\nthinking: nope\n---\nx");
+	writeFileSync(join(cwd, ".pi/agents/notes.txt"), "ignored");
+	const { agents, errors } = discoverAgents({ cwd, home });
+	assert.deepEqual(agents.map((agent) => `${agent.name}:${agent.description}:${agent.scope}`), ["gentle-ai-explore:Read-only exploration and mapping.:global", "shared:project agents:project"]);
+	assert.equal(errors.length, 1);
+	assert.match(errors[0], /broken\.md/);
+	assert.deepEqual(discoverAgents({ cwd: join(root, "empty"), home: join(root, "nohome") }), { agents: [], errors: [] });
+});
+
+test("profile agent roots isolate global definitions and subagents.json while explicit homes keep their fallback", () => {
+	const cwd = join(root, "profile-project");
+	const principal = join(root, "pi-principal", "agent");
+	const lab = join(root, "pi-lab", "agent");
+	for (const [agentHome, name, model] of [[principal, "principal", "openai/principal"], [lab, "lab", "openai/lab"]] as const) {
+		mkdirSync(join(agentHome, "agents"), { recursive: true });
+		writeFileSync(join(agentHome, "agents", `${name}.md`), `---\ndescription: ${name}\n---\n${name}`);
+		writeFileSync(join(agentHome, "subagents.json"), JSON.stringify({ default_model: model }));
+	}
+	assert.deepEqual(agentDirectories({ cwd, home: join(root, "legacy-home"), agentHome: principal }).slice(0, 2).map(({ dir }) => dir), [join(principal, "agents"), join(principal, "subagents")]);
+	assert.deepEqual(discoverAgents({ cwd, home: join(root, "legacy-home"), agentHome: principal }).agents.map((agent) => agent.name), ["principal"]);
+	assert.deepEqual(discoverAgents({ cwd, home: join(root, "legacy-home"), agentHome: lab }).agents.map((agent) => agent.name), ["lab"]);
+	assert.equal(loadAgentsConfig({ cwd, home: join(root, "legacy-home"), agentHome: principal }).defaultModel?.id, "principal");
+	assert.equal(loadAgentsConfig({ cwd, home: join(root, "legacy-home"), agentHome: lab }).defaultModel?.id, "lab");
+	assert.equal(agentDirectories({ cwd, home: join(root, "legacy-home") })[0].dir, join(root, "legacy-home", ".pi", "agent", "agents"));
+});
+
+test("parseAgentsConfig applies defaults, validates values, and silently ignores the retired total-timeout key", () => {
+	const config = parseAgentsConfig({ default_model: "openai-codex/gpt-6-astra", default_effort: "medium", max_concurrency: 3, timeout_ms: 1000, stall_timeout_ms: 12_000, model_profiles: { explore: { model: "openai-codex/gpt-5.6-terra", effort: "high" } } }, { max_concurrency: 2, timeout_ms: 500, model_profiles: { explore: { effort: "low" }, worker: { model: "anthropic/claude-sonnet-5" } } });
+	assert.deepEqual(config.defaultModel, { provider: "openai-codex", id: "gpt-6-astra" });
+	assert.equal(config.defaultThinking, "medium");
+	assert.equal(config.maxConcurrency, 2);
+	assert.equal(config.stallTimeoutMs, 12_000);
+	assert.equal("timeoutMs" in config, false, "legacy timeout_ms must not become an active runtime setting");
+	assert.deepEqual(config.modelProfiles.explore, { model: { provider: "openai-codex", id: "gpt-5.6-terra" }, thinking: "low" });
+	assert.deepEqual(config.modelProfiles.worker, { model: { provider: "anthropic", id: "claude-sonnet-5" }, thinking: undefined });
+	const defaults = parseAgentsConfig(undefined, undefined);
+	assert.equal(defaults.maxConcurrency, 5);
+	assert.equal("timeoutMs" in defaults, false);
+	assert.equal(defaults.stallTimeoutMs, 4 * 60_000);
+	assert.equal(defaults.defaultMode, AGENT_MODE.TASK);
+	assert.equal(defaults.historyMaxTasks, 200);
+	assert.equal(parseAgentsConfig({ max_concurrency: "many", default_effort: "wild", default_mode: "background" }, undefined).maxConcurrency, 5);
+	assert.equal(parseAgentsConfig({ default_mode: "background" }, undefined).defaultMode, AGENT_MODE.BACKGROUND);
+});
+
+test("resolveAgentProfile prefers the profile, then the definition, then the defaults", () => {
+	const config = parseAgentsConfig({ default_model: "openai-codex/gpt-6-astra", default_effort: "medium", model_profiles: { "gentle-ai-explore": { effort: "high" } } }, undefined);
+	const explore = parseAgentDefinition(EXPLORER, "/x/explore.md", "global");
+	assert.ok(!("error" in explore));
+	assert.deepEqual(resolveAgentProfile(explore, config), { model: { provider: "openai-codex", id: "gpt-5.6-terra" }, thinking: "high", source: { model: "definition", thinking: "profile" } });
+	const bare = parseAgentDefinition("---\nname: bare\n---\nbody", "/x/bare.md", "global");
+	assert.ok(!("error" in bare));
+	assert.deepEqual(resolveAgentProfile(bare, config), { model: { provider: "openai-codex", id: "gpt-6-astra" }, thinking: "medium", source: { model: "default", thinking: "default" } });
+	assert.deepEqual(resolveAgentProfile(bare, parseAgentsConfig(undefined, undefined)).source, { model: "unresolved", thinking: "unresolved" });
+});

package/tests/agents-fake-child.ts

@@ -0,0 +1,52 @@
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import type { ChildLike } from "../lib/agents-runner.ts";
+
+// A fake `pi --mode rpc` child: answers every command with a success
+// response, records what the host wrote, and lets tests emit events.
+
+export interface FakeChild {
+	child: ChildLike;
+	written: Array<Record<string, unknown>>;
+	emit(event: Record<string, unknown>): void;
+	exit(code: number): void;
+	fail(message: string): void;
+	killed: string[];
+}
+
+export function fakeChild(options: { exitOnKill?: boolean; pid?: number } = {}): FakeChild {
+	const emitter = new EventEmitter();
+	const stdin = new PassThrough();
+	const stdout = new PassThrough();
+	const written: Array<Record<string, unknown>> = [];
+	const killed: string[] = [];
+	let buffer = "";
+	stdin.on("data", (chunk: Buffer) => {
+		buffer += chunk.toString();
+		const lines = buffer.split("\n");
+		buffer = lines.pop() ?? "";
+		for (const line of lines) {
+			const command = JSON.parse(line) as Record<string, unknown>;
+			written.push(command);
+			if (command.type === "extension_ui_response") continue;
+			const data = command.type === "get_state" ? { sessionFile: "/sessions/child.jsonl" } : undefined;
+			stdout.write(`${JSON.stringify({ type: "response", id: command.id, command: command.type, success: true, data })}\n`);
+		}
+	});
+	const child: ChildLike = {
+		pid: options.pid,
+		stdin,
+		stdout,
+		stderr: new PassThrough(),
+		kill: (signal) => {
+			killed.push(String(signal ?? "SIGTERM"));
+			if (options.exitOnKill !== false) queueMicrotask(() => emitter.emit("exit", 0, signal ?? "SIGTERM"));
+			return true;
+		},
+		on: (event, listener) => {
+			emitter.on(event, listener);
+			return child;
+		},
+	};
+	return { child, written, killed, emit: (event) => stdout.write(`${JSON.stringify(event)}\n`), exit: (code) => emitter.emit("exit", code, null), fail: (message) => emitter.emit("error", new Error(message)) };
+}

package/tests/agents-history.test.ts

@@ -0,0 +1,54 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test, { after } from "node:test";
+import { historyDir, loadHistory, loadStoredTask, pruneHistory, saveTask } from "../lib/agents-history.ts";
+import { applyTaskEvent, emptyThread, TASK_EVENT, TASK_STATUS, TaskStore, type TaskRecord } from "../lib/agents-protocol.ts";
+
+// Gentle Agents history: JSON per task, async, lazy, pruned by count.
+
+const root = mkdtempSync(join(tmpdir(), "gentle-agents-history-"));
+after(() => rmSync(root, { recursive: true, force: true }));
+const dir = join(root, "tasks");
+
+function task(id: string, createdAt: number): TaskRecord {
+	return { id, agent: "explore", mode: "task", prompt: "p", label: "p", cwd: "/r", parentSessionId: "s", status: TASK_STATUS.COMPLETED, createdAt, startedAt: createdAt, endedAt: createdAt + 5, model: "m", thinking: undefined, sessionPath: null, error: null, result: "ok", lastStep: "done", lastActivityAt: createdAt, turns: 1, toolCalls: 0, tokens: 10, cost: 0.01 };
+}
+
+test("historyDir follows an isolated agent profile while explicit homes retain the default fallback", () => {
+	assert.equal(historyDir("/home/x", "/profiles/pi-principal/agent"), join("/profiles/pi-principal/agent", "gentle-agents", "tasks"));
+	assert.equal(historyDir("/home/x", "/profiles/pi-lab/agent"), join("/profiles/pi-lab/agent", "gentle-agents", "tasks"));
+	assert.equal(historyDir("/home/x"), join("/home/x", ".pi", "agent", "gentle-agents", "tasks"));
+});
+
+test("saveTask writes a task with its thread and loadStoredTask reads it back", async () => {
+	const thread = applyTaskEvent(emptyThread(), { type: TASK_EVENT.TEXT, text: "hello" });
+	await saveTask(dir, task("a1", 1000), thread);
+	const stored = await loadStoredTask(dir, "a1");
+	assert.equal(stored?.task.result, "ok");
+	assert.deepEqual(stored?.thread.items, [{ kind: "text", text: "hello" }]);
+	assert.equal(await loadStoredTask(dir, "missing"), undefined);
+	assert.equal(await loadStoredTask(dir, "../etc/passwd"), undefined);
+	assert.deepEqual(readdirSync(dir), ["a1.json"], "no temp file is left behind");
+});
+
+test("loadHistory skips broken files, sorts newest first, and pruneHistory keeps the newest N", async () => {
+	await saveTask(dir, task("b2", 3000), emptyThread());
+	await saveTask(dir, task("c3", 2000), emptyThread());
+	writeFileSync(join(dir, "junk.json"), "{not json");
+	writeFileSync(join(dir, "shape.json"), JSON.stringify({ task: { id: 1 } }));
+	assert.deepEqual((await loadHistory(dir)).map((entry) => entry.task.id), ["b2", "c3", "a1"]);
+	assert.equal(await pruneHistory(dir, 2), 1);
+	assert.deepEqual((await loadHistory(dir)).map((entry) => entry.task.id), ["b2", "c3"]);
+	assert.deepEqual(await loadHistory(join(root, "nowhere")), []);
+});
+
+test("TaskStore.restore adds a stored task without clobbering a live one", () => {
+	const store = new TaskStore();
+	const thread = applyTaskEvent(emptyThread(), { type: TASK_EVENT.NOTE, text: "restored" });
+	assert.equal(store.restore(task("r1", 1000), thread), true);
+	assert.equal(store.thread("r1").items.length, 1);
+	assert.equal(store.restore({ ...task("r1", 1000), result: "other" }, emptyThread()), false);
+	assert.equal(store.get("r1")?.result, "ok");
+});

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);
+	}
+});