pi-dynamic-workflow 0.1.0

package/src/index.ts

@@ -0,0 +1,122 @@
+/**
+ * pi-dynamic-workflow extension entry point.
+ *
+ * Registers the `/workflow` command and a compact renderer for the injected
+ * authoring brief. The `workflow` tool itself is registered lazily on first
+ * use so sessions that never invoke `/workflow` do not carry it in their
+ * system prompt.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { WORKFLOW_GUIDE } from "./guide.ts";
+import { discoverWorkflows } from "./registry.ts";
+import { createWorkflowTool, listActiveWorkflowRuns, stopWorkflowRun, WORKFLOW_COMPLETE_TYPE } from "./tool.ts";
+
+const BRIEF_TYPE = "dynamic-workflow-brief";
+
+export default function (pi: ExtensionAPI) {
+	const workflowTool = createWorkflowTool(pi);
+	let toolRegistered = false;
+
+	const ensureToolRegistered = () => {
+		if (toolRegistered) return;
+		toolRegistered = true;
+		pi.registerTool(workflowTool);
+		pi.setActiveTools([...new Set([...pi.getActiveTools(), "workflow"])]);
+	};
+
+	pi.registerCommand("workflow", {
+		description: "Author and run a dynamic multi-agent workflow: /workflow <task>",
+		handler: async (args, ctx) => {
+			const task = args.trim();
+			if (!task) {
+				ctx.ui.notify("Usage: /workflow <task description>", "warning");
+				return;
+			}
+			ensureToolRegistered();
+			const sections = [WORKFLOW_GUIDE];
+			const saved = discoverWorkflows(ctx.cwd);
+			if (saved.size > 0) {
+				const list = [...saved.values()]
+					.map((w) => `- ${w.name} (${w.source})${w.description ? `: ${w.description}` : ""}`)
+					.join("\n");
+				sections.push(
+					`## Saved workflows\n\nWhen one of these fits the task, invoke the tool with \`workflowName\` (plus \`args\`) instead of authoring a script:\n\n${list}`,
+				);
+			}
+			sections.push(`## Task\n\n${task}`);
+			pi.sendMessage(
+				{
+					customType: BRIEF_TYPE,
+					content: sections.join("\n\n"),
+					display: true,
+					details: { task },
+				},
+				{ triggerTurn: true },
+			);
+		},
+	});
+
+	pi.registerCommand("workflow-stop", {
+		description: "Stop a background workflow run: /workflow-stop <runId>",
+		handler: async (args, ctx) => {
+			const runId = args.trim();
+			if (!runId) {
+				const active = listActiveWorkflowRuns();
+				ctx.ui.notify(
+					active.length > 0
+						? `Active background runs: ${active.join(", ")}. Usage: /workflow-stop <runId>`
+						: "No background workflow runs are active.",
+					"info",
+				);
+				return;
+			}
+			if (stopWorkflowRun(runId)) {
+				ctx.ui.notify(`Aborting background workflow run ${runId}`, "info");
+			} else {
+				ctx.ui.notify(`No active background run "${runId}"`, "warning");
+			}
+		},
+	});
+
+	pi.registerMessageRenderer(WORKFLOW_COMPLETE_TYPE, (message, { expanded }, theme) => {
+		const content = String(message.content);
+		if (expanded) return new Text(theme.fg("muted", content), 0, 0);
+		const firstLine = content.split("\n")[0] ?? "";
+		return new Text(theme.fg("accent", "workflow complete ") + theme.fg("dim", firstLine), 0, 0);
+	});
+
+	// Background runs must not outlive the session that owns their subprocesses.
+	pi.on("session_shutdown", () => {
+		for (const runId of listActiveWorkflowRuns()) stopWorkflowRun(runId);
+	});
+
+	pi.registerMessageRenderer<{ task?: string }>(BRIEF_TYPE, (message, { expanded }, theme) => {
+		if (expanded) {
+			return new Text(theme.fg("muted", String(message.content)), 0, 0);
+		}
+		const task = message.details?.task ?? "";
+		const preview = task.length > 80 ? `${task.slice(0, 80)}...` : task;
+		return new Text(
+			theme.fg("accent", "workflow brief ") + theme.fg("dim", preview || "(authoring guide injected)"),
+			0,
+			0,
+		);
+	});
+
+	// Resumed sessions whose branch already contains workflow tool calls need
+	// the tool re-registered so prior results render and remain re-invocable.
+	pi.on("session_start", (_event, ctx) => {
+		for (const entry of ctx.sessionManager.getBranch()) {
+			if (
+				entry.type === "message" &&
+				entry.message.role === "toolResult" &&
+				entry.message.toolName === "workflow"
+			) {
+				ensureToolRegistered();
+				break;
+			}
+		}
+	});
+}

package/src/journal.ts

@@ -0,0 +1,182 @@
+/**
+ * Per-run journaling for resume: every run records each successful agent()
+ * call (keyed by a hash of prompt + behavioral options) to
+ * `<agentDir>/pi-dynamic-workflow/runs/<runId>.jsonl` — one meta line followed
+ * by one appended line per completed call, so a crash mid-run loses at most
+ * the final partial line. A later run passing `resumeFromRunId` replays cached
+ * results for matching calls and only spawns subagents for new or changed ones.
+ *
+ * Cache semantics are a multiset (hash → queue of results in completion
+ * order), not a strict sequence: parallel() completes in nondeterministic
+ * order, so position-based matching would spuriously bust the cache.
+ */
+
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import type { AgentOptions, UsageStats } from "./types.ts";
+
+/** Runs beyond this count are pruned oldest-first when a new journal is created. */
+const MAX_KEPT_RUNS = 50;
+
+export interface JournalEntry {
+	hash: string;
+	label: string;
+	outputText: string;
+	structured?: unknown;
+	model?: string;
+	usage: UsageStats;
+}
+
+export interface RunJournal {
+	runId: string;
+	name: string;
+	description: string;
+	script: string;
+	createdAt: number;
+	entries: JournalEntry[];
+}
+
+export function runsDir(): string {
+	return path.join(getAgentDir(), "pi-dynamic-workflow", "runs");
+}
+
+export function journalPath(runId: string): string {
+	return path.join(runsDir(), `${runId}.jsonl`);
+}
+
+export function newRunId(name: string): string {
+	// Host-side code; the sandbox determinism guards do not apply here.
+	const slug = name.replace(/[^a-zA-Z0-9-]/g, "-").slice(0, 40) || "workflow";
+	return `${slug}-${Date.now().toString(36)}-${crypto.randomBytes(3).toString("hex")}`;
+}
+
+function stableStringify(value: unknown): string {
+	if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "undefined";
+	if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+	const entries = Object.entries(value as Record<string, unknown>)
+		.filter(([, v]) => v !== undefined)
+		.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+		.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`);
+	return `{${entries.join(",")}}`;
+}
+
+/**
+ * Cache key for one agent() call. Display-only options (label, phase) are
+ * excluded so cosmetic edits to a script do not invalidate cached results.
+ * The resolved agent-type definition is behavioral: editing the `.md` between
+ * runs must invalidate the cache, not silently replay stale results.
+ */
+export function agentCallHash(
+	prompt: string,
+	opts: AgentOptions,
+	resolvedAgentType?: { systemPrompt: string; tools?: string[]; model?: string },
+): string {
+	const behavioral = {
+		prompt,
+		model: opts.model,
+		tools: opts.tools,
+		cwd: opts.cwd,
+		schema: opts.schema,
+		systemPrompt: opts.systemPrompt,
+		appendSystemPrompt: opts.appendSystemPrompt,
+		agentType: opts.agentType,
+		agentTypeResolved: resolvedAgentType
+			? {
+					systemPrompt: resolvedAgentType.systemPrompt,
+					tools: resolvedAgentType.tools,
+					model: resolvedAgentType.model,
+				}
+			: undefined,
+		timeout: opts.timeout,
+	};
+	return crypto.createHash("sha256").update(stableStringify(behavioral)).digest("hex");
+}
+
+/** Load a run journal; returns null when missing or unreadable. */
+export function loadJournal(runId: string): RunJournal | null {
+	try {
+		const lines = fs.readFileSync(journalPath(runId), "utf-8").split("\n");
+		const metaLine = lines.shift();
+		if (!metaLine?.trim()) return null;
+		const meta = JSON.parse(metaLine) as Omit<RunJournal, "entries">;
+		const entries: JournalEntry[] = [];
+		for (const line of lines) {
+			if (!line.trim()) continue;
+			try {
+				entries.push(JSON.parse(line) as JournalEntry);
+			} catch {
+				// A truncated tail line (crash mid-append) invalidates only itself.
+			}
+		}
+		return { ...meta, entries };
+	} catch {
+		return null;
+	}
+}
+
+/** Group journal entries into hash → queue-of-results, preserving order. */
+export function buildResumeCache(journal: RunJournal): Map<string, JournalEntry[]> {
+	const cache = new Map<string, JournalEntry[]>();
+	for (const entry of journal.entries) {
+		const queue = cache.get(entry.hash);
+		if (queue) queue.push(entry);
+		else cache.set(entry.hash, [entry]);
+	}
+	return cache;
+}
+
+function pruneOldRuns(dir: string): void {
+	let entries: Array<{ path: string; mtimeMs: number }>;
+	try {
+		entries = fs
+			.readdirSync(dir)
+			.filter((f) => f.endsWith(".jsonl"))
+			.map((f) => {
+				const p = path.join(dir, f);
+				return { path: p, mtimeMs: fs.statSync(p).mtimeMs };
+			});
+	} catch {
+		return;
+	}
+	if (entries.length <= MAX_KEPT_RUNS) return;
+	entries.sort((a, b) => a.mtimeMs - b.mtimeMs);
+	for (const stale of entries.slice(0, entries.length - MAX_KEPT_RUNS)) {
+		try {
+			fs.rmSync(stale.path, { force: true });
+		} catch {
+			// best-effort
+		}
+	}
+}
+
+/**
+ * Journals a run as it progresses: a meta line at creation, then one appended
+ * line per recorded call — O(1) per entry, no full-file rewrites. All disk I/O
+ * is best-effort: a failed write must never take down the workflow it is
+ * recording.
+ */
+export class JournalWriter {
+	readonly filePath: string;
+
+	constructor(meta: { runId: string; name: string; description: string; script: string }) {
+		this.filePath = journalPath(meta.runId);
+		try {
+			fs.mkdirSync(runsDir(), { recursive: true });
+			fs.writeFileSync(this.filePath, `${JSON.stringify({ ...meta, createdAt: Date.now() })}\n`);
+			// Prune after writing so this run (newest mtime) survives the cut.
+			pruneOldRuns(runsDir());
+		} catch {
+			// best-effort
+		}
+	}
+
+	record(entry: JournalEntry): void {
+		try {
+			fs.appendFileSync(this.filePath, `${JSON.stringify(entry)}\n`);
+		} catch {
+			// best-effort
+		}
+	}
+}

package/src/registry.ts

@@ -0,0 +1,101 @@
+/**
+ * Registry of saved workflow scripts: `~/.pi/agent/workflows/*.js` (user) and
+ * the nearest `<project>/.pi/workflows/*.js` (project, overrides user on name
+ * collision). A file's name (minus extension) is the workflow name; a leading
+ * `//` comment line doubles as its description.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export interface SavedWorkflow {
+	name: string;
+	description?: string;
+	filePath: string;
+	source: "user" | "project";
+}
+
+function firstCommentLine(source: string): string | undefined {
+	const line = source.split("\n", 1)[0]?.trim();
+	if (line?.startsWith("//")) return line.replace(/^\/\/\s*/, "");
+	return undefined;
+}
+
+function loadWorkflowsFromDir(dir: string, source: "user" | "project"): SavedWorkflow[] {
+	const workflows: SavedWorkflow[] = [];
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return workflows;
+	}
+
+	for (const entry of entries) {
+		if (!entry.name.endsWith(".js")) continue;
+		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+		const filePath = path.join(dir, entry.name);
+		let description: string | undefined;
+		try {
+			description = firstCommentLine(fs.readFileSync(filePath, "utf-8"));
+		} catch {
+			continue;
+		}
+		workflows.push({
+			name: entry.name.slice(0, -".js".length),
+			...(description ? { description } : {}),
+			filePath,
+			source,
+		});
+	}
+	return workflows;
+}
+
+function findNearestProjectWorkflowsDir(cwd: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		const candidate = path.join(currentDir, CONFIG_DIR_NAME, "workflows");
+		try {
+			if (fs.statSync(candidate).isDirectory()) return candidate;
+		} catch {
+			// keep walking up
+		}
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+
+/** Discover saved workflows; project entries override user entries by name. */
+export function discoverWorkflows(cwd: string): Map<string, SavedWorkflow> {
+	const map = new Map<string, SavedWorkflow>();
+	for (const wf of loadWorkflowsFromDir(path.join(getAgentDir(), "workflows"), "user")) {
+		map.set(wf.name, wf);
+	}
+	const projectDir = findNearestProjectWorkflowsDir(cwd);
+	if (projectDir) {
+		for (const wf of loadWorkflowsFromDir(projectDir, "project")) {
+			map.set(wf.name, wf);
+		}
+	}
+	return map;
+}
+
+/**
+ * Load a workflow script body by saved name or by path (anything containing a
+ * path separator or ending in .js is treated as a path relative to `cwd`).
+ */
+export function loadWorkflowSource(nameOrPath: string, cwd: string): { source: string; filePath: string } {
+	const looksLikePath = nameOrPath.includes("/") || nameOrPath.includes(path.sep) || nameOrPath.endsWith(".js");
+	if (looksLikePath) {
+		const filePath = path.resolve(cwd, nameOrPath);
+		return { source: fs.readFileSync(filePath, "utf-8"), filePath };
+	}
+	const workflows = discoverWorkflows(cwd);
+	const saved = workflows.get(nameOrPath);
+	if (!saved) {
+		const available = [...workflows.keys()].join(", ") || "(none found)";
+		throw new Error(`Unknown workflow "${nameOrPath}". Saved workflows: ${available}`);
+	}
+	return { source: fs.readFileSync(saved.filePath, "utf-8"), filePath: saved.filePath };
+}

package/src/render.ts

@@ -0,0 +1,183 @@
+/** TUI rendering for the `workflow` tool. */
+
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import type { AgentRecord, UsageStats, WorkflowDetails } from "./types.ts";
+
+const COLLAPSED_LOG_COUNT = 5;
+
+function formatTokens(count: number): string {
+	if (count < 1000) return count.toString();
+	if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+	if (count < 1000000) return `${Math.round(count / 1000)}k`;
+	return `${(count / 1000000).toFixed(1)}M`;
+}
+
+function formatUsage(usage: UsageStats, model?: string): string {
+	const parts: string[] = [];
+	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
+	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+	if (model) parts.push(model);
+	return parts.join(" ");
+}
+
+function aggregateUsage(agents: AgentRecord[]): UsageStats {
+	const total: UsageStats = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+	for (const a of agents) {
+		total.input += a.usage.input;
+		total.output += a.usage.output;
+		total.cacheRead += a.usage.cacheRead;
+		total.cacheWrite += a.usage.cacheWrite;
+		total.cost += a.usage.cost;
+		total.turns += a.usage.turns;
+	}
+	return total;
+}
+
+function statusIcon(status: AgentRecord["status"], theme: Theme): string {
+	switch (status) {
+		case "queued":
+			return theme.fg("muted", "·");
+		case "running":
+			return theme.fg("warning", "⏳");
+		case "done":
+			return theme.fg("success", "✓");
+		case "error":
+			return theme.fg("error", "✗");
+		case "aborted":
+			return theme.fg("muted", "⊘");
+		case "cached":
+			return theme.fg("success", "↺");
+	}
+}
+
+/** Group agents by phase, preserving first-seen phase order. */
+function groupByPhase(agents: AgentRecord[]): Map<string, AgentRecord[]> {
+	const groups = new Map<string, AgentRecord[]>();
+	for (const a of agents) {
+		const key = a.phase ?? "";
+		const list = groups.get(key);
+		if (list) list.push(a);
+		else groups.set(key, [a]);
+	}
+	return groups;
+}
+
+export function renderWorkflowCall(
+	args: { name?: string; description?: string; phases?: string[] },
+	theme: Theme,
+): Text {
+	let text = theme.fg("toolTitle", theme.bold("workflow ")) + theme.fg("accent", args.name ?? "...");
+	if (args.description) {
+		const firstLine = args.description.split("\n")[0] ?? "";
+		text += theme.fg("dim", ` ${firstLine}`);
+	}
+	if (args.phases && args.phases.length > 0) {
+		text += `\n  ${theme.fg("muted", `phases: ${args.phases.join(" → ")}`)}`;
+	}
+	return new Text(text, 0, 0);
+}
+
+export function renderWorkflowResult(
+	result: AgentToolResult<WorkflowDetails>,
+	options: { expanded: boolean; isPartial?: boolean },
+	theme: Theme,
+): Container | Text {
+	const details = result.details;
+	if (!details) {
+		const first = result.content[0];
+		return new Text(first?.type === "text" ? first.text : "(no output)", 0, 0);
+	}
+
+	const { expanded } = options;
+	const running = details.agents.filter((a) => a.status === "running").length;
+	const queued = details.agents.filter((a) => a.status === "queued").length;
+	const failed = details.agents.filter((a) => a.status === "error").length;
+	const isRunning = running > 0 || queued > 0 || !details.finishedAt;
+
+	const headerIcon = details.scriptError
+		? theme.fg("error", "✗")
+		: details.aborted
+			? theme.fg("muted", "⊘")
+			: isRunning
+				? theme.fg("warning", "⏳")
+				: failed > 0
+					? theme.fg("warning", "◐")
+					: theme.fg("success", "✓");
+
+	const doneCount = details.agents.filter((a) => a.status === "done" || a.status === "cached").length;
+	const status = isRunning
+		? `${doneCount}/${details.agents.length} agents done, ${running} running${queued > 0 ? `, ${queued} queued` : ""}`
+		: `${doneCount}/${details.agents.length} agents`;
+
+	let header = `${headerIcon} ${theme.fg("toolTitle", theme.bold(details.name))} ${theme.fg("accent", status)}`;
+	if (details.aborted) header += ` ${theme.fg("muted", "[aborted]")}`;
+
+	const container = new Container();
+	container.addChild(new Text(header, 0, 0));
+
+	if (details.scriptError) {
+		container.addChild(new Text(theme.fg("error", details.scriptError), 0, 0));
+	}
+
+	for (const [phaseName, agents] of groupByPhase(details.agents)) {
+		if (phaseName) {
+			container.addChild(new Text(theme.fg("muted", `─── ${phaseName} ───`), 0, 0));
+		}
+		for (const a of agents) {
+			let line = `${statusIcon(a.status, theme)} ${theme.fg("accent", a.label)}`;
+			const usageStr = formatUsage(a.usage, a.model);
+			if (usageStr) line += ` ${theme.fg("dim", usageStr)}`;
+			container.addChild(new Text(line, 0, 0));
+			if (a.status === "error" && a.error) {
+				container.addChild(new Text(theme.fg("error", `  ${a.error}`), 0, 0));
+			}
+			if (expanded && a.output) {
+				container.addChild(new Markdown(a.output.trim(), 0, 0, getMarkdownTheme()));
+				container.addChild(new Spacer(1));
+			}
+		}
+	}
+
+	if (details.logs.length > 0) {
+		const logs = expanded ? details.logs : details.logs.slice(-COLLAPSED_LOG_COUNT);
+		const skipped = details.logs.length - logs.length;
+		container.addChild(new Text(theme.fg("muted", "─── log ───"), 0, 0));
+		if (skipped > 0) container.addChild(new Text(theme.fg("muted", `... ${skipped} earlier entries`), 0, 0));
+		for (const line of logs) {
+			container.addChild(new Text(theme.fg("dim", line), 0, 0));
+		}
+	}
+
+	if (expanded && details.returnValue !== undefined) {
+		container.addChild(new Text(theme.fg("muted", "─── result ───"), 0, 0));
+		const text =
+			typeof details.returnValue === "string"
+				? details.returnValue
+				: JSON.stringify(details.returnValue, null, 2);
+		container.addChild(new Text(theme.fg("toolOutput", text), 0, 0));
+	}
+
+	const total = aggregateUsage(details.agents);
+	const totalStr = formatUsage(total);
+	if (totalStr) {
+		container.addChild(new Text(theme.fg("dim", `Total: ${totalStr}`), 0, 0));
+	}
+	if (details.budget) {
+		const parts: string[] = [];
+		if (details.budget.maxCost !== undefined) {
+			parts.push(`$${total.cost.toFixed(4)} / $${details.budget.maxCost}`);
+		}
+		if (details.budget.maxTokens !== undefined) {
+			parts.push(`${formatTokens(total.input + total.output)} / ${formatTokens(details.budget.maxTokens)} tokens`);
+		}
+		container.addChild(new Text(theme.fg("dim", `Budget: ${parts.join(", ")}`), 0, 0));
+	}
+	if (!expanded && !isRunning) {
+		container.addChild(new Text(theme.fg("muted", "(Ctrl+O to expand)"), 0, 0));
+	}
+	return container;
+}