pi-thread-engine 0.1.0

package/src/core/executor.ts

@@ -0,0 +1,200 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ThreadRegistry } from "./registry.js";
+import type { Thread, ThreadTask } from "./types.js";
+
+/**
+ * Executor — runs thread tasks.
+ *
+ * Two backends:
+ * - "subagent": delegates to pi-subagents via sendUserMessage (inherits agent specialization, TUI, artifacts)
+ * - "native": spawns pi -p directly (for fusion/zero where we need raw control)
+ */
+export class ThreadExecutor {
+	constructor(
+		private pi: ExtensionAPI,
+		private registry: ThreadRegistry
+	) {}
+
+	// ── Native execution (pi -p) ────────────────────────────────
+
+	private async runTaskNative(thread: Thread, task: ThreadTask): Promise<void> {
+		const cwd = thread.config.cwd ?? process.cwd();
+		this.registry.startTask(thread.id, task.id);
+
+		try {
+			const args = ["-p", task.prompt];
+			if (task.model) args.unshift("-m", task.model);
+
+			const result = await this.pi.exec("pi", args, {
+				cwd,
+				timeout: 10 * 60 * 1000,
+			});
+
+			if (result.code === 0) {
+				this.registry.completeTask(thread.id, task.id, result.stdout);
+			} else {
+				this.registry.failTask(thread.id, task.id, result.stderr || `Exit code: ${result.code}`);
+			}
+		} catch (err: any) {
+			this.registry.failTask(thread.id, task.id, err.message ?? String(err));
+		}
+	}
+
+	// ── Subagent execution (via sendUserMessage) ────────────────
+
+	private launchSubagentParallel(thread: Thread): void {
+		const agent = thread.config.agent ?? "worker";
+		const tasks = thread.tasks.map((t) => ({
+			agent,
+			task: t.prompt,
+			...(t.model ? { model: t.model } : {}),
+		}));
+
+		// Send as a user message that pi-subagents will pick up
+		this.pi.sendUserMessage(
+			`Run these tasks in parallel using subagent:\n\`\`\`json\n${JSON.stringify({ tasks }, null, 2)}\n\`\`\``,
+			{ deliverAs: "followUp" }
+		);
+
+		// Mark all tasks as running (subagent handles the rest)
+		this.registry.startThread(thread.id);
+		for (const task of thread.tasks) {
+			this.registry.startTask(thread.id, task.id);
+		}
+	}
+
+	private launchSubagentChain(thread: Thread): void {
+		const agent = thread.config.agent ?? "worker";
+		const chain = thread.tasks.map((t, i) => ({
+			agent,
+			task: i === 0 ? t.prompt : `Continue: ${t.prompt}. Previous context: {previous}`,
+			...(t.model ? { model: t.model } : {}),
+		}));
+
+		this.pi.sendUserMessage(
+			`Run this chain using subagent:\n\`\`\`json\n${JSON.stringify({ chain }, null, 2)}\n\`\`\``,
+			{ deliverAs: "followUp" }
+		);
+
+		this.registry.startThread(thread.id);
+		this.registry.startTask(thread.id, thread.tasks[0].id);
+	}
+
+	private launchSubagentMeta(thread: Thread): void {
+		const chain = [
+			{ agent: "scout", task: thread.tasks[0]?.prompt ?? "Scout the codebase" },
+			{ agent: "planner", task: "{previous}" },
+			{ agent: "worker", task: "{previous}" },
+			{ agent: "reviewer", task: "{previous}" },
+		];
+
+		this.pi.sendUserMessage(
+			`Run this meta pipeline using subagent:\n\`\`\`json\n${JSON.stringify({ chain }, null, 2)}\n\`\`\``,
+			{ deliverAs: "followUp" }
+		);
+
+		this.registry.startThread(thread.id);
+		this.registry.startTask(thread.id, thread.tasks[0].id);
+	}
+
+	// ── Fusion (native, multi-model) ────────────────────────────
+
+	async execFusion(thread: Thread): Promise<void> {
+		this.registry.startThread(thread.id);
+		// All tasks run in parallel with potentially different models
+		await Promise.allSettled(thread.tasks.map((task) => this.runTaskNative(thread, task)));
+	}
+
+	// ── Zero-touch (native + verification) ──────────────────────
+
+	async execZero(thread: Thread): Promise<void> {
+		this.registry.startThread(thread.id);
+		const task = thread.tasks[0];
+		await this.runTaskNative(thread, task);
+
+		// If task succeeded and we have a verify command, run it
+		if (task.state === "completed" && thread.config.verifyCommand) {
+			const cwd = thread.config.cwd ?? process.cwd();
+			try {
+				const verify = await this.pi.exec("bash", ["-c", thread.config.verifyCommand], {
+					cwd,
+					timeout: 5 * 60 * 1000,
+				});
+				if (verify.code !== 0) {
+					// Override the completed state to failed
+					task.state = "failed";
+					task.error = `Verification failed (${thread.config.verifyCommand}): ${verify.stderr || verify.stdout}`;
+					thread.state = "failed";
+					thread.completedAt = Date.now();
+					thread.duration = thread.completedAt - (thread.startedAt ?? thread.createdAt);
+				}
+			} catch (err: any) {
+				task.state = "failed";
+				task.error = `Verification error: ${err.message}`;
+				thread.state = "failed";
+				thread.completedAt = Date.now();
+			}
+		}
+	}
+
+	// ── Dispatch ─────────────────────────────────────────────────
+
+	async dispatch(
+		thread: Thread,
+		opts?: { onCheckpoint?: (phase: number, task: ThreadTask) => Promise<boolean> }
+	): Promise<void> {
+		const backend = thread.config.backend;
+
+		if (backend === "subagent") {
+			switch (thread.type) {
+				case "parallel":
+					return this.launchSubagentParallel(thread);
+				case "chained":
+					return this.launchSubagentChain(thread);
+				case "meta":
+					return this.launchSubagentMeta(thread);
+				default:
+					// Fall through to native for unsupported subagent types
+					break;
+			}
+		}
+
+		// Native execution
+		switch (thread.type) {
+			case "base":
+			case "long":
+				this.registry.startThread(thread.id);
+				return this.runTaskNative(thread, thread.tasks[0]);
+			case "parallel":
+				this.registry.startThread(thread.id);
+				await Promise.allSettled(thread.tasks.map((t) => this.runTaskNative(thread, t)));
+				return;
+			case "fusion":
+				return this.execFusion(thread);
+			case "zero":
+				return this.execZero(thread);
+			case "chained": {
+				this.registry.startThread(thread.id);
+				for (let i = 0; i < thread.tasks.length; i++) {
+					if (i > 0 && opts?.onCheckpoint) {
+						const proceed = await opts.onCheckpoint(i, thread.tasks[i]);
+						if (!proceed) {
+							this.registry.kill(thread.id);
+							return;
+						}
+					}
+					await this.runTaskNative(thread, thread.tasks[i]);
+					if (thread.tasks[i].state === "failed") return;
+				}
+				return;
+			}
+			case "meta":
+				this.registry.startThread(thread.id);
+				for (const task of thread.tasks) {
+					await this.runTaskNative(thread, task);
+					if (task.state === "failed") return;
+				}
+				return;
+		}
+	}
+}

package/src/core/registry.ts

@@ -0,0 +1,281 @@
+import type { ExecutionBackend, Story, StoryPhase, Thread, ThreadEvent, ThreadState, ThreadSummary, ThreadTask, ThreadType } from "./types.js";
+
+type EventHandler = (event: ThreadEvent) => void;
+
+let nextThreadId = 1;
+let nextStoryId = 1;
+
+function genThreadId(): string {
+	return `t-${String(nextThreadId++).padStart(3, "0")}`;
+}
+
+function genStoryId(): string {
+	return `s-${String(nextStoryId++).padStart(3, "0")}`;
+}
+
+function genTaskId(threadId: string, index: number): string {
+	return `${threadId}.${index + 1}`;
+}
+
+/** Format elapsed time */
+export function formatElapsed(ms: number): string {
+	if (ms < 1000) return `${ms}ms`;
+	const s = Math.floor(ms / 1000);
+	if (s < 60) return `${s}s`;
+	const m = Math.floor(s / 60);
+	const rem = s % 60;
+	if (m < 60) return `${m}m ${rem}s`;
+	const h = Math.floor(m / 60);
+	return `${h}h ${m % 60}m`;
+}
+
+/** Central registry for all threads and stories */
+export class ThreadRegistry {
+	private threads = new Map<string, Thread>();
+	private stories = new Map<string, Story>();
+	private handlers: EventHandler[] = [];
+
+	on(handler: EventHandler): () => void {
+		this.handlers.push(handler);
+		return () => {
+			const idx = this.handlers.indexOf(handler);
+			if (idx >= 0) this.handlers.splice(idx, 1);
+		};
+	}
+
+	private emit(event: ThreadEvent) {
+		for (const h of this.handlers) {
+			try {
+				h(event);
+			} catch {}
+		}
+	}
+
+	// ── Threads ──────────────────────────────────────────────────
+
+	create(
+		type: ThreadType,
+		label: string,
+		prompts: string[],
+		opts?: { models?: string[]; cwd?: string; backend?: ExecutionBackend; agent?: string; verify?: string }
+	): Thread {
+		const threadId = genThreadId();
+		const tasks: ThreadTask[] = prompts.map((prompt, i) => ({
+			id: genTaskId(threadId, i),
+			label: prompt.length > 60 ? prompt.slice(0, 57) + "..." : prompt,
+			prompt,
+			model: opts?.models?.[i],
+			state: "pending" as ThreadState,
+		}));
+
+		const thread: Thread = {
+			id: threadId,
+			type,
+			label,
+			state: "pending",
+			config: {
+				type,
+				tasks,
+				backend: opts?.backend ?? "native",
+				cwd: opts?.cwd,
+				models: opts?.models,
+				agent: opts?.agent,
+				verifyCommand: opts?.verify,
+			},
+			tasks,
+			createdAt: Date.now(),
+		};
+
+		this.threads.set(threadId, thread);
+		this.emit({ type: "thread_created", thread });
+		return thread;
+	}
+
+	get(id: string): Thread | undefined {
+		return this.threads.get(id);
+	}
+
+	all(): Thread[] {
+		return [...this.threads.values()];
+	}
+
+	byState(state: ThreadState): Thread[] {
+		return this.all().filter((t) => t.state === state);
+	}
+
+	startThread(id: string) {
+		const t = this.threads.get(id);
+		if (!t) return;
+		t.state = "running";
+		t.startedAt = Date.now();
+		this.emit({ type: "thread_started", thread: t });
+	}
+
+	startTask(threadId: string, taskId: string, sessionId?: string) {
+		const t = this.threads.get(threadId);
+		if (!t) return;
+		const task = t.tasks.find((tk) => tk.id === taskId);
+		if (!task) return;
+		task.state = "running";
+		task.startedAt = Date.now();
+		if (sessionId) task.sessionId = sessionId;
+		this.emit({ type: "task_started", thread: t, task });
+	}
+
+	completeTask(threadId: string, taskId: string, result?: string) {
+		const t = this.threads.get(threadId);
+		if (!t) return;
+		const task = t.tasks.find((tk) => tk.id === taskId);
+		if (!task) return;
+		task.state = "completed";
+		task.completedAt = Date.now();
+		if (result) task.result = result;
+		this.emit({ type: "task_completed", thread: t, task });
+
+		if (t.tasks.every((tk) => tk.state === "completed")) {
+			t.state = "completed";
+			t.completedAt = Date.now();
+			t.duration = t.completedAt - (t.startedAt ?? t.createdAt);
+			this.emit({ type: "thread_completed", thread: t });
+		}
+	}
+
+	failTask(threadId: string, taskId: string, error: string) {
+		const t = this.threads.get(threadId);
+		if (!t) return;
+		const task = t.tasks.find((tk) => tk.id === taskId);
+		if (!task) return;
+		task.state = "failed";
+		task.completedAt = Date.now();
+		task.error = error;
+		this.emit({ type: "task_failed", thread: t, task });
+
+		// For parallel/fusion: don't fail the whole thread if one task fails
+		if (t.type === "parallel" || t.type === "fusion") {
+			const allDone = t.tasks.every((tk) => tk.state === "completed" || tk.state === "failed");
+			if (allDone) {
+				const anySuccess = t.tasks.some((tk) => tk.state === "completed");
+				t.state = anySuccess ? "completed" : "failed";
+				t.completedAt = Date.now();
+				t.duration = t.completedAt - (t.startedAt ?? t.createdAt);
+				this.emit(anySuccess ? { type: "thread_completed", thread: t } : { type: "thread_failed", thread: t });
+			}
+		} else {
+			t.state = "failed";
+			t.completedAt = Date.now();
+			t.duration = t.completedAt - (t.startedAt ?? t.createdAt);
+			this.emit({ type: "thread_failed", thread: t });
+		}
+	}
+
+	kill(id: string) {
+		const t = this.threads.get(id);
+		if (!t) return;
+		t.state = "killed";
+		t.completedAt = Date.now();
+		t.duration = t.completedAt - (t.startedAt ?? t.createdAt);
+		for (const task of t.tasks) {
+			if (task.state === "running" || task.state === "pending") {
+				task.state = "killed";
+				task.completedAt = Date.now();
+			}
+		}
+		this.emit({ type: "thread_killed", thread: t });
+	}
+
+	summarize(thread: Thread): ThreadSummary {
+		const done = thread.tasks.filter((t) => t.state === "completed").length;
+		const failed = thread.tasks.filter((t) => t.state === "failed").length;
+		const total = thread.tasks.length;
+		const elapsed = thread.startedAt ? formatElapsed(Date.now() - thread.startedAt) : "-";
+		const progress = failed > 0 ? `${done}/${total} (${failed}✗)` : `${done}/${total}`;
+
+		return {
+			id: thread.id,
+			type: thread.type,
+			label: thread.label,
+			state: thread.state,
+			progress,
+			elapsed,
+			backend: thread.config.backend,
+		};
+	}
+
+	prune() {
+		for (const [id, t] of this.threads) {
+			if (t.state === "completed" || t.state === "failed" || t.state === "killed") {
+				this.threads.delete(id);
+			}
+		}
+	}
+
+	/** Restore state from session persistence */
+	restore(threads: Thread[], stories: Story[]) {
+		for (const t of threads) {
+			this.threads.set(t.id, t);
+		}
+		for (const s of stories) {
+			this.stories.set(s.id, s);
+		}
+	}
+
+	// ── Stories ──────────────────────────────────────────────────
+
+	createStory(goal: string, verify?: string): Story {
+		const story: Story = {
+			id: genStoryId(),
+			goal,
+			state: "planning",
+			phases: [],
+			createdAt: Date.now(),
+			verify,
+			artifacts: [],
+		};
+		this.stories.set(story.id, story);
+		this.emit({ type: "story_created", story });
+		return story;
+	}
+
+	getStory(id: string): Story | undefined {
+		return this.stories.get(id);
+	}
+
+	allStories(): Story[] {
+		return [...this.stories.values()];
+	}
+
+	addPhase(storyId: string, phase: StoryPhase) {
+		const s = this.stories.get(storyId);
+		if (!s) return;
+		s.phases.push(phase);
+	}
+
+	startPhase(storyId: string, phaseIndex: number, threadId: string) {
+		const s = this.stories.get(storyId);
+		if (!s || !s.phases[phaseIndex]) return;
+		s.phases[phaseIndex].state = "running";
+		s.phases[phaseIndex].threadId = threadId;
+		s.state = "executing";
+		this.emit({ type: "story_phase_started", story: s, phase: s.phases[phaseIndex] });
+	}
+
+	completePhase(storyId: string, phaseIndex: number) {
+		const s = this.stories.get(storyId);
+		if (!s || !s.phases[phaseIndex]) return;
+		s.phases[phaseIndex].state = "completed";
+
+		if (s.phases.every((p) => p.state === "completed")) {
+			s.state = "done";
+			s.completedAt = Date.now();
+			this.emit({ type: "story_completed", story: s });
+		}
+	}
+
+	failStory(storyId: string) {
+		const s = this.stories.get(storyId);
+		if (!s) return;
+		s.state = "failed";
+		s.completedAt = Date.now();
+		this.emit({ type: "story_failed", story: s });
+	}
+}

package/src/core/types.ts

@@ -0,0 +1,104 @@
+/** Thread types from the thread engineering framework */
+export type ThreadType = "base" | "parallel" | "chained" | "fusion" | "meta" | "long" | "zero";
+
+/** Thread lifecycle states */
+export type ThreadState = "pending" | "running" | "paused" | "completed" | "failed" | "killed";
+
+/** How a thread is executed */
+export type ExecutionBackend = "subagent" | "native";
+
+/** A single unit of work within a thread */
+export interface ThreadTask {
+	id: string;
+	label: string;
+	prompt: string;
+	model?: string;
+	state: ThreadState;
+	startedAt?: number;
+	completedAt?: number;
+	result?: string;
+	error?: string;
+	/** interactive_shell session ID or subagent run ID */
+	sessionId?: string;
+}
+
+/** Thread configuration */
+export interface ThreadConfig {
+	type: ThreadType;
+	tasks: ThreadTask[];
+	/** Execution backend */
+	backend: ExecutionBackend;
+	/** For fusion threads: models to compete */
+	models?: string[];
+	/** For zero threads: verification command */
+	verifyCommand?: string;
+	/** For chained threads: require human checkpoint between phases */
+	checkpoints?: boolean;
+	/** Working directory */
+	cwd?: string;
+	/** Subagent agent name to use (default: "worker") */
+	agent?: string;
+}
+
+/** A thread — the fundamental unit of tracked work */
+export interface Thread {
+	id: string;
+	type: ThreadType;
+	label: string;
+	state: ThreadState;
+	config: ThreadConfig;
+	tasks: ThreadTask[];
+	createdAt: number;
+	startedAt?: number;
+	completedAt?: number;
+	/** Duration in ms */
+	duration?: number;
+}
+
+/** A story — a goal decomposed into thread phases */
+export interface Story {
+	id: string;
+	goal: string;
+	state: "planning" | "executing" | "verifying" | "done" | "failed";
+	phases: StoryPhase[];
+	createdAt: number;
+	completedAt?: number;
+	/** Verification command */
+	verify?: string;
+	/** Files changed */
+	artifacts: string[];
+}
+
+export interface StoryPhase {
+	name: string;
+	threadType: ThreadType;
+	threadId?: string;
+	state: ThreadState;
+	description: string;
+}
+
+/** Short status line for dashboard */
+export interface ThreadSummary {
+	id: string;
+	type: ThreadType;
+	label: string;
+	state: ThreadState;
+	progress: string;
+	elapsed: string;
+	backend: ExecutionBackend;
+}
+
+/** Thread event for state changes */
+export type ThreadEvent =
+	| { type: "thread_created"; thread: Thread }
+	| { type: "thread_started"; thread: Thread }
+	| { type: "task_started"; thread: Thread; task: ThreadTask }
+	| { type: "task_completed"; thread: Thread; task: ThreadTask }
+	| { type: "task_failed"; thread: Thread; task: ThreadTask }
+	| { type: "thread_completed"; thread: Thread }
+	| { type: "thread_failed"; thread: Thread }
+	| { type: "thread_killed"; thread: Thread }
+	| { type: "story_created"; story: Story }
+	| { type: "story_phase_started"; story: Story; phase: StoryPhase }
+	| { type: "story_completed"; story: Story }
+	| { type: "story_failed"; story: Story };