@aprimediet/minion 1.0.0

package/tasks.ts

@@ -0,0 +1,380 @@
+/**
+ * Persistent delegation/task board — a lightweight kanban (à la Hermes' agent board) stored as
+ * one markdown card per task under ~/.pi/projects/<id>/tasks/. Each card carries a status
+ * (column), a designated agent (assignee), a structured instruction the subagent can execute
+ * directly, acceptance criteria, dependencies, and an activity log. Delegation records are written
+ * under .../delegations/ so every delegation's full detail is captured.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { type ExtensionAPI, type ExtensionContext, parseFrontmatter, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { resolveProject } from "./project.ts";
+
+export type TaskStatus = "backlog" | "todo" | "in_progress" | "blocked" | "review" | "done" | "cancelled";
+export const STATUS_ORDER: TaskStatus[] = ["backlog", "todo", "in_progress", "blocked", "review", "done", "cancelled"];
+/** Statuses that should be re-delegated when work resumes in a new session. */
+const RESUMABLE = new Set<TaskStatus>(["todo", "in_progress", "blocked"]);
+const OPEN = new Set<TaskStatus>(["backlog", "todo", "in_progress", "blocked", "review"]);
+
+export interface Task {
+	id: string;
+	title: string;
+	status: TaskStatus;
+	agent: string;
+	priority: "low" | "normal" | "high";
+	labels: string[];
+	dependsOn: string[];
+	created: string;
+	updated: string;
+	attempts: number;
+	session: string;
+	instruction: string;
+	acceptance: string[];
+	notes: string;
+	activity: string[];
+}
+
+function nowISO(): string {
+	return new Date().toISOString();
+}
+export function generateTaskId(): string {
+	return `t-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+// --------------------------------------------------------------- (de)serialize
+
+function csv(v: string[]): string {
+	return v.filter(Boolean).join(", ");
+}
+function splitCsv(v: string | undefined): string[] {
+	return (v ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+function section(title: string, content: string): string {
+	return `## ${title}\n${content.trim()}\n`;
+}
+
+function serialize(t: Task): string {
+	const fm = [
+		"---",
+		`id: ${t.id}`,
+		`title: ${t.title}`,
+		`status: ${t.status}`,
+		`agent: ${t.agent}`,
+		`priority: ${t.priority}`,
+		`labels: ${csv(t.labels)}`,
+		`depends_on: ${csv(t.dependsOn)}`,
+		`created: ${t.created}`,
+		`updated: ${t.updated}`,
+		`attempts: ${t.attempts}`,
+		`session: ${t.session}`,
+		"---",
+		"",
+	].join("\n");
+	const body = [
+		section("Instruction", t.instruction || "(none)"),
+		section("Acceptance criteria", t.acceptance.length ? t.acceptance.map((a) => `- ${a}`).join("\n") : "(none)"),
+		section("Notes", t.notes || "(none)"),
+		section("Activity", t.activity.length ? t.activity.map((a) => `- ${a}`).join("\n") : "(none)"),
+	].join("\n");
+	return `${fm}${body}`;
+}
+
+function parseSections(body: string): Record<string, string> {
+	const out: Record<string, string> = {};
+	const parts = body.split(/^## /m);
+	for (const part of parts) {
+		const nl = part.indexOf("\n");
+		if (nl === -1) continue;
+		const heading = part.slice(0, nl).trim().toLowerCase();
+		if (!heading) continue;
+		out[heading] = part.slice(nl + 1).trim();
+	}
+	return out;
+}
+
+function parse(content: string, fallbackId: string): Task | null {
+	try {
+		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+		if (!frontmatter?.id && !frontmatter?.title) return null;
+		const s = parseSections(body);
+		const listFrom = (txt: string | undefined): string[] =>
+			(txt && txt !== "(none)" ? txt.split("\n") : [])
+				.map((l) => l.replace(/^[-*]\s*/, "").trim())
+				.filter(Boolean);
+		const text = (txt: string | undefined): string => (txt && txt !== "(none)" ? txt : "");
+		return {
+			id: frontmatter.id || fallbackId,
+			title: frontmatter.title || "(untitled)",
+			status: (frontmatter.status as TaskStatus) || "todo",
+			agent: frontmatter.agent || "",
+			priority: (frontmatter.priority as Task["priority"]) || "normal",
+			labels: splitCsv(frontmatter.labels),
+			dependsOn: splitCsv(frontmatter.depends_on),
+			created: frontmatter.created || nowISO(),
+			updated: frontmatter.updated || frontmatter.created || nowISO(),
+			attempts: Number.parseInt(frontmatter.attempts ?? "0", 10) || 0,
+			session: frontmatter.session || "",
+			instruction: text(s.instruction),
+			acceptance: listFrom(s["acceptance criteria"]),
+			notes: text(s.notes),
+			activity: listFrom(s.activity),
+		};
+	} catch {
+		return null;
+	}
+}
+
+// --------------------------------------------------------------- store ops
+
+function taskPath(tasksDir: string, id: string): string {
+	return path.join(tasksDir, `${id}.md`);
+}
+
+export function listTasks(tasksDir: string): Task[] {
+	if (!fs.existsSync(tasksDir)) return [];
+	const out: Task[] = [];
+	for (const name of fs.readdirSync(tasksDir)) {
+		if (!name.endsWith(".md")) continue;
+		try {
+			const t = parse(fs.readFileSync(path.join(tasksDir, name), "utf-8"), name.replace(/\.md$/, ""));
+			if (t) out.push(t);
+		} catch {
+			/* skip */
+		}
+	}
+	return out;
+}
+
+export function getTask(tasksDir: string, id: string): Task | null {
+	const file = taskPath(tasksDir, id);
+	if (!fs.existsSync(file)) return null;
+	try {
+		return parse(fs.readFileSync(file, "utf-8"), id);
+	} catch {
+		return null;
+	}
+}
+
+export async function writeTask(tasksDir: string, t: Task): Promise<void> {
+	const file = taskPath(tasksDir, t.id);
+	fs.mkdirSync(tasksDir, { recursive: true });
+	await withFileMutationQueue(file, async () => {
+		const tmp = `${file}.tmp`;
+		await fs.promises.writeFile(tmp, serialize(t), { encoding: "utf-8", mode: 0o600 });
+		await fs.promises.rename(tmp, file);
+	});
+}
+
+export function listResumable(tasksDir: string): Task[] {
+	return listTasks(tasksDir).filter((t) => RESUMABLE.has(t.status));
+}
+export function listOpen(tasksDir: string): Task[] {
+	return listTasks(tasksDir).filter((t) => OPEN.has(t.status));
+}
+
+// --------------------------------------------------------------- delegation linkage
+
+export function loadTaskInstruction(tasksDir: string, id: string): { instruction: string; agent: string } | null {
+	const t = getTask(tasksDir, id);
+	if (!t) return null;
+	const parts = [t.instruction];
+	if (t.acceptance.length) parts.push(`\nAcceptance criteria:\n${t.acceptance.map((a) => `- ${a}`).join("\n")}`);
+	if (t.notes) parts.push(`\nNotes:\n${t.notes}`);
+	return { instruction: parts.filter(Boolean).join("\n").trim() || t.title, agent: t.agent };
+}
+
+export async function markTaskDelegating(tasksDir: string, id: string, agent: string, session: string): Promise<void> {
+	const t = getTask(tasksDir, id);
+	if (!t) return;
+	t.status = "in_progress";
+	if (agent) t.agent = agent;
+	t.attempts += 1;
+	t.updated = nowISO();
+	t.activity.push(`${nowISO()} — delegated to ${agent || t.agent || "?"} (attempt ${t.attempts}, session ${session.slice(0, 8)})`);
+	await writeTask(tasksDir, t);
+}
+
+export async function updateTaskAfterDelegation(tasksDir: string, id: string, summary: string, ok: boolean): Promise<void> {
+	const t = getTask(tasksDir, id);
+	if (!t) return;
+	t.status = ok ? "review" : "blocked";
+	t.updated = nowISO();
+	const clipped = summary.length > 200 ? `${summary.slice(0, 200)}…` : summary;
+	t.activity.push(`${nowISO()} — ${ok ? "completed → review" : "failed → blocked"}: ${clipped.replace(/\n/g, " ")}`);
+	await writeTask(tasksDir, t);
+}
+
+// --------------------------------------------------------------- delegation records
+
+export interface DelegationResult {
+	agent: string;
+	task: string;
+	output: string;
+	failed: boolean;
+	stopReason?: string;
+	model?: string;
+}
+
+export async function recordDelegation(
+	delegationsDir: string,
+	mode: string,
+	results: DelegationResult[],
+): Promise<void> {
+	try {
+		fs.mkdirSync(delegationsDir, { recursive: true });
+		const ts = nowISO();
+		const stamp = ts.replace(/[:.]/g, "-");
+		const first = results[0]?.agent ?? "agent";
+		const file = path.join(delegationsDir, `${stamp}-${mode}-${first}.md`);
+		const blocks = results.map((r, i) => {
+			const head = `### [${i + 1}] ${r.agent} — ${r.failed ? `failed${r.stopReason ? ` (${r.stopReason})` : ""}` : "completed"}${r.model ? ` · ${r.model}` : ""}`;
+			return [head, "", "**Task**", r.task.trim(), "", "**Result**", (r.output || "(no output)").trim(), ""].join("\n");
+		});
+		const body = [`# Delegation — ${ts}`, `mode: ${mode}`, "", ...blocks].join("\n");
+		await withFileMutationQueue(file, async () => {
+			await fs.promises.writeFile(file, body, { encoding: "utf-8", mode: 0o600 });
+		});
+	} catch {
+		/* non-fatal */
+	}
+}
+
+// --------------------------------------------------------------- rendering
+
+export function renderBoard(tasks: Task[]): string {
+	if (tasks.length === 0) return "(board empty)";
+	const lines: string[] = [];
+	for (const status of STATUS_ORDER) {
+		const col = tasks.filter((t) => t.status === status);
+		if (col.length === 0) continue;
+		lines.push(`${status} (${col.length}):`);
+		for (const t of col) lines.push(`  - ${t.id} ${t.agent ? `@${t.agent} ` : ""}${t.title}`);
+	}
+	return lines.join("\n");
+}
+
+/** The session-start "resume" block: lists resumable tasks and instructs delegation. */
+export function buildResumePrompt(cwd: string): string | null {
+	const tasks = listResumable(resolveProject(cwd).tasksDir);
+	if (tasks.length === 0) return null;
+	const lines = [
+		"# Open tasks — resume these",
+		"This project has unfinished tasks on its board (persisted from earlier sessions). Resume each",
+		"by delegating it to its designated agent with the `subagent` tool in single mode, passing",
+		"`taskId` so the agent loads the full structured instruction. Keep each task's status current",
+		"(it moves to `review` on success or `blocked` on failure automatically).",
+		"",
+		...tasks.map((t) => `- ${t.id} [${t.status}] ${t.agent ? `→ ${t.agent}` : "(no agent assigned)"}: ${t.title}`),
+	];
+	return lines.join("\n");
+}
+
+// --------------------------------------------------------------- the `task` tool
+
+const TaskParams = Type.Object({
+	action: StringEnum(["create", "update", "list", "get"] as const, {
+		description: "create a task; update fields/status; list the board; get one task's full detail",
+	}),
+	id: Type.Optional(Type.String({ description: "Task id (required for update/get)" })),
+	title: Type.Optional(Type.String({ description: "Short task title (create)" })),
+	instruction: Type.Optional(Type.String({ description: "Full, self-contained instruction the subagent will execute" })),
+	agent: Type.Optional(Type.String({ description: "Designated agent to execute this task (assignee)" })),
+	status: Type.Optional(
+		StringEnum(["backlog", "todo", "in_progress", "blocked", "review", "done", "cancelled"] as const, {
+			description: "Kanban column / status",
+		}),
+	),
+	priority: Type.Optional(StringEnum(["low", "normal", "high"] as const)),
+	acceptance: Type.Optional(Type.Array(Type.String(), { description: "Acceptance criteria (create/update)" })),
+	labels: Type.Optional(Type.Array(Type.String())),
+	dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Task ids this depends on" })),
+	note: Type.Optional(Type.String({ description: "Append a note to the task (update)" })),
+	filter: Type.Optional(StringEnum(["open", "all"] as const, { description: "list filter (default open)" })),
+});
+
+export function registerTaskTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "task",
+		label: "Task board",
+		description:
+			"Manage the persistent project task board (a kanban for delegation). Create tasks with a designated agent and a structured instruction, update status/fields, and list or read tasks. Tasks survive across sessions; unfinished ones are resumed by delegating to their agent (use subagent with taskId).",
+		promptSnippet: "Manage the persistent kanban task board for delegation",
+		promptGuidelines: [
+			"Use the task tool to record durable, multi-step or to-be-delegated work as kanban cards with a designated agent and a clear instruction + acceptance criteria.",
+			"Execute a task by delegating it: call subagent in single mode with that task's taskId; its status updates to review (success) or blocked (failure) automatically.",
+		],
+		parameters: TaskParams,
+		async execute(_id, params, _signal, _onUpdate, ctx: ExtensionContext) {
+			const { tasksDir } = resolveProject(ctx.cwd);
+			const action = params.action as string;
+
+			if (action === "list") {
+				const all = listTasks(tasksDir);
+				const shown = (params.filter ?? "open") === "all" ? all : all.filter((t) => OPEN.has(t.status));
+				return { content: [{ type: "text", text: renderBoard(shown) }], details: { count: shown.length } };
+			}
+
+			if (action === "get") {
+				if (!params.id) return { content: [{ type: "text", text: "get requires id" }], details: { error: true } };
+				const t = getTask(tasksDir, params.id as string);
+				if (!t) return { content: [{ type: "text", text: `No task ${params.id}` }], details: { error: true } };
+				return { content: [{ type: "text", text: serialize(t) }], details: { id: t.id } };
+			}
+
+			if (action === "create") {
+				if (!params.title) return { content: [{ type: "text", text: "create requires title" }], details: { error: true } };
+				const now = nowISO();
+				const t: Task = {
+					id: generateTaskId(),
+					title: params.title as string,
+					status: (params.status as TaskStatus) ?? "todo",
+					agent: (params.agent as string) ?? "",
+					priority: (params.priority as Task["priority"]) ?? "normal",
+					labels: (params.labels as string[]) ?? [],
+					dependsOn: (params.dependsOn as string[]) ?? [],
+					created: now,
+					updated: now,
+					attempts: 0,
+					session: "",
+					instruction: (params.instruction as string) ?? "",
+					acceptance: (params.acceptance as string[]) ?? [],
+					notes: "",
+					activity: [`${now} — created`],
+				};
+				await writeTask(tasksDir, t);
+				return { content: [{ type: "text", text: `Created task ${t.id} (${t.status}${t.agent ? `, @${t.agent}` : ""}).` }], details: { id: t.id } };
+			}
+
+			if (action === "update") {
+				if (!params.id) return { content: [{ type: "text", text: "update requires id" }], details: { error: true } };
+				const t = getTask(tasksDir, params.id as string);
+				if (!t) return { content: [{ type: "text", text: `No task ${params.id}` }], details: { error: true } };
+				const changes: string[] = [];
+				if (params.status) { changes.push(`status→${params.status}`); t.status = params.status as TaskStatus; }
+				if (params.agent !== undefined) { changes.push(`agent→${params.agent}`); t.agent = params.agent as string; }
+				if (params.priority) { changes.push(`priority→${params.priority}`); t.priority = params.priority as Task["priority"]; }
+				if (params.title) t.title = params.title as string;
+				if (params.instruction !== undefined) t.instruction = params.instruction as string;
+				if (params.acceptance) t.acceptance = params.acceptance as string[];
+				if (params.labels) t.labels = params.labels as string[];
+				if (params.dependsOn) t.dependsOn = params.dependsOn as string[];
+				if (params.note) t.notes = t.notes ? `${t.notes}\n${params.note}` : (params.note as string);
+				t.updated = nowISO();
+				t.activity.push(`${nowISO()} — updated${changes.length ? ` (${changes.join(", ")})` : ""}${params.note ? `: ${params.note}` : ""}`);
+				await writeTask(tasksDir, t);
+				return { content: [{ type: "text", text: `Updated task ${t.id}.` }], details: { id: t.id } };
+			}
+
+			return { content: [{ type: "text", text: "Unknown action" }], details: { error: true } };
+		},
+		renderResult(result, _opts, theme) {
+			const text = result.content[0];
+			return new Text(theme.fg("muted", "▣ ") + (text?.type === "text" ? text.text : ""), 0, 0);
+		},
+	});
+}

package/todo.ts

@@ -0,0 +1,149 @@
+/**
+ * `todo_write` — Claude Code's TodoWrite for pi.
+ *
+ * The model calls it with the full, updated task list (it replaces prior state).
+ * State lives in the tool result's `details` (branch-correct on session fork) and
+ * is reconstructed by scanning the session branch on session_start / session_tree.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { resolveProject } from "./project.ts";
+
+type Status = "pending" | "in_progress" | "completed";
+interface Todo {
+	content: string;
+	activeForm: string;
+	status: Status;
+}
+interface TodoDetails {
+	todos: Todo[];
+	warning?: string;
+}
+
+const TodoItem = Type.Object({
+	content: Type.String({ description: "Imperative form, e.g. 'Run tests'" }),
+	activeForm: Type.String({ description: "Present-continuous form shown while active, e.g. 'Running tests'" }),
+	status: StringEnum(["pending", "in_progress", "completed"] as const),
+});
+const TodoWriteParams = Type.Object({
+	todos: Type.Array(TodoItem, { description: "The full, updated todo list (replaces prior state)" }),
+});
+
+const ICON: Record<Status, string> = { pending: "☐", in_progress: "◐", completed: "☑" };
+
+function renderChecklist(todos: Todo[], fg?: (role: string, s: string) => string, strike?: (s: string) => string): string {
+	if (todos.length === 0) return "(no todos)";
+	const done = todos.filter((t) => t.status === "completed").length;
+	const header = `${done}/${todos.length} completed`;
+	const lines = todos.map((t) => {
+		const label = t.status === "in_progress" ? t.activeForm : t.content;
+		if (!fg) return `${ICON[t.status]} ${label}`;
+		if (t.status === "completed") return fg("success", `${ICON.completed} `) + fg("muted", strike ? strike(label) : label);
+		if (t.status === "in_progress") return fg("accent", `${ICON.in_progress} `) + fg("text", label);
+		return fg("muted", `${ICON.pending} `) + label;
+	});
+	return `${header}\n${lines.join("\n")}`;
+}
+
+export function registerTodoTool(pi: ExtensionAPI): void {
+	let todos: Todo[] = [];
+	// one snapshot file per session, overwritten as the list changes
+	const snapshotName = `${new Date().toISOString().slice(0, 10)}-${Math.random().toString(36).slice(2, 8)}.md`;
+
+	const persistSnapshot = (ctx: ExtensionContext) => {
+		try {
+			const { todosDir } = resolveProject(ctx.cwd);
+			fs.mkdirSync(todosDir, { recursive: true });
+			const text = `# Todo snapshot — ${new Date().toISOString()}\n\n${renderChecklist(todos)}\n`;
+			fs.writeFileSync(path.join(todosDir, snapshotName), text, { encoding: "utf-8", mode: 0o600 });
+		} catch {
+			/* non-fatal */
+		}
+	};
+
+	const reconstruct = (ctx: ExtensionContext) => {
+		todos = [];
+		try {
+			for (const entry of (ctx.sessionManager as any).getBranch() ?? []) {
+				if (entry?.type !== "message") continue;
+				const msg = entry.message;
+				if (msg?.role !== "toolResult" || msg?.toolName !== "todo_write") continue;
+				const details = msg.details as TodoDetails | undefined;
+				if (details?.todos) todos = details.todos;
+			}
+		} catch {
+			/* ignore */
+		}
+	};
+
+	const updateStatus = (ctx: ExtensionContext) => {
+		if (!ctx.hasUI) return;
+		if (todos.length === 0) {
+			ctx.ui.setStatus("todos", undefined);
+			return;
+		}
+		const done = todos.filter((t) => t.status === "completed").length;
+		ctx.ui.setStatus("todos", ctx.ui.theme.fg("muted", `▣ ${done}/${todos.length}`));
+	};
+
+	pi.on("session_start", async (_e, ctx) => {
+		reconstruct(ctx);
+		updateStatus(ctx);
+	});
+	pi.on("session_tree", async (_e, ctx) => {
+		reconstruct(ctx);
+		updateStatus(ctx);
+	});
+
+	pi.registerTool({
+		name: "todo_write",
+		label: "Todos",
+		description:
+			"Manage the task list for the current work. Call with the FULL updated list whenever a task starts or finishes — it replaces the previous list. Keep exactly one task 'in_progress' at a time and mark a task 'completed' immediately when done (do not batch).",
+		promptSnippet: "Track multi-step work with a todo list",
+		promptGuidelines: [
+			"Use todo_write for any non-trivial multi-step task; update it as you start/finish each step.",
+			"Exactly one todo should be in_progress at a time.",
+		],
+		parameters: TodoWriteParams,
+
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			todos = params.todos as Todo[];
+			const inProgress = todos.filter((t) => t.status === "in_progress").length;
+			let warning: string | undefined;
+			if (todos.length > 0 && inProgress !== 1) {
+				warning = `Expected exactly one in_progress task, found ${inProgress}.`;
+			}
+			updateStatus(ctx);
+			persistSnapshot(ctx);
+			const text = renderChecklist(todos);
+			return {
+				content: [{ type: "text" as const, text: warning ? `${text}\n\n⚠ ${warning}` : text }],
+				details: { todos, warning } satisfies TodoDetails,
+			};
+		},
+
+		renderResult(result, _opts, theme) {
+			const d = result.details as TodoDetails | undefined;
+			const list = d?.todos ?? [];
+			let text = renderChecklist(list, (role, s) => theme.fg(role, s), (s) => theme.strikethrough(s));
+			if (d?.warning) text += `\n${theme.fg("warning", `⚠ ${d.warning}`)}`;
+			return new Text(text, 0, 0);
+		},
+	});
+
+	pi.registerCommand("todos", {
+		description: "Show the current task list",
+		handler: async (_args, ctx) => {
+			reconstruct(ctx);
+			if (!ctx.hasUI) return;
+			const text = renderChecklist(todos, (role, s) => ctx.ui.theme.fg(role, s), (s) => ctx.ui.theme.strikethrough(s));
+			ctx.ui.notify(`Todos:\n${text}`, "info");
+		},
+	});
+}