gentle-pi 2.3.0 → 2.5.0

package/extensions/gentle-todo.ts

@@ -0,0 +1,199 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import {
+	applyTodo,
+	emptyTodo,
+	renderTodoCard,
+	replayTodo,
+	staleTurns,
+	TODO_DETAILS_KEY,
+	TODO_GLYPH,
+	TODO_TOOL_NAME,
+	todoPromptBlock,
+	todoSummary,
+	type TodoParams,
+	type TodoState,
+} from "../lib/shell-todo.ts";
+
+// Gentle Todo: the task list the model keeps while it works, drawn as a
+// Gentle Shell card above the editor. Three things keep it current that a
+// static tool description cannot: `write` replaces the whole list in one
+// call, every turn's system prompt carries the open tasks and the rules, and
+// a list that goes untouched while tasks stay open is marked stale for both
+// the human and the model.
+
+const WIDGET_KEY = "gentle-todo";
+const COLLAPSE_KEY_DEFAULT = "ctrl+shift+t";
+const TOOL_PARAMETERS = {
+	type: "object",
+	additionalProperties: false,
+	required: ["action"],
+	properties: {
+		action: { type: "string", enum: ["write", "add", "update", "clear", "list"], description: "write replaces the whole list; add appends one task; update changes one task by id; clear empties the list; list reports it." },
+		tasks: {
+			type: "array",
+			description: "For write: the complete ordered list. Keep the id of tasks that already exist so their history survives; omit it for new ones.",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				required: ["title"],
+				properties: {
+					id: { type: "integer", description: "Existing task id to keep." },
+					title: { type: "string", description: "Short imperative title, e.g. 'Write the parser'." },
+					status: { type: "string", enum: ["pending", "in_progress", "done"], description: "Defaults to pending." },
+					note: { type: "string", description: "What is happening right now, shown while in_progress, e.g. 'writing tests'." },
+				},
+			},
+		},
+		id: { type: "integer", description: "Task id for update." },
+		title: { type: "string", description: "Title for add, or a new title for update." },
+		status: { type: "string", enum: ["pending", "in_progress", "done"], description: "Status for add or update." },
+		note: { type: "string", description: "Note for add or update." },
+	},
+} as const;
+
+export function todoEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+	if (env.GENTLE_PI_AGENTS_CHILD === "1") return false;
+	const value = env.GENTLE_PI_TODO?.trim().toLowerCase();
+	return !(value === "0" || value === "false" || value === "off");
+}
+
+export function todoCollapseKey(env: NodeJS.ProcessEnv = process.env): string | undefined {
+	const value = env.GENTLE_PI_TODO_KEY?.trim();
+	if (value === undefined) return COLLAPSE_KEY_DEFAULT;
+	return value === "" || value.toLowerCase() === "off" ? undefined : value;
+}
+
+interface TodoSession {
+	state: TodoState;
+	turn: number;
+	collapsed: boolean;
+	/** A finished list stays on screen for the turn it finished in, then clears. */
+	clearOnNextTurn: boolean;
+	ui: ExtensionContext["ui"] | undefined;
+	host: { requestRender(): void } | undefined;
+}
+
+function sessionKey(ctx: ExtensionContext): string {
+	return ctx.sessionManager.getSessionId() ?? "";
+}
+
+export default function gentleTodo(pi: ExtensionAPI, env: NodeJS.ProcessEnv = process.env): void {
+	if (!todoEnabled(env)) return;
+	const sessions = new Map<string, TodoSession>();
+	const collapseKey = todoCollapseKey(env);
+
+	const session = (ctx: ExtensionContext): TodoSession => {
+		const key = sessionKey(ctx);
+		let current = sessions.get(key);
+		if (!current) {
+			current = { state: emptyTodo(), turn: 0, collapsed: false, clearOnNextTurn: false, ui: undefined, host: undefined };
+			sessions.set(key, current);
+		}
+		return current;
+	};
+
+	const show = (current: TodoSession) => {
+		if (!current.ui) return;
+		if (current.state.tasks.length === 0) {
+			current.ui.setWidget(WIDGET_KEY, undefined);
+			return;
+		}
+		const snapshot = current;
+		current.ui.setWidget(WIDGET_KEY, (tui, theme) => {
+			snapshot.host = tui;
+			return {
+				render(width: number) {
+					const lines = renderTodoCard(snapshot.state, theme, width, { collapsed: snapshot.collapsed, staleTurns: staleTurns(snapshot.state, snapshot.turn), collapseKey });
+					return lines.length === 0 ? [] : [...lines, ""];
+				},
+				invalidate() {},
+			};
+		});
+	};
+
+	pi.registerTool({
+		name: TODO_TOOL_NAME,
+		label: "Todo",
+		description: "Plan and track multi-step work. Use write to set the whole list, update to move one task, add for a new one, clear to reset, list to read it back.",
+		promptSnippet: "Track multi-step work; rewrite the whole list as the plan changes",
+		promptGuidelines: [
+			"Use todo for work with three or more steps or when the user hands you a list. Skip it for single trivial requests.",
+			"Mark a task in_progress before starting it and done right after finishing it; keep exactly one task in_progress.",
+			"Prefer write with the complete list whenever the plan changes; keep ids of tasks that already exist.",
+			"Never mark a task done while tests fail or the work is partial; add a task for the blocker instead.",
+		],
+		parameters: TOOL_PARAMETERS,
+		executionMode: "sequential",
+		renderCall(args, theme) {
+			const params = args as TodoParams;
+			return new Text(theme.fg("toolTitle", `${TODO_GLYPH} todo · ${params.action}`), 0, 0);
+		},
+		renderResult(result, options, theme) {
+			const text = result.content.map((part) => (part.type === "text" ? part.text : "")).join("\n");
+			return new Text(options.expanded ? text : theme.fg("muted", text.split("\n")[0] ?? ""), 0, 0);
+		},
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const current = session(ctx);
+			const result = applyTodo(current.state, params as TodoParams, current.turn);
+			if (!result.error) {
+				current.state = result.state;
+				current.clearOnNextTurn = false;
+			}
+			return {
+				content: [{ type: "text", text: result.text }],
+				details: { [TODO_DETAILS_KEY]: result.state, ...(result.error ? { error: result.error } : {}) },
+			};
+		},
+	});
+
+	if (collapseKey) {
+		pi.registerShortcut(collapseKey as Parameters<ExtensionAPI["registerShortcut"]>[0], {
+			description: "Collapse or expand the todo list",
+			handler: async (ctx) => {
+				const current = session(ctx);
+				current.collapsed = !current.collapsed;
+				current.host?.requestRender();
+			},
+		});
+	}
+
+	pi.on("session_start", (_event, ctx) => {
+		const current = session(ctx);
+		// A list that was already finished when the session was left is history,
+		// not work: it would otherwise sit on screen until two more turns pass.
+		const replayed = replayTodo(ctx.sessionManager.getBranch());
+		current.state = replayed.tasks.length > 0 && todoSummary(replayed).open === 0 ? { ...replayed, tasks: [] } : replayed;
+		current.turn = ctx.sessionManager.getBranch().filter((entry) => (entry as { type?: string }).type === "message" && (entry as { message?: { role?: string } }).message?.role === "user").length;
+		current.ui = ctx.hasUI ? ctx.ui : undefined;
+		show(current);
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		sessions.delete(sessionKey(ctx));
+	});
+
+	pi.on("before_agent_start", (event, ctx) => {
+		const current = session(ctx);
+		current.turn += 1;
+		if (current.clearOnNextTurn) {
+			current.state = { ...current.state, tasks: [] };
+			current.clearOnNextTurn = false;
+			show(current);
+		}
+		const block = todoPromptBlock(current.state, staleTurns(current.state, current.turn));
+		if (!block) return undefined;
+		return { systemPrompt: `${event.systemPrompt}\n\n${block}` };
+	});
+
+	pi.on("tool_execution_end", (event, ctx) => {
+		if (event.toolName !== TODO_TOOL_NAME) return;
+		show(session(ctx));
+	});
+
+	pi.on("agent_end", (_event, ctx) => {
+		const current = session(ctx);
+		if (current.state.tasks.length > 0 && todoSummary(current.state).open === 0) current.clearOnNextTurn = true;
+		show(current);
+	});
+}

package/extensions/quiet-tools.ts

@@ -653,7 +653,7 @@ function registerQuietTool(pi: ExtensionAPI, toolName: QuietToolName, commandArg
 				{ result: true, isPartial: options.isPartial },
 			).directResult;
 			if (directResult) {
-				return renderGentleAiResult(safeResult, { expanded: options.expanded });
+				return renderGentleAiResult(safeResult, { expanded: options.expanded, isPartial: options.isPartial, isError }, theme, renderContext as GentleAiRenderContext | undefined);
 			}
 			if (options.isPartial) {
 				if (options.expanded) return new Text(`${theme.fg("warning", partialLabel(toolName, text))}\n${theme.fg("muted", text)}`, 0, 0);

package/lib/agent-home.ts

@@ -0,0 +1,8 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// Pi Subagents resolves its global directory as `PI_CODING_AGENT_DIR || ~/.pi/agent`,
+// so an empty value must fall through here too or the two homes diverge again.
+export function resolveGentlePiAgentHome(env: NodeJS.ProcessEnv = process.env): string {
+	return env.GENTLE_PI_AGENT_HOME || env.PI_CODING_AGENT_DIR || join(homedir(), ".pi", "agent");
+}

package/lib/agents-config.ts

@@ -0,0 +1,318 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+
+// Gentle Agents configuration. Agent definitions are markdown files with YAML
+// frontmatter (the format gentle-ai installs) and runtime settings come from
+// subagents.json at the global and project level. Everything here is pure
+// apart from the discovery helpers, which take their roots as arguments.
+
+export const AGENT_MODE = {
+	TASK: "task",
+	BACKGROUND: "background",
+} as const;
+
+export type AgentMode = (typeof AGENT_MODE)[keyof typeof AGENT_MODE];
+
+export const THINKING_LEVEL = {
+	OFF: "off",
+	MINIMAL: "minimal",
+	LOW: "low",
+	MEDIUM: "medium",
+	HIGH: "high",
+	XHIGH: "xhigh",
+} as const;
+
+export type ThinkingLevel = (typeof THINKING_LEVEL)[keyof typeof THINKING_LEVEL];
+
+export const AGENT_SCOPE = {
+	GLOBAL: "global",
+	PROJECT: "project",
+} as const;
+
+export type AgentScope = (typeof AGENT_SCOPE)[keyof typeof AGENT_SCOPE];
+
+export const PROFILE_SOURCE = {
+	PROFILE: "profile",
+	DEFINITION: "definition",
+	DEFAULT: "default",
+	UNRESOLVED: "unresolved",
+} as const;
+
+export type ProfileSource = (typeof PROFILE_SOURCE)[keyof typeof PROFILE_SOURCE];
+
+export interface ModelRef {
+	provider: string | undefined;
+	id: string;
+}
+
+export interface AgentDefinition {
+	name: string;
+	description: string;
+	filePath: string;
+	scope: AgentScope;
+	instructions: string;
+	model: ModelRef | undefined;
+	thinking: ThinkingLevel | undefined;
+	mode: AgentMode | undefined;
+	tools: string[];
+}
+
+export interface AgentDefinitionError {
+	filePath: string;
+	error: string;
+}
+
+export interface ModelProfile {
+	model: ModelRef | undefined;
+	thinking: ThinkingLevel | undefined;
+}
+
+export interface AgentsConfig {
+	defaultModel: ModelRef | undefined;
+	defaultThinking: ThinkingLevel | undefined;
+	defaultMode: AgentMode;
+	modelProfiles: Record<string, ModelProfile>;
+	stallTimeoutMs: number;
+	maxConcurrency: number;
+	historyMaxTasks: number;
+}
+
+export interface ProfileSources {
+	model: ProfileSource;
+	thinking: ProfileSource;
+}
+
+export interface ResolvedProfile {
+	model: ModelRef | undefined;
+	thinking: ThinkingLevel | undefined;
+	source: ProfileSources;
+}
+
+export interface DiscoveryRoots {
+	cwd: string;
+	home: string;
+	agentHome?: string;
+}
+
+export interface DiscoveryResult {
+	agents: AgentDefinition[];
+	errors: string[];
+}
+
+export type FrontmatterValue = string | string[];
+
+export interface Frontmatter {
+	data: Record<string, FrontmatterValue>;
+	body: string;
+}
+
+const DEFAULT_STALL_TIMEOUT_MS = 4 * 60_000;
+const DEFAULT_MAX_CONCURRENCY = 5;
+const DEFAULT_HISTORY_MAX_TASKS = 200;
+const THINKING_LEVELS = Object.values(THINKING_LEVEL) as string[];
+const AGENT_MODES = Object.values(AGENT_MODE) as string[];
+
+function unquote(value: string): string {
+	const trimmed = value.trim();
+	const quoted = (trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"));
+	return quoted && trimmed.length >= 2 ? trimmed.slice(1, -1) : trimmed;
+}
+
+function parseInlineList(value: string): string[] {
+	return value.slice(1, -1).split(",").map(unquote).filter((item) => item.length > 0);
+}
+
+// Just enough YAML for agent frontmatter: `key: scalar`, `key: [a, b]`, and
+// `key:` followed by `- item` lines. Anything else stays a plain string.
+export function parseFrontmatter(text: string): Frontmatter {
+	const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+	if (!match) return { data: {}, body: text.trim() };
+	const data: Record<string, FrontmatterValue> = {};
+	let listKey: string | undefined;
+	for (const raw of match[1].split(/\r?\n/)) {
+		const item = /^\s*-\s+(.*)$/.exec(raw);
+		if (item && listKey) {
+			(data[listKey] as string[]).push(unquote(item[1]));
+			continue;
+		}
+		const pair = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(raw);
+		if (!pair) continue;
+		const [, key, value] = pair;
+		const trimmed = value.trim();
+		if (trimmed.length === 0) {
+			data[key] = [];
+			listKey = key;
+			continue;
+		}
+		listKey = undefined;
+		data[key] = trimmed.startsWith("[") && trimmed.endsWith("]") ? parseInlineList(trimmed) : unquote(trimmed);
+	}
+	return { data, body: match[2].trim() };
+}
+
+export function parseModelRef(value: unknown): ModelRef | undefined {
+	if (typeof value !== "string") return undefined;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return undefined;
+	const slash = trimmed.indexOf("/");
+	if (slash <= 0) return { provider: undefined, id: trimmed };
+	return { provider: trimmed.slice(0, slash), id: trimmed.slice(slash + 1) };
+}
+
+function parseThinking(value: unknown): ThinkingLevel | undefined | string {
+	if (value === undefined) return undefined;
+	const normalized = String(value).trim().toLowerCase();
+	return THINKING_LEVELS.includes(normalized) ? (normalized as ThinkingLevel) : `thinking "${value}" is not one of ${THINKING_LEVELS.join(", ")}`;
+}
+
+function parseMode(value: unknown): AgentMode | undefined | string {
+	if (value === undefined) return undefined;
+	const normalized = String(value).trim().toLowerCase();
+	return AGENT_MODES.includes(normalized) ? (normalized as AgentMode) : `mode "${value}" is not one of ${AGENT_MODES.join(", ")}`;
+}
+
+function parseTools(value: FrontmatterValue | undefined): string[] {
+	if (value === undefined) return [];
+	const items = Array.isArray(value) ? value : value.split(",");
+	return items.map((item) => item.trim()).filter((item) => item.length > 0);
+}
+
+function scalar(value: FrontmatterValue | undefined): string | undefined {
+	return typeof value === "string" ? value : undefined;
+}
+
+export function parseAgentDefinition(text: string, filePath: string, scope: AgentScope): AgentDefinition | AgentDefinitionError {
+	const { data, body } = parseFrontmatter(text);
+	const thinking = parseThinking(scalar(data.thinking) ?? scalar(data.effort) ?? scalar(data.thinking_level));
+	if (thinking !== undefined && !THINKING_LEVELS.includes(thinking)) return { filePath, error: thinking };
+	const mode = parseMode(scalar(data.subagent_mode) ?? scalar(data.mode));
+	if (mode !== undefined && !AGENT_MODES.includes(mode)) return { filePath, error: mode };
+	if (body.length === 0) return { filePath, error: "no instructions after the frontmatter" };
+	const name = scalar(data.name)?.trim() || basename(filePath).replace(/\.md$/i, "");
+	return {
+		name,
+		description: scalar(data.description)?.trim() ?? "",
+		filePath,
+		scope,
+		instructions: body,
+		model: parseModelRef(data.model),
+		thinking: thinking as ThinkingLevel | undefined,
+		mode: mode as AgentMode | undefined,
+		tools: parseTools(data.tools),
+	};
+}
+
+// Discovery order is precedence order: a later directory replaces an earlier
+// definition with the same name, so project beats global and `subagents/`
+// beats `agents/` within each scope.
+function profileRoot(roots: DiscoveryRoots): string {
+	return roots.agentHome ?? join(roots.home, ".pi", "agent");
+}
+
+export function agentDirectories(roots: DiscoveryRoots): Array<{ dir: string; scope: AgentScope }> {
+	const agentHome = profileRoot(roots);
+	return [
+		{ dir: join(agentHome, "agents"), scope: AGENT_SCOPE.GLOBAL },
+		{ dir: join(agentHome, "subagents"), scope: AGENT_SCOPE.GLOBAL },
+		{ dir: join(roots.cwd, ".pi", "agents"), scope: AGENT_SCOPE.PROJECT },
+		{ dir: join(roots.cwd, ".pi", "subagents"), scope: AGENT_SCOPE.PROJECT },
+	];
+}
+
+export function discoverAgents(roots: DiscoveryRoots): DiscoveryResult {
+	const agents = new Map<string, AgentDefinition>();
+	const errors: string[] = [];
+	for (const { dir, scope } of agentDirectories(roots)) {
+		if (!existsSync(dir)) continue;
+		for (const file of readdirSync(dir).filter((entry) => entry.toLowerCase().endsWith(".md")).sort()) {
+			const filePath = join(dir, file);
+			const parsed = parseAgentDefinition(readFileSync(filePath, "utf8"), filePath, scope);
+			if ("error" in parsed) errors.push(`${filePath}: ${parsed.error}`);
+			else agents.set(parsed.name, parsed);
+		}
+	}
+	return { agents: [...agents.values()].sort((a, b) => a.name.localeCompare(b.name)), errors };
+}
+
+type RawConfig = Record<string, unknown> | undefined;
+
+function positiveInteger(value: unknown, fallback: number): number {
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+
+function parseProfiles(value: unknown): Record<string, ModelProfile> {
+	const profiles: Record<string, ModelProfile> = {};
+	if (!value || typeof value !== "object") return profiles;
+	for (const [name, raw] of Object.entries(value as Record<string, unknown>)) {
+		if (!raw || typeof raw !== "object") continue;
+		const entry = raw as Record<string, unknown>;
+		const thinking = parseThinking(entry.effort ?? entry.thinking);
+		profiles[name] = { model: parseModelRef(entry.model), thinking: thinking !== undefined && THINKING_LEVELS.includes(thinking) ? (thinking as ThinkingLevel) : undefined };
+	}
+	return profiles;
+}
+
+function mergeProfiles(base: Record<string, ModelProfile>, override: Record<string, ModelProfile>): Record<string, ModelProfile> {
+	const merged = { ...base };
+	for (const [name, profile] of Object.entries(override)) {
+		merged[name] = { model: profile.model ?? base[name]?.model, thinking: profile.thinking ?? base[name]?.thinking };
+	}
+	return merged;
+}
+
+// Project settings override global ones field by field; model profiles merge
+// per agent so a project can change one effort without repeating the model.
+export function parseAgentsConfig(global: RawConfig, project: RawConfig): AgentsConfig {
+	const merged: Record<string, unknown> = { ...(global ?? {}), ...(project ?? {}) };
+	const thinking = parseThinking(merged.default_effort ?? merged.default_thinking_level ?? merged.default_thinking);
+	const mode = parseMode(merged.default_mode);
+	return {
+		defaultModel: parseModelRef(merged.default_model),
+		defaultThinking: thinking !== undefined && THINKING_LEVELS.includes(thinking) ? (thinking as ThinkingLevel) : undefined,
+		defaultMode: mode !== undefined && AGENT_MODES.includes(mode) ? (mode as AgentMode) : AGENT_MODE.TASK,
+		modelProfiles: mergeProfiles(parseProfiles(global?.model_profiles), parseProfiles(project?.model_profiles)),
+		// `timeout_ms` remains accepted as an inert legacy key so existing JSON
+		// files load normally; only silence is bounded by `stall_timeout_ms`.
+		stallTimeoutMs: positiveInteger(merged.stall_timeout_ms, DEFAULT_STALL_TIMEOUT_MS),
+		maxConcurrency: positiveInteger(merged.max_concurrency, DEFAULT_MAX_CONCURRENCY),
+		historyMaxTasks: positiveInteger(merged.history_max_tasks, DEFAULT_HISTORY_MAX_TASKS),
+	};
+}
+
+function readJson(path: string): RawConfig {
+	if (!existsSync(path)) return undefined;
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function loadAgentsConfig(roots: DiscoveryRoots): AgentsConfig {
+	return parseAgentsConfig(readJson(join(profileRoot(roots), "subagents.json")), readJson(join(roots.cwd, ".pi", "subagents.json")));
+}
+
+function pick<T>(candidates: Array<[T | undefined, ProfileSource]>): [T | undefined, ProfileSource] {
+	return candidates.find(([value]) => value !== undefined) ?? [undefined, PROFILE_SOURCE.UNRESOLVED];
+}
+
+export function resolveAgentProfile(agent: AgentDefinition, config: AgentsConfig): ResolvedProfile {
+	const profile = config.modelProfiles[agent.name];
+	const [model, modelSource] = pick<ModelRef>([
+		[profile?.model, PROFILE_SOURCE.PROFILE],
+		[agent.model, PROFILE_SOURCE.DEFINITION],
+		[config.defaultModel, PROFILE_SOURCE.DEFAULT],
+	]);
+	const [thinking, thinkingSource] = pick<ThinkingLevel>([
+		[profile?.thinking, PROFILE_SOURCE.PROFILE],
+		[agent.thinking, PROFILE_SOURCE.DEFINITION],
+		[config.defaultThinking, PROFILE_SOURCE.DEFAULT],
+	]);
+	return { model, thinking, source: { model: modelSource, thinking: thinkingSource } };
+}
+
+export function formatModelRef(model: ModelRef | undefined): string {
+	if (!model) return "default";
+	return model.provider ? `${model.provider}/${model.id}` : model.id;
+}

package/lib/agents-history.ts

@@ -0,0 +1,80 @@
+import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { emptyThread, type TaskRecord, type TaskThread } from "./agents-protocol.ts";
+
+// Gentle Agents history: one JSON file per finished task, written by the
+// host after the child is gone and read back lazily when the overlay opens
+// or a tool asks for a task from an earlier session. Everything is async so
+// the terminal never waits on disk.
+
+export interface StoredTask {
+	task: TaskRecord;
+	thread: TaskThread;
+}
+
+const FILE_SUFFIX = ".json";
+const SAFE_ID = /^[a-z0-9-]+$/i;
+
+export function historyDir(home: string, agentHome = join(home, ".pi", "agent")): string {
+	return join(agentHome, "gentle-agents", "tasks");
+}
+
+function fileFor(dir: string, id: string): string {
+	if (!SAFE_ID.test(id)) throw new Error(`invalid task id: ${id}`);
+	return join(dir, `${id}${FILE_SUFFIX}`);
+}
+
+function isRecord(value: unknown): value is TaskRecord {
+	const task = value as Partial<TaskRecord> | undefined;
+	return typeof task?.id === "string" && typeof task.agent === "string" && typeof task.status === "string" && typeof task.createdAt === "number";
+}
+
+function parseStored(text: string): StoredTask | undefined {
+	try {
+		const parsed = JSON.parse(text) as Partial<StoredTask>;
+		if (!isRecord(parsed.task)) return undefined;
+		const thread = parsed.thread && Array.isArray(parsed.thread.items) ? parsed.thread : emptyThread();
+		return { task: parsed.task, thread: { ...emptyThread(), ...thread } };
+	} catch {
+		return undefined;
+	}
+}
+
+export async function saveTask(dir: string, task: TaskRecord, thread: TaskThread): Promise<void> {
+	await mkdir(dir, { recursive: true });
+	const target = fileFor(dir, task.id);
+	const temp = `${target}.${process.pid}-${Math.random().toString(36).slice(2, 8)}.tmp`;
+	await writeFile(temp, JSON.stringify({ task, thread }), "utf8");
+	await rename(temp, target);
+}
+
+export async function loadStoredTask(dir: string, id: string): Promise<StoredTask | undefined> {
+	if (!SAFE_ID.test(id)) return undefined;
+	try {
+		return parseStored(await readFile(fileFor(dir, id), "utf8"));
+	} catch {
+		return undefined;
+	}
+}
+
+async function listFiles(dir: string): Promise<string[]> {
+	try {
+		return (await readdir(dir)).filter((name) => name.endsWith(FILE_SUFFIX));
+	} catch {
+		return [];
+	}
+}
+
+export async function loadHistory(dir: string): Promise<StoredTask[]> {
+	const files = await listFiles(dir);
+	const stored = await Promise.all(files.map(async (name) => parseStored(await readFile(join(dir, name), "utf8").catch(() => ""))));
+	return stored.filter((entry): entry is StoredTask => entry !== undefined).sort((a, b) => b.task.createdAt - a.task.createdAt);
+}
+
+// Keep the newest `maxTasks` files; the rest go. Returns how many were removed.
+export async function pruneHistory(dir: string, maxTasks: number): Promise<number> {
+	const stored = await loadHistory(dir);
+	const extra = stored.slice(Math.max(0, maxTasks));
+	await Promise.all(extra.map((entry) => rm(fileFor(dir, entry.task.id), { force: true })));
+	return extra.length;
+}