raga-cli 0.0.0-stage → 0.8.0

package/examples/extensions/jev-router.ts

@@ -0,0 +1,113 @@
+/**
+ * Jev router - a virtual model that plans on a strong model and implements on a cheap one.
+ *
+ * Registers `jev/auto`, which routes between three OpenAI Codex models:
+ *
+ * - Planning: GPT-5.6 Sol for complex work, GPT-5.6 Terra otherwise. The Jev classifier rates the
+ *   first user message; planning stays on the chosen model.
+ * - Implementation: GPT-5.6 Luna.
+ *
+ * The planning model explores, plans, and makes the first edit. After the first successful `edit`
+ * or `write` tool call, the next request of the same turn goes to Luna, and the session stays
+ * there. A session therefore switches models once and accepts a single prompt-cache miss.
+ *
+ * The phase is router state: Pi stores it on the session branch, so it follows the session tree
+ * and survives compaction. The selected thinking level passes through as the reasoning effort of
+ * the chosen model. Requests outside the agent loop, such as compaction summaries, go to Luna.
+ *
+ * Requires TypeSafe credentials (TYPESAFE_API_KEY) and an OpenAI Codex login.
+ * Usage: pi -e ./jev-router.ts --model jev/auto
+ */
+
+import type { Message } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext, ModelRoute, ModelRouteRequest } from "@earendil-works/pi-coding-agent";
+
+const PROVIDER = "openai-codex";
+const SOL = "gpt-5.6-sol";
+const TERRA = "gpt-5.6-terra";
+const LUNA = "gpt-5.6-luna";
+
+/** Tools whose successful result means implementation has started. */
+const EDIT_TOOLS = new Set(["edit", "write"]);
+
+interface JevState {
+	phase: "planning" | "implementation";
+	/** OpenAI Codex model for this phase. */
+	model: string;
+}
+
+type JevRequest = ModelRouteRequest<JevState>;
+
+function routeTo(request: JevRequest, ctx: ExtensionContext, id: string, state?: JevState): ModelRoute<JevState> {
+	const model = ctx.modelRegistry.find(PROVIDER, id);
+	if (!model) throw new Error(`Model ${PROVIDER}/${id} is not in the catalog`);
+	return { model, thinkingLevel: request.thinkingLevel, state };
+}
+
+function lastUserText(messages: readonly Message[]): string {
+	const content = messages.filter((message) => message.role === "user").at(-1)?.content ?? "";
+	if (typeof content === "string") return content;
+	return content.flatMap((block) => (block.type === "text" ? [block.text] : [])).join("\n");
+}
+
+/** Whether a tool call since the last user message edited a file successfully. */
+function editedThisTurn(messages: readonly Message[]): boolean {
+	const lastUser = messages.findLastIndex((message) => message.role === "user");
+	return messages
+		.slice(lastUser + 1)
+		.some((message) => message.role === "toolResult" && EDIT_TOOLS.has(message.toolName) && !message.isError);
+}
+
+/** Planning model for a new session: Sol for complex work, Terra otherwise or when Jev is unavailable. */
+async function choosePlanningModel(request: JevRequest, ctx: ExtensionContext): Promise<string> {
+	// Keep a planning model the session already uses, so switching to jev/auto costs no cache miss.
+	const previous = request.previous?.model;
+	if (previous?.provider === PROVIDER && (previous.id === SOL || previous.id === TERRA)) return previous.id;
+
+	const jev = ctx.modelRegistry.findOfType("classifier", "typesafe", "jev-latest");
+	if (!jev) return TERRA;
+	const result = await ctx.modelRegistry.classify(
+		jev,
+		{
+			state: { prompt: lastUserText(request.messages).slice(0, 16_000) },
+			questions: {
+				complexity: {
+					type: "choice",
+					instructions: "How demanding is the software engineering work requested in `prompt`?",
+					criteria: {
+						standard: "Ordinary features, fixes, reviews, or questions",
+						complex: "Subtle design, cross-cutting changes, or hard debugging",
+					},
+				},
+			},
+		},
+		{ signal: request.signal },
+	);
+	const answer = result.stopReason === "stop" ? result.answers.complexity : undefined;
+	return answer?.type === "choice" && (answer.probabilities.complex ?? 0) >= 0.5 ? SOL : TERRA;
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerVirtualModel<JevState>({
+		provider: "jev",
+		id: "auto",
+		name: "Auto (Jev)",
+		thinkingLevels: ["low", "medium", "high", "xhigh"],
+		// Shared by all three models; shown before the first response.
+		contextWindow: 272_000,
+		maxTokens: 128_000,
+		async route(request, ctx) {
+			if (request.reason === "direct") return routeTo(request, ctx, LUNA);
+			const state = request.state;
+			if (!state) {
+				const model = await choosePlanningModel(request, ctx);
+				return routeTo(request, ctx, model, { phase: "planning", model });
+			}
+			// The planning model made the first edit: hand the rest of the work to Luna.
+			if (state.phase === "planning" && editedThisTurn(request.messages)) {
+				return routeTo(request, ctx, LUNA, { phase: "implementation", model: LUNA });
+			}
+			return routeTo(request, ctx, state.model);
+		},
+	});
+}

package/examples/extensions/mac-system-theme.ts

@@ -0,0 +1,47 @@
+/**
+ * Syncs pi theme with macOS system appearance (dark/light mode).
+ *
+ * Usage:
+ *   pi -e examples/extensions/mac-system-theme.ts
+ */
+
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const execAsync = promisify(exec);
+
+async function isDarkMode(): Promise<boolean> {
+	try {
+		const { stdout } = await execAsync(
+			"osascript -e 'tell application \"System Events\" to tell appearance preferences to return dark mode'",
+		);
+		return stdout.trim() === "true";
+	} catch {
+		return false;
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	let intervalId: ReturnType<typeof setInterval> | null = null;
+
+	pi.on("session_start", async (_event, ctx) => {
+		let currentTheme = (await isDarkMode()) ? "dark" : "light";
+		ctx.ui.setTheme(currentTheme);
+
+		intervalId = setInterval(async () => {
+			const newTheme = (await isDarkMode()) ? "dark" : "light";
+			if (newTheme !== currentTheme) {
+				currentTheme = newTheme;
+				ctx.ui.setTheme(currentTheme);
+			}
+		}, 2000);
+	});
+
+	pi.on("session_shutdown", () => {
+		if (intervalId) {
+			clearInterval(intervalId);
+			intervalId = null;
+		}
+	});
+}

package/examples/extensions/message-renderer.ts

@@ -0,0 +1,59 @@
+/**
+ * Custom message rendering example.
+ *
+ * Shows how to use registerMessageRenderer to control how custom messages
+ * appear in the TUI, with colors, formatting, and expandable details.
+ *
+ * Usage: /status [message] - sends a status message with custom rendering
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+
+export default function (pi: ExtensionAPI) {
+	// Register custom renderer for "status-update" messages
+	pi.registerMessageRenderer("status-update", (message, { expanded, outputPad }, theme) => {
+		const details = message.details as { level: string; timestamp: number } | undefined;
+		const level = details?.level ?? "info";
+
+		// Color based on level
+		const color = level === "error" ? "error" : level === "warn" ? "warning" : "success";
+		const prefix = theme.fg(color, `[${level.toUpperCase()}]`);
+
+		let text = `${prefix} ${message.content}`;
+
+		// Show timestamp when expanded
+		if (expanded && details?.timestamp) {
+			const time = new Date(details.timestamp).toLocaleTimeString();
+			text += `\n${theme.fg("dim", `  at ${time}`)}`;
+		}
+
+		// Use Box with customMessageBg for consistent styling
+		const box = new Box(outputPad, 1, (t) => theme.bg("customMessageBg", t));
+		box.addChild(new Text(text, 0, 0));
+		return box;
+	});
+
+	// Command to send status messages
+	pi.registerCommand("status", {
+		description: "Send a status message (usage: /status [warn|error] message)",
+		handler: async (args, _ctx) => {
+			const parts = args.trim().split(/\s+/);
+			let level = "info";
+			let content = args.trim();
+
+			// Check for level prefix
+			if (parts[0] === "warn" || parts[0] === "error") {
+				level = parts[0];
+				content = parts.slice(1).join(" ") || "Status update";
+			}
+
+			pi.sendMessage({
+				customType: "status-update",
+				content,
+				display: true,
+				details: { level, timestamp: Date.now() },
+			});
+		},
+	});
+}

package/examples/extensions/minimal-mode.ts

@@ -0,0 +1,353 @@
+/**
+ * Minimal Mode Example - Demonstrates a "minimal" tool display mode
+ *
+ * This extension overrides built-in tools to provide custom rendering:
+ * - Collapsed mode: Only shows the tool call (command/path), no output
+ * - Expanded mode: Shows full output like the built-in renderers
+ *
+ * This demonstrates how a "minimal mode" could work, where ctrl+o cycles through:
+ * - Standard: Shows truncated output (current default)
+ * - Expanded: Shows full output (current expanded)
+ * - Minimal: Shows only tool call, no output (this extension's collapsed mode)
+ *
+ * Usage:
+ *   pi -e ./minimal-mode.ts
+ *
+ * Then use ctrl+o to toggle between minimal (collapsed) and full (expanded) views.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	createBashToolDefinition,
+	createEditToolDefinition,
+	createFindToolDefinition,
+	createGrepToolDefinition,
+	createLsToolDefinition,
+	createReadToolDefinition,
+	createWriteToolDefinition,
+	formatReadLineRange,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { homedir } from "os";
+
+/**
+ * Shorten a path by replacing home directory with ~
+ */
+function shortenPath(path: string): string {
+	const home = homedir();
+	if (path.startsWith(home)) {
+		return `~${path.slice(home.length)}`;
+	}
+	return path;
+}
+
+function createBuiltInTools(cwd: string) {
+	return {
+		read: createReadToolDefinition(cwd),
+		bash: createBashToolDefinition(cwd),
+		edit: createEditToolDefinition(cwd),
+		write: createWriteToolDefinition(cwd),
+		find: createFindToolDefinition(cwd),
+		grep: createGrepToolDefinition(cwd),
+		ls: createLsToolDefinition(cwd),
+	};
+}
+
+export default function (pi: ExtensionAPI) {
+	const tools = createBuiltInTools(process.cwd());
+
+	// =========================================================================
+	// Read Tool
+	// =========================================================================
+	pi.registerTool({
+		...tools.read,
+
+		renderCall(args, theme, _context) {
+			const path = shortenPath(args.path || "");
+			let pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
+
+			const lineRange = formatReadLineRange(args.offset, args.limit);
+			if (lineRange) {
+				pathDisplay += theme.fg("warning", lineRange);
+			}
+
+			return new Text(`${theme.fg("toolTitle", theme.bold("read"))} ${pathDisplay}`, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme, _context) {
+			// Minimal mode: show nothing in collapsed state
+			if (!expanded) {
+				return new Text("", 0, 0);
+			}
+
+			// Expanded mode: show full output
+			const textContent = result.content.find((c) => c.type === "text");
+			if (!textContent || textContent.type !== "text") {
+				return new Text("", 0, 0);
+			}
+
+			const lines = textContent.text.split("\n");
+			const output = lines.map((line) => theme.fg("toolOutput", line)).join("\n");
+			return new Text(`\n${output}`, 0, 0);
+		},
+	});
+
+	// =========================================================================
+	// Bash Tool
+	// =========================================================================
+	pi.registerTool({
+		...tools.bash,
+
+		renderCall(args, theme, _context) {
+			const command = args.command || "...";
+			const timeout = args.timeout as number | undefined;
+			const timeoutSuffix = timeout ? theme.fg("muted", ` (timeout ${timeout}s)`) : "";
+
+			return new Text(theme.fg("toolTitle", theme.bold(`$ ${command}`)) + timeoutSuffix, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme, _context) {
+			// Minimal mode: show nothing in collapsed state
+			if (!expanded) {
+				return new Text("", 0, 0);
+			}
+
+			// Expanded mode: show full output
+			const textContent = result.content.find((c) => c.type === "text");
+			if (!textContent || textContent.type !== "text") {
+				return new Text("", 0, 0);
+			}
+
+			const output = textContent.text
+				.trim()
+				.split("\n")
+				.map((line) => theme.fg("toolOutput", line))
+				.join("\n");
+
+			if (!output) {
+				return new Text("", 0, 0);
+			}
+
+			return new Text(`\n${output}`, 0, 0);
+		},
+	});
+
+	// =========================================================================
+	// Write Tool
+	// =========================================================================
+	pi.registerTool({
+		...tools.write,
+
+		renderCall(args, theme, _context) {
+			const path = shortenPath(args.path || "");
+			const pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
+			const lineCount = args.content ? args.content.split("\n").length : 0;
+			const lineInfo = lineCount > 0 ? theme.fg("muted", ` (${lineCount} lines)`) : "";
+
+			return new Text(`${theme.fg("toolTitle", theme.bold("write"))} ${pathDisplay}${lineInfo}`, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme, _context) {
+			// Minimal mode: show nothing (file was written)
+			if (!expanded) {
+				return new Text("", 0, 0);
+			}
+
+			// Expanded mode: show error if any
+			if (result.content.some((c) => c.type === "text" && c.text)) {
+				const textContent = result.content.find((c) => c.type === "text");
+				if (textContent?.type === "text" && textContent.text) {
+					return new Text(`\n${theme.fg("error", textContent.text)}`, 0, 0);
+				}
+			}
+
+			return new Text("", 0, 0);
+		},
+	});
+
+	// =========================================================================
+	// Edit Tool
+	// =========================================================================
+	pi.registerTool({
+		...tools.edit,
+		renderShell: "default",
+
+		renderCall(args, theme, _context) {
+			const path = shortenPath(args.path || "");
+			const pathDisplay = path ? theme.fg("accent", path) : theme.fg("toolOutput", "...");
+
+			return new Text(`${theme.fg("toolTitle", theme.bold("edit"))} ${pathDisplay}`, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme, _context) {
+			// Minimal mode: show nothing in collapsed state
+			if (!expanded) {
+				return new Text("", 0, 0);
+			}
+
+			// Expanded mode: show diff or error
+			const textContent = result.content.find((c) => c.type === "text");
+			if (!textContent || textContent.type !== "text") {
+				return new Text("", 0, 0);
+			}
+
+			// For errors, show the error message
+			const text = textContent.text;
+			if (text.includes("Error") || text.includes("error")) {
+				return new Text(`\n${theme.fg("error", text)}`, 0, 0);
+			}
+
+			// Otherwise show the text (would be nice to show actual diff here)
+			return new Text(`\n${theme.fg("toolOutput", text)}`, 0, 0);
+		},
+	});
+
+	// =========================================================================
+	// Find Tool
+	// =========================================================================
+	pi.registerTool({
+		...tools.find,
+
+		renderCall(args, theme, _context) {
+			const pattern = args.pattern || "";
+			const path = shortenPath(args.path || ".");
+			const limit = args.limit;
+
+			let text = `${theme.fg("toolTitle", theme.bold("find"))} ${theme.fg("accent", pattern)}`;
+			text += theme.fg("toolOutput", ` in ${path}`);
+			if (limit !== undefined) {
+				text += theme.fg("toolOutput", ` (limit ${limit})`);
+			}
+
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme, _context) {
+			if (!expanded) {
+				// Minimal: just show count
+				const textContent = result.content.find((c) => c.type === "text");
+				if (textContent?.type === "text") {
+					const count = textContent.text.trim().split("\n").filter(Boolean).length;
+					if (count > 0) {
+						return new Text(theme.fg("muted", ` → ${count} files`), 0, 0);
+					}
+				}
+				return new Text("", 0, 0);
+			}
+
+			// Expanded: show full results
+			const textContent = result.content.find((c) => c.type === "text");
+			if (!textContent || textContent.type !== "text") {
+				return new Text("", 0, 0);
+			}
+
+			const output = textContent.text
+				.trim()
+				.split("\n")
+				.map((line) => theme.fg("toolOutput", line))
+				.join("\n");
+
+			return new Text(`\n${output}`, 0, 0);
+		},
+	});
+
+	// =========================================================================
+	// Grep Tool
+	// =========================================================================
+	pi.registerTool({
+		...tools.grep,
+
+		renderCall(args, theme, _context) {
+			const pattern = args.pattern || "";
+			const path = shortenPath(args.path || ".");
+			const glob = args.glob;
+			const limit = args.limit;
+
+			let text = `${theme.fg("toolTitle", theme.bold("grep"))} ${theme.fg("accent", `/${pattern}/`)}`;
+			text += theme.fg("toolOutput", ` in ${path}`);
+			if (glob) {
+				text += theme.fg("toolOutput", ` (${glob})`);
+			}
+			if (limit !== undefined) {
+				text += theme.fg("toolOutput", ` limit ${limit}`);
+			}
+
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme, _context) {
+			if (!expanded) {
+				// Minimal: just show match count
+				const textContent = result.content.find((c) => c.type === "text");
+				if (textContent?.type === "text") {
+					const count = textContent.text.trim().split("\n").filter(Boolean).length;
+					if (count > 0) {
+						return new Text(theme.fg("muted", ` → ${count} matches`), 0, 0);
+					}
+				}
+				return new Text("", 0, 0);
+			}
+
+			// Expanded: show full results
+			const textContent = result.content.find((c) => c.type === "text");
+			if (!textContent || textContent.type !== "text") {
+				return new Text("", 0, 0);
+			}
+
+			const output = textContent.text
+				.trim()
+				.split("\n")
+				.map((line) => theme.fg("toolOutput", line))
+				.join("\n");
+
+			return new Text(`\n${output}`, 0, 0);
+		},
+	});
+
+	// =========================================================================
+	// Ls Tool
+	// =========================================================================
+	pi.registerTool({
+		...tools.ls,
+
+		renderCall(args, theme, _context) {
+			const path = shortenPath(args.path || ".");
+			const limit = args.limit;
+
+			let text = `${theme.fg("toolTitle", theme.bold("ls"))} ${theme.fg("accent", path)}`;
+			if (limit !== undefined) {
+				text += theme.fg("toolOutput", ` (limit ${limit})`);
+			}
+
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme, _context) {
+			if (!expanded) {
+				// Minimal: just show entry count
+				const textContent = result.content.find((c) => c.type === "text");
+				if (textContent?.type === "text") {
+					const count = textContent.text.trim().split("\n").filter(Boolean).length;
+					if (count > 0) {
+						return new Text(theme.fg("muted", ` → ${count} entries`), 0, 0);
+					}
+				}
+				return new Text("", 0, 0);
+			}
+
+			// Expanded: show full listing
+			const textContent = result.content.find((c) => c.type === "text");
+			if (!textContent || textContent.type !== "text") {
+				return new Text("", 0, 0);
+			}
+
+			const output = textContent.text
+				.trim()
+				.split("\n")
+				.map((line) => theme.fg("toolOutput", line))
+				.join("\n");
+
+			return new Text(`\n${output}`, 0, 0);
+		},
+	});
+}

package/examples/extensions/modal-editor.ts

@@ -0,0 +1,85 @@
+/**
+ * Modal Editor - vim-like modal editing example
+ *
+ * Usage: pi --extension ./examples/extensions/modal-editor.ts
+ *
+ * - Escape: insert → normal mode (in normal mode, aborts agent)
+ * - i: normal → insert mode
+ * - hjkl: navigation in normal mode
+ * - ctrl+c, ctrl+d, etc. work in both modes
+ */
+
+import { CustomEditor, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+// Normal mode key mappings: key -> escape sequence (or null for mode switch)
+const NORMAL_KEYS: Record<string, string | null> = {
+	h: "\x1b[D", // left
+	j: "\x1b[B", // down
+	k: "\x1b[A", // up
+	l: "\x1b[C", // right
+	"0": "\x01", // line start
+	$: "\x05", // line end
+	x: "\x1b[3~", // delete char
+	i: null, // insert mode
+	a: null, // append (insert + right)
+};
+
+class ModalEditor extends CustomEditor {
+	private mode: "normal" | "insert" = "insert";
+
+	handleInput(data: string): void {
+		// Escape toggles to normal mode, or passes through for app handling
+		if (matchesKey(data, "escape")) {
+			if (this.mode === "insert") {
+				this.mode = "normal";
+			} else {
+				super.handleInput(data); // abort agent, etc.
+			}
+			return;
+		}
+
+		// Insert mode: pass everything through
+		if (this.mode === "insert") {
+			super.handleInput(data);
+			return;
+		}
+
+		// Normal mode: check mapped keys
+		if (data in NORMAL_KEYS) {
+			const seq = NORMAL_KEYS[data];
+			if (data === "i") {
+				this.mode = "insert";
+			} else if (data === "a") {
+				this.mode = "insert";
+				super.handleInput("\x1b[C"); // move right first
+			} else if (seq) {
+				super.handleInput(seq);
+			}
+			return;
+		}
+
+		// Pass control sequences (ctrl+c, etc.) to super, ignore printable chars
+		if (data.length === 1 && data.charCodeAt(0) >= 32) return;
+		super.handleInput(data);
+	}
+
+	render(width: number): string[] {
+		const lines = super.render(width);
+		if (lines.length === 0) return lines;
+
+		// Add mode indicator to bottom border
+		const label = this.mode === "normal" ? " NORMAL " : " INSERT ";
+		const last = lines.length - 1;
+		if (visibleWidth(lines[last]!) >= label.length) {
+			lines[last] = truncateToWidth(lines[last]!, width - label.length, "") + label;
+		}
+		return lines;
+	}
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.on("session_start", (_event, ctx) => {
+		ctx.ui.setEditorComponent((tui, theme, kb) => new ModalEditor(tui, theme, kb));
+	});
+}

package/examples/extensions/model-status.ts

@@ -0,0 +1,31 @@
+/**
+ * Model status extension - shows model changes in the status bar.
+ *
+ * Demonstrates the `model_select` hook which fires when the model changes
+ * via /model command, Ctrl+P cycling, or session restore.
+ *
+ * Usage: pi -e ./model-status.ts
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+	pi.on("model_select", async (event, ctx) => {
+		const { model, previousModel, source } = event;
+
+		// Format model identifiers
+		const next = `${model.provider}/${model.id}`;
+		const prev = previousModel ? `${previousModel.provider}/${previousModel.id}` : "none";
+
+		// Show notification on change
+		if (source !== "restore") {
+			ctx.ui.notify(`Model: ${next}`, "info");
+		}
+
+		// Update status bar with current model
+		ctx.ui.setStatus("model", `🤖 ${model.id}`);
+
+		// Log change details (visible in debug output)
+		console.log(`[model_select] ${prev} → ${next} (${source})`);
+	});
+}